User REST API | Documentation

This API allows more privileged users to manage users within the Cxense Advertising system. To create and invite new users, control which sections of the Folder tree they should be granted access to and the operations they should be allowed to perform there.

Individual users

The GET, PUT, and DELETE operations are supported for individual users.

GET

Retrieve an existing user in the XML format described below. Throws an error if a user with the specified userId does not exist.

https://{cxadbaseurl}/api/secure/user/{userId}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system
userId - the unique id for the user to be retrieved.

This XML example shows the contents returned from a typical GET call:

<?xml version="1.0"?>
<cx:user xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:userId>00000000000292a5</cx:userId>
  <cx:homeFolderId>000000000005a929</cx:homeFolderId>
  <cx:username>jsmith</cx:username>
  <cx:firstName>John</cx:firstName>
  <cx:surname>Smith</cx:surname>
  <cx:email>jsmith@emaildomain.com</cx:email>
  <cx:question>What is you mother's maiden name?</cx:question>
  <cx:answer>Jones</cx:answer>
  <cx:openIdUrl>http://www.domain.com/profiles/111222333444555666777</cx:openIdUrl>
  <cx:signUpDate>2012-10-31T02:24:36.203Z</cx:signUpDate>
  <cx:signUpIpAddress>127.0.0.1</cx:signUpIpAddress>
  <cx:enabled>true</cx:enabled>
  <cx:currencyCode>AUD</cx:currencyCode>
  <cx:locale>en_AU</cx:locale>
  <cx:timeZone>Australia/Melbourne</cx:timeZone>
  <cx:rowsPerPage>10</cx:rowsPerPage>
</cx:user>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET https://cxad.cxense.com/api/secure/user/0000000000004a94

PUT

Update the contents of an existing user with data taken from the request payload. Throws an error if the userId does not exist.

https://{cxadbaseurl}/api/secure/user/{userId}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system
userId - the unique id for the user to be retrieved.

