Zone Management

Documentation for all functionality to manage zones using the Revive Adserver REST API (get a list of zones, get one zone, add a zone, modify a zone, delete a zone, retrieve zone invocation code).

getZoneListByPublisherID

Description: Get a list of all zones for a specific publisher by providing the publisher ID

Implementation: URL/zon/pub/[publisherId]

Method: GET

Json example

Method: 
    GET http://api.example.com/zon/pub/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
    },
    {
        "zoneId": "3",
        "publisherId": "1",
        "zoneName": "Demo Zone 3",
        "type": "0",
        "width": "728",
        "height": "90",
        "capping": "0",
        "sessionCapping": "0",
        "block": "0",
        "comments": "",
        "append": "",
        "prepend": "",
        "chainedZoneId": null
    }
]

Notes

Note: starting with v4.1.0, this method returns an unnamed array of all zones (breaking changes).

getZone

Description: Get the details of an existing zone

Implementation: URL/zon/[zoneId]

Method: GET

Json example

Method: 
    GET http://api.example.com/zon/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
}

addZone

Description: Add new zone

Implementation: URL/zon/new

Method: POST/PUT

Request parameters

addZone
Name Description: Allowed Values Required / Optional Default
publisherId publisher ID int required
zoneName name of the zone string optional Untilted
type type of the zone 0, 1, 3, 4, 6, 7 optional 0 (see zone types below)
width width int optional 0
height height int optional 0

Zone types

The following zone types exist:

  • type 0: banner
  • type 1: interstitial
  • type 3: text ad
  • type 4: e-mail/newsletter
  • type 6: inline video ad
  • type 7: overlay video ad

Json example

Method: 
    POST http://api.example.com/zon/new
Request Header:
    Content-Type:text/javascript
Request Body:
{
    "publisherId": 1,
    "zoneName": "New zone",
    "type": "0",
    "width": 728,
    "height": 90
}

Response example

{
    "zoneId": 12,
    "publisherId": 1,
    "zoneName": "New zone",
    "type": "0",
    "width": 728,
    "height": 90,
    "capping": null,
    "sessionCapping": null,
    "block": null,
    "comments": null,
    "append": null,
    "prepend": null,
    "chainedZoneId": null
}

Notes

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

modifyZone

Description: Modify existing zone

Implementation: URL/zon/[zoneId]

Method: POST/PUT

Request parameters: see above with addZone

Json example

Method: 
    POST http://api.example.com/zon/12
Request Header:
    Content-Type:text/javascript
Request Body:
{
    "zoneName": "Modified zone",
    "type": "0",
    "width": 468,
    "height": 60
}

Response example

{
    "zoneId": 12,
    "publisherId": 1,
    "zoneName": "Modified zone",
    "type": "0",
    "width": 468,
    "height": 60,
    "capping": 0,
    "sessionCapping": 0,
    "block": 0,
    "comments": "",
    "append": "",
    "prepend": "",
    "chainedZoneId": null
}

deleteZone

Description: Delete existing zone

Implementation: URL/zon/[zoneId]

Method: DELETE

Json example

Method: 
    DELETE http://api.example.com/zon/12

Response example

{"OK"}

linkBanner

Description: Links zone and banner

Implementation: URL/zon/[zoneId]/ban/[bannerId]

Method: POST/PUT

Json example

Method: 
    POST http://api.example.com/zon/1/ban/1

unlinkBanner

Description: Unlinks zone and banner

Implementation: URL/zon/[zoneId]/ban/[bannerId]

Method: DELETE

Json example

Method: 
    DELETE http://api.example.com/zon/1/ban/1

linkCampaign

Description: Links zone and campaign

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

Method: POST/PUT

Json example

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

unlinkCampaign

Description: Unlinks zone and campaign

Implementation: URL/zon/[zoneId]/ban/[campaignId]

Method: DELETE

Json example

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

generateTags

Description: Generate invocation code

Implementation: URL/zon/[zoneId]/ic

Method: POST

Requested parameters

invocation code parameters
Name Description: Allowed Values Required / Optional Default
code_type invocation code type enum(‘adframe’, ‘adjs’, ‘adlayer’, ‘adview’, ‘adviewnocookies’, ‘async’, ‘local’, ‘popup’, ‘xmlrpc’) required  none
block Don’t show the banner again on the same page 0/1 optional 0
target Target frame enum(,’_blank’,’_top’) optional
source source string optional
withtext Show text below banner 0/1 optional 0
blockcampaign Don’t show a banner from the same campaign again on the same page 0/1 optional 0
charset Character set enum(‘ISO-8859-6′,’Windows-1256′,’ISO-8859-4′,’UTF-8′,’EUC-KR’,….) optional
thirdpartytrack Support 3rd Party Server Clicktracking enum(‘0’, ‘generic’, ‘3rdPartyServers:ox3rdPartyServers:doubleclick’, ‘3rdPartyServers:ox3rdPartyServers:max’) optional 0
comments Include comments 0/1 optional 1

Note: Starting with Revive Adserver REST API v4.2, the cody_type ‘async’ is also supported, to enable retrieving the asynchronous javascript tag type introduced with Revive Adserver v3.2.

Json example

Method: 
    POST http://api.example.com/zon/1/ic
Request Header:
    Content-Type:text/javascript
Request Body:
    {
        "code_type": "adjs"
    }

getCampaignListByZoneID

Description: get a list of all details of all campaigns linked to a zone

Notes:

  • This method was added in v4.0.0
  • A bug in the method’s output was fixed in v4.1.0
  • Starting with v4.1.0, this method returns an unnamed array of all campaigns (breaking change).

Implementation: URL/cam/zon/[zoneID]

Method: GET

Json example

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

getBannerListByZoneID

Description: get a list of all details of all banners linked to a zone

Notes:

  • This method was added in v4.0.0
  • A bug in this method’s output was corrected in v4.1.0
  • Starting with v4.1.0, this method returns an unnamed array of all banners (breaking change).

Implementation: URL/bnn/zon/[zoneID]

Method: GET

Json example

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

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