Advertiser Management

Documentation for all functionality to manage advertisers using the Revive Adserver REST API (get a list of advertisers, get one advertiser, add an advertiser, modify an advertiser, delete an advertiser).

getAdvertiserListByAgencyID

Description: Get a list of all advertisers associated with an agency by providing the agency ID

Implementation: URL/adv/agc/[agencyId]

Method: GET

Json example

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

Response example

[
    {
        "advertiserId": "1",
        "accountId": "3",
        "agencyId": "1",
        "advertiserName": "Demo Advertiser 1",
        "contactName": "Demo Advertiser 1",
        "emailAddress": "noreply@reviveadserverrestapi.com",
        "comments": ""
    },
    {
        "advertiserId": "2",
        "accountId": "8",
        "agencyId": "1",
        "advertiserName": "Statistics Demo Advertiser",
        "contactName": "Revive Adserver REST API",
        "emailAddress": "info@reviveadserverrestapi.com",
        "comments": ""
    }
]

Notes

  • Starting with v4.1.0, this method returns an unnamed array of all advertisers (breaking change).
  • Requesting a list of advertisers for an agency that has no advertisers returns an empty array:
    []
  • Requesting a list of advertisers for an agency that does not exist returns:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown agencyId Error"
        }
    }

getAdvertiser

Description: Get the details of an existing advertiser, by providing the advertiser’s ID

Implementation: URL/adv/[advertiserId]

Method: GET

Json example

Method: 
    GET http://api.example.com/adv/2

Response example

{
    "advertiserId": "2",
    "accountId": "8",
    "agencyId": "1",
    "advertiserName": "Statistics Demo Advertiser",
    "contactName": "Revive Adserver REST API",
    "emailAddress": "info@reviveadserverrestapi.com",
    "comments": ""
}

Notes

  • Requesting an non-existent advertiser returns the following response:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown advertiserId Error"
        }
    }

addAdvertiser

Description: Add new advertiser

Implementation: URL/adv/new

Method: POST/PUT

Requested parameters

addAdvertiser
Name Description Allowed Values Required / Optional Default
advertiserName name of the advertiser string required
contactName contact name string optional null
emailAddress email address string optional null
comments comments string optional null

Json example

Method: 
    POST http://api.example.com/adv/new
Request Header:
    Content-Type:text/javascript
Request Body:
{
  "advertiserName":"New Advertiser",
  "contactName":"John Doe",
  "emailAddress":"john.doe@example.com",
  "username":"test",
  "password":"test"
}

Response example

{
    "advertiserId": 3,
    "accountId": 10,
    "agencyId": 1,
    "advertiserName": "New Advertiser",
    "contactName": "John Doe",
    "emailAddress": "john.doe@example.com",
    "comments": null
}

Notes

Starting with v4.0, the addAdvertiser function will return full details of the newly created advertiser, 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.

modifyAdvertiser

Description: Modify an existing advertiser

Implementation: URL/adv/[advertiserId]

Method: POST/PUT

Request parameters:

modifyAdvertiser
Name Description Allowed Values Required / Optional Default
advertiserName name of the advertiser string optional null
contactName contact name string optional null
emailAddress email address string optional null
comments comments string optional null

Json example

Method: 
    POST http://api.example.com/adv/3
Request Header:
    Content-Type:text/javascript
Request Body:
{
  "advertiserName":"Modified Advertiser",
  "contactName":"Jane Doe",
  "emailAddress":"jane.doe@example.com"
}

Response example

{
    "advertiserId": 3,
    "accountId": 10,
    "agencyId": 1,
    "advertiserName": "Modified Advertiser",
    "contactName": "Jane Doe",
    "emailAddress": "jane.doe@example.com",
    "comments": ""
}

Notes

  • Trying to modify an non-existent advertiser will return:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown advertiserId Error"
        }
    }
  • Trying to modify an advertiser with an incorrect or missing request body will return:
    {
        "error": {
            "type": "Exception",
            "message": "Sent parameters are not properly formatted"
        }
    }

deleteAdvertiser

Description: Delete an existing advertiser

Implementation: URL/adv/[advertiserId]

Method: DELETE

Json example

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

Response example

{"OK"}

Notes

  • Trying to delete an non-existent advertiser will return:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown advertiserId Error"
        }
    }

Current version

The most recently released version of the Revive Adserver REST API is v5.1.0 (publication date April 15, 2022).

See Release Notes

Compatibility

Revive Adserver REST API is compatible with all versions of Revive Adserver v4.x, and v5.x. 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 PHP 7 and PHP  8.

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