Campaign Management

Documentation for all functionality to manage campaigns using the Revive Adserver REST API (get a list of all campaigns for an advertiser, get the details of a specific campaign, add a campaign, modify a campaign, delete a campaign, get a list of all the zones a campaign is linked to).

Campaigns represent a very powerful but also complex feature of the Revive Adserver software. See the special page about all fields and properties to get a full picture of the available options for campaigns.

getCampaignListByAdvertiserID

Description: Returns the existing campaigns under the requested advertiser

Implementation: URL/cam/adv/[advertiserId]

Method: GET

Json example

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

Notes

  • Requesting the campaigns of a non-existent advertiser will return:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown advertiserId Error"
        }
    }

getCampaign

Description: Get the details of one specific campaign Implementation: URL/cam/[campaignId] Method: GET

Json example

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

Response example

{
    "campaignId": "1",
    "advertiserId": "1",
    "campaignName": "Demo Campaign 1 - remnant",
    "startDate": {
        "year": "2017",
        "month": "01",
        "day": "01",
        "hour": 0,
        "minute": 0,
        "second": 0,
        "partsecond": 0,
        "tz": {
            "id": "UTC",
            "longname": "Coordinated Universal Time",
            "shortname": "UTC",
            "hasdst": false,
            "dstlongname": "Coordinated Universal Time",
            "dstshortname": "UTC",
            "offset": 0,
            "default": null
        }
    },
    "endDate": {
        "year": "2031",
        "month": "12",
        "day": "31",
        "hour": 23,
        "minute": 59,
        "second": 59,
        "partsecond": 0,
        "tz": {
            "id": "UTC",
            "longname": "Coordinated Universal Time",
            "shortname": "UTC",
            "hasdst": false,
            "dstlongname": "Coordinated Universal Time",
            "dstshortname": "UTC",
            "offset": 0,
            "default": null
        }
    },
    "impressions": "-1",
    "clicks": "-1",
    "priority": "0",
    "weight": "1",
    "targetImpressions": "0",
    "targetClicks": "0",
    "targetConversions": "0",
    "revenue": "10.0000",
    "revenueType": "1",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "comments": "",
    "viewWindow": "864000",
    "clickWindow": "86400"
}

Notes

addCampaign

Description: Add a new campaign
Implementation: URL/cam/new
Method: POST/PUT

Pro tips

See our special page with details about campaign properties and the corresponding fields in the REST API.

The easiest way to find out which campaign parameters exist, but more importantly in which combination they work together, is to create a campaign in the Revive Adserver user interface, and then to retrieve the details of that campaign through the API using the getCampaign method described above. This will show all campaign parameters as entered, but now returned in JSON formatting. This is particularly useful to find out how to combine things like campaign type, start date, end date and number of impressions (for example).

Json example

Method: 
    POST http://api.example.com/cam/new
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "advertiserId": 1,
        "campaignName": "New campaign",
        "weight": 1,
        "startDate": "2018-09-01",
        "endDate": "2018-12-31"
    }

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

modifyCampaign

Description: Modify an existing campaign

Implementation: URL/cam/[campaignId]

Method: POST/PUT

Pro tips

See our special page with details about campaign properties and the corresponding fields in the REST API.

The easiest way to find out which campaign parameters exist, but more importantly in which combination they work together, is to create a campaign in the Revive Adserver user interface, and then to retrieve the details of that campaign through the API using the getCampaign method described above. This will show all campaign parameters as entered, but now returned in JSON formatting. This is particularly useful to find out how to combine things like campaign type, start date, end date and number of impressions (for example).

Json example

Method: 
    POST http://api.example.com/cam/6
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "campaignName": "Modified campaign",
        "weight" : 2,
        "startDate": "2018-10-01",
        "endDate": "2018-11-30"
    }

deleteCampaign

Description: Delete existing campaign

Implementation: URL/cam/[campaignId]

Method: DELETE

Json example

Method: 
    DELETE http://api.example.com/cam/6

getZoneListByCampaignID

Description: get a list of all zones a specific campaign is linked to.

Implementation: /URL/zon/cam/[campaignId]

Method: GET

Json example

Method: 
    GET http://api.example.com/zon/cam/1

Response example

[
    {
        "zoneId": "1",
        "publisherId": "1",
        "zoneName": "Demo Zone 1",
        "type": "0",
        "width": "728",
        "height": "90",
        "capping": "0",
        "sessionCapping": "0",
        "block": "0",
        "comments": "",
        "append": "",
        "prepend": "",
        "chainedZoneId": null
    },
    {
        "zoneId": "2",
        "publisherId": "1",
        "zoneName": "Demo Zone 2",
        "type": "0",
        "width": "728",
        "height": "90",
        "capping": "0",
        "sessionCapping": "0",
        "block": "0",
        "comments": "",
        "append": "",
        "prepend": "",
        "chainedZoneId": null
    }
]

Notes:

  • This method has been added in version 4.0.0
  • A bug in this method’s output has been fixed in v4.1.0
  • Starting with v4.1.0, this method returns an unnamed array of all zones (breaking change)

Current version

The most recently released version of the Revive Adserver REST API is v4.3.0 (publication date May 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