This XML example shows the contents required to be supplied for a PUT call (note: neither a user's username nor their password can be updated once they have been created, if either of these values are included in the PUT request payload they will be ignored):

<?xml version="1.0"?>
<cx:user xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:firstName>Bob</cx:firstName>
  <cx:surname>Robertson</cx:surname>
  <cx:email>bob@therrobertsons.com</cx:email>
  <cx:question>What is the meaning of life?</cx:question>
  <cx:answer>42</cx:answer>
  <cx:openIdUrl>http://www.therrobertsons.com/profiles/bob007</cx:openIdUrl>
  <cx:enabled>true</cx:enabled>
  <cx:currencyCode>AUD</cx:currencyCode>
  <cx:locale>en_AU</cx:locale>
  <cx:timeZone>Australia/Melbourne</cx:timeZone>
  <cx:rowsPerPage>10</cx:rowsPerPage>
</cx:user>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X PUT https://cxad.cxense.com/api/secure/user/{userId} -d @input.xml

DELETE

Remove an existing user.

https://{cxadbaseurl}/api/secure/user/{userId}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system
userId - the unique id for the user to be deleted.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X DELETE https://cxad.cxense.com/api/secure/user/0000000000004a94

Retrieving the list of existing users

The GET operation is supported for existing users.

GET

Retrieve the list of existing users that the currently authenticated user is authorised to read and/or modify.

https://{cxadbaseurl}/api/secure/users

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system

This XML example shows the contents returned from a typical GET call:

<?xml version="1.0"?>
<cx:users xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:user>
    <cx:userId>00000000000292bf</cx:userId>
    <cx:homeFolderId>00000000000fb929</cx:homeFolderId>
    <cx:username>agencyOwner</cx:username>
    <cx:firstName>Alice</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>alice@example.com</cx:email>
    <cx:question>Why is the sky blue?</cx:question>
    <cx:answer>Refraction of sunlight</cx:answer>
    <cx:openIdUrl>http://www.domain.com/profiles/111222333444555666777</cx:openIdUrl>
    <cx:signUpDate>2012-05-01T09:05:20.100Z</cx:signUpDate>
    <cx:signUpIpAddress>192.168.0.10</cx:signUpIpAddress>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
  <cx:user>
    <cx:userId>00000000000292c1</cx:userId>
    <cx:homeFolderId>000000000001c929</cx:homeFolderId>
    <cx:username>agencyUser</cx:username>
    <cx:firstName>Bob</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>bob@example.com</cx:email>
    <cx:question>Why is the sea blue?</cx:question>
    <cx:answer>Reflection of the sky</cx:answer>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
  <cx:user>
    <cx:userId>00000000000292c3</cx:userId>
    <cx:homeFolderId>000000000003c929</cx:homeFolderId>
    <cx:username>advertiser1</cx:username>
    <cx:firstName>Charlie</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>charlie@example.com</cx:email>
    <cx:question>What time is it?</cx:question>
    <cx:answer>Dinner time</cx:answer>
    <cx:openIdUrl>http://www.domain.com/profiles/777666555444333222111</cx:openIdUrl>
    <cx:signUpDate>2012-10-31T02:24:36.203Z</cx:signUpDate>
    <cx:signUpIpAddress>127.0.0.1</cx:signUpIpAddress>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
  <cx:user>
    <cx:userId>00000000000292c5</cx:userId>
    <cx:homeFolderId>000000000005c929</cx:homeFolderId>
    <cx:username>publisher1</cx:username>
    <cx:firstName>Dave</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>dave@example.com</cx:email>
    <cx:question>What is Friday?</cx:question>
    <cx:answer>Hawaiian shirt day</cx:answer>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
  <cx:user>
    <cx:userId>00000000000292c7</cx:userId>
    <cx:homeFolderId>000000000007c929</cx:homeFolderId>
    <cx:username>fullServAd</cx:username>
    <cx:firstName>Eve</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>eve@example.com</cx:email>
    <cx:question>What is you favourite fruit?</cx:question>
    <cx:answer>Oranges</cx:answer>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
  <cx:user>
    <cx:userId>00000000000292c9</cx:userId>
    <cx:homeFolderId>00000000009c929</cx:homeFolderId>
    <cx:username>fullServPub</cx:username>
    <cx:firstName>Fran</cx:firstName>
    <cx:surname>Smith</cx:surname>
    <cx:email>fran@example.com</cx:email>
    <cx:question>WHat is you favourite colour?</cx:question>
    <cx:answer>Green</cx:answer>
    <cx:openIdUrl>http://www.domain.com/profiles/111111111111111111111</cx:openIdUrl>
    <cx:enabled>true</cx:enabled>
    <cx:currencyCode>AUD</cx:currencyCode>
    <cx:locale>en_AU</cx:locale>
    <cx:timeZone>UTC</cx:timeZone>
    <cx:rowsPerPage>10</cx:rowsPerPage>
  </cx:user>
</cx:users>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET https://cxad.cxense.com/api/secure/users

Retrieving the list of available Groups

The GET operation is supported for available groups.

GET

Retrieve the list of groups that the currently authenticated user is authorised to manage.

When adding new users (see the Inviting a new user and Creating a new user sections below) the group(s) that are to be assigned to the new user are specified in the request XML payload. The current user is only allowed to assign new users to those groups that they themselves are authorised to manage, the list of which can be retrieved using this API method call.

https://{cxadbaseurl}/api/secure/groups

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system

This XML example shows the contents returned from a typical GET call:

<?xml version="1.0"?>
<cx:groups xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:group>ADACCOUNTMANAGER</cx:group>
  <cx:group>ADHELPDESK</cx:group>
  <cx:group>FULLSERVAD</cx:group>
  <cx:group>SELFSERVAD</cx:group>
</cx:groups>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET https://cxad.cxense.com/api/secure/groups

Inviting a new user

The POST operation is supported for inviting a new user.

POST

Add a new user to Cxense Advertising and invite them to the home container of the currently authenticated user.

For more information on inviting a new user please refer to Invite User.

https://{cxadbaseurl}/api/secure/inviteUser

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system

This XML example shows the contents required to be supplied for a POST call:

<?xml version="1.0"?>
<cx:newUser xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:user>
    <cx:username>ziggy</cx:username>
    <cx:password>password1</cx:password>
    <cx:firstName>Ziggy</cx:firstName>
    <cx:surname>Stardust</cx:surname>
    <cx:email>ziggy@example.com</cx:email>
    <cx:question>What is the meaning of life</cx:question>
    <cx:answer>42</cx:answer>
    <cx:openIdUrl>http://www.domain.com/profiles/111222333444555666777</cx:openIdUrl>
    <cx:signUpDate>2012-10-31T02:24:36.203Z</cx:signUpDate>
    <cx:signUpIpAddress>127.0.0.1</cx:signUpIpAddress>
  </cx:user>
  <cx:groups>
    <cx:group>ADACCOUNTMANAGER</cx:group>
    <cx:group>FULLSERVAD</cx:group>
  </cx:groups>
  <cx:sendEmailNotification>false</cx:sendEmailNotification>
</cx:newUser>

In order to avoid a notification email being sent to the new user the sendEmailNotification element must be specified in the request XML with a value of "false". If not specified this value will default to "true" and an email will be sent to the provided email address informing the user that they have been invited to join the Cxense Advertising system and directing them to a Cxense Advertising page where they must complete their registration.

When sendEmailNotification is set to true only the username and email fields are required in the request payload.

When sendEmailNotification is set to false ALL fields required for a Cxense Advertising User must be included in the request payload (as per the example above).

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X POST https://cxad.cxense.com/api/secure/inviteUser -d @input.xml

Creating a new user

The POST operation is supported for creating a new user.

POST

Add a new user to Cxense Advertising as a sub-user of the currently authenticated user.

For more information on creating a new user please refer to Creating a New User.

https://{cxadbaseurl}/api/secure/createUser

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system

This XML example shows the contents required to be supplied for a POST call:

<?xml version="1.0"?>
<cx:newUser xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:user>
    <cx:username>zorro</cx:username>
    <cx:password>password1</cx:password>
    <cx:firstName>Don Diego</cx:firstName>
    <cx:surname>Vega</cx:surname>
    <cx:email>zorro@maskedvigilantes.com</cx:email>
    <cx:question>Weapon of choice?</cx:question>
    <cx:answer>Rapier</cx:answer>
    <cx:openIdUrl>http://www.domain.com/profiles/111222333444555666777</cx:openIdUrl>
    <cx:signUpDate>2012-10-31T02:24:36.203Z</cx:signUpDate>
    <cx:signUpIpAddress>127.0.0.1</cx:signUpIpAddress>
  </cx:user>
  <cx:groups>
    <cx:group>AGENCY</cx:group>
    <cx:group>SELFSERVAD</cx:group>
    <cx:group>FULLSERVAD</cx:group>
  </cx:groups>
  <cx:sendEmailNotification>false</cx:sendEmailNotification>
</cx:newUser>

User role selection

When selecting the roles that your new user is to be created with, please note that the Advertising Analyst (ADANALYST), Full Service Advertiser (FULLSERVAD) and Full Service Publisher (FULLSERVPUB) roles are treated as "Invite Only".

This means that a user cannot be created with only one or more of these roles. They can be created with any of the other roles as well as one or more of these Invite Only roles but they cannot be created with just Invite Only role(s).

The reason being that Invite Only roles are effectively read-only, they do not provide the user with the ability to create any inventory in the system. Creating a user with only these roles would add them to Cxense Advertising in a new, empty home container in which they would be unable to perform any actions making their account, effectively, non-functional.

In order to avoid a notification email being sent to the new user the sendEmailNotification element must be specified in the request XML with a value of "false". If not specified this value will default to "true" and an email will be sent to the provided email address informing the user that they have been created in the Cxense Advertising system and directing them to a Cxense Advertising page where they must complete their registration.

When sendEmailNotification is set to true only the username and email fields are required in the request payload.

When sendEmailNotification is set to false ALL fields required for a Cxense Advertising User must be included in the request payload (as per the example above).

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X POST https://cxad.cxense.com/api/secure/createUser -d @input.xml

Reseting a user's password

The PUT operation is supported for reseting the password for a particular user.

PUT

Update a particular user's password to a new value. Throws an error if the user performing the operation is not authorised to modify the nominated user.

https://{cxadbaseurl}/api/secure/resetPassword/{userId}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system
userId - the unique id for the user whose password is to be reset

This XML example shows the contents required to be supplied for a PUT call:

<?xml version="1.0"?>
<cx:password xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:newPassword>p4ssw0rd2</cx:newPassword>
</cx:password>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X PUT https://cxad.cxense.com/api/secure/resetPassword -d @input.xml

Changing the current user's password

The PUT operation is supported for changing the password of the user accessing the REST API.

PUT

Update the current user's password from an its current, or "old", value to a new value. Throws an error if the provided old password value is not correct.

https://{cxadbaseurl}/api/secure/changePassword

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system

This XML example shows the contents required to be supplied for a PUT call:

Click to view XML example

<?xml version="1.0"?>
<cx:password xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:oldPassword>password1</cx:oldPassword>
  <cx:newPassword>p4ssw0rd2</cx:newPassword>
</cx:password>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X PUT https://cxad.cxense.com/api/secure/changePassword -d @input.xml

Last updated: January 19, 2022