Agency management

Documentation for all functionality to manage agencies using the Revive Adserver REST API (list agencies, request agency details, add an agency, modify an agency, delete an agency)

getAgencyList

Description: Get a list of all existing agencies

Implementation: URL/agc/lst

Method: GET

Json example:

Method: 
    GET http://api.example.com/agc/lst

response example

[
    {
        "agencyId": "1",
        "accountId": "2",
        "agencyName": "Revive Adserver REST API demo account",
        "contactName": "Revive Adserver REST API team",
        "emailAddress": "noreply@reviveadserverrestapi.com"
    }
]

Note

The REST API response may include a field ‘password’. This comes from the API inside Revive Adserver, even though there isn’t a password associated with an account/agency. The value for ‘password’ being returned is always ‘null’. Developers can ignore this ‘password’ in the response.

getAgency

Description: Get the details of one specific agency

Implementation: URL/agc/[agencyId]

Method: GET

Json example:

Method: 
    GET http://api.example.com/agc/1

response example

{
    "agencyId": "1",
    "accountId": "2",
    "agencyName": "Revive Adserver REST API demo account",
    "contactName": "Revive Adserver REST API team",
    "emailAddress": "noreply@reviveadserverrestapi.com"
}

Response when requesting a non-existent agency

{
    "error": {
        "type": "Exception",
        "message": "Unknown agencyId Error"
    }
}

Note

The REST API response may include a field ‘password’. This comes from the API inside Revive Adserver, even though there isn’t a password associated with an account/agency. The value for ‘password’ being returned is always ‘null’. Developers can ignore this ‘password’ in the response.

addAgency

Description: Add a new agency

Implementation: URL/agc/new

Method: POST/PUT

Parameters:

Name Description Allowed Values Required / Optional Default
agencyName name of the agency string required
contactName contact name string required
emailAddress email address string required

 

Json example:

Method: 
    POST http://api.example.com/agc/new
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "agencyName":"Some additional account",
        "contactName":"Revive Adserver REST API team",
        "emailAddress":"noreply@reviveadserverrestapi.com"
    }

note

Starting with v4.0, the addAgency function will return full details of the newly created agency, instead of just {“OK”}. This enables developers to quickly retrieve the ID of the newly created entity, and to check the default values assigned to attributes that were not included in the call to create the new entity.

response example

[
    {
        "agencyId": "2",
        "accountId": "3",
        "agencyName": "Some additional account",
        "contactName": "Revive Adserver REST API team",
        "emailAddress": "noreply@reviveadserverrestapi.com"
    }
]

Note

The REST API response may include a field ‘password’. This comes from the API inside Revive Adserver, even though there isn’t a password associated with an account/agency. The value for ‘password’ being returned is always ‘null’. Developers can ignore this ‘password’ in the response.

modifyAgency

Description: Modify an existing agency

Implementation: URL/agc/[agencyId]

Method: POST/PUT

Requested parameters:

modifyAgency
Name Description Allowed Values Required / Optional Default
agencyName name of the agency string optional
contactName contact name string optional null
emailAddress email address string optional null

Json example:

Method: 
    POST http://api.example.com/agc/3
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "agencyName":"Test new Agency creation - modified",
        "contactName":"Peter B Pan"
    }

Notes

Trying to modify an agency that does not exist, results in the following response:

{
    "error": {
        "type": "Exception",
        "message": "Unknown agencyId Error"
    }
}

The REST API response may include a field ‘password’. This comes from the API inside Revive Adserver, even though there isn’t a password associated with an account/agency. The value for ‘password’ being returned is always ‘null’. Developers can ignore this ‘password’ in the response.

deleteAgency

Description: Delete an existing agency

Implementation: URL/agc/[agencyId]

Method: DELETE

Json example:

Method: 
    DELETE http://api.example.com/agc/3

Notes

When deleting an existing agency, the API responds with the following success message:

{"OK"}

Trying to delete an agency that does not exist, results in the following response:

{
    "error": {
        "type": "Exception",
        "message": "Unknown agencyId Error"
    }
}

Current version

The most recently released version of the Revive Adserver REST API is v4.5.0 (publication date November 28, 2018).

See Release Notes

Compatibility

Revive Adserver REST API is compatible with all versions of Revive Adserver v4.0 and higher. It may also be compatible with Revive Adserver v3.x (and also with OpenX Source v2.8 and higher), but this can not be guaranteed.

Revive Adserver REST API is compatible with all supported versions of PHP, including PHP7.

Also see Technical Requirements, Product Content, and Installation Instructions.

Our Recent Tweets