User management

getUserListByAccountId

Description: Get a list of all existing users in an account, by providing the account ID

Implementation: URL/usr/acc/[accountId]

Method: GET

Json example

Method: 
    GET http://api.example.com/usr/acc/X

Response example

[
    {
        "userId": "21",
        "contactName": "John Doe",
        "emailAddress": "john.doe@example.com",
        "username": "johndoe",
        "password": null,
        "defaultAccountId": "2",
        "active": "1"
    },
abbreviated for clarity, additional entries could appear here
]

Note

Note the terms account and agency are related but different. Due to a terminology change, end users see accounts in the user interface, but these used to be called ‘agency’ in the past. For reasons of backward compatibility, the API continues to use the term agency.

The ID to be used in the request is the account ID of the agency. Please consult the documentation about managing accounts to find out how agencies and accounts are tied together.

In most cases, account ID 1 is reserved for the ‘system administrator’ type account.

getUser

Description: Get the detail of a specific user, requesting by user ID

Implementation: URL/usr/[userId]

Method: GET

Json example

Method: 
    GET http://api.example.com/usr/4

Response example

{
    "userId": "21",
    "contactName": "John Doe",
    "emailAddress": "john.doe@example.com",
    "username": "johndoe",
    "password": null,
    "defaultAccountId": "2",
    "active": "1"
}

addUser

Description: Add a new user

Implementation: URL/usr/new

Method: POST/PUT

Json example

Method: 
    POST http://api.example.com/usr/new
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "contactName": "John Doe",
        "emailAddress": "john.doe@example.com",
        "defaultAccountId": 2,
        "username": "johndoe",
        "password": "somepassword"
    }

Notes

When using the Revive Adserver REST API version 5.1.0 or higher, in combination with Revive Adserver v5.4.0 or higher, the password field is not mandatory. Omitting the password means that the “welcome new user” email gets sent to the new user, containing instructions to set their initial password. See the Release Notes on Revive Adserver REST API v5.1.0 and the Notes on changes to password functionality in Revive Adserver v5.4.0 for more information.

modifyUser

Description: Modify an existing user

Implementation: URL/usr/[userId]

Method: POST/PUT

See the addUser method above for additional information.

deleteUser

Description: Delete an existing user

Implementation: URL/usr/[userId]

Method: DELETE

Json example

Method:

DELETE http://api.example.com/usr/X

setPermissions

Description: Set the permissions of a user relative to an account

Implementation: URL/usr/[userId]/lnk

Method: POST

Json example

Method:

POST http://api.example.com/usr/X/link

Request Header:

Content-Type:text/javascript

Request Body:

{
  "type": "ADMIN|MANAGER|ADVERTISER|TRAFFICKER",
  "accountId": X,
  "permissions": [
    10,
    12
   ]
}

Notes

The setPermissions method is new starting with Revive Adserver REST API v5.1.0 and works only in combination with Revive Adserver v5.4.0 or higher.

A list of values allowed for permissions can be found in the Github repository of the Revive Adserver software. In the example above, the values 10 indicates that the user has the ‘super account’ permission, meaning the user is allowed to create, manage, and delete other usernames. The value 12 indicates that the user has permission to delete inventory items.

Each POST will reset the permissions, so an empty array as permissions, or even omitting it will do the trick of removing the permissions of an existing user.

At the time of this writing, it is not yet possible to ‘unlink’ a user from an account using the Revive Adserver REST API, nor to retrieve the user’s permissions and linked accounts.