Zone Management

Revive Adserver REST API functionality to create and modify zones, link and unlink campaigns and banners, 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]

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

Method: GET

Json example

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

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

addZone

Description: Add new zone

Implementation: URL/zon/new

Method: POST/PUT

Requested 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

Json example

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

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.

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

modifyZone

Description: Modify existing zone

Implementation: URL/zon/[zoneId]

Method: POST/PUT

Requested parameters

modifyZone
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 list of zone types above)
width width int optional 0
height height int optional 0

Json example

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

deleteZone

Description: Delete existing zone

Implementation: URL/zon/[zoneId]

Method: DELETE

Json example

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

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.2.0 (publication date July 12, 2017).

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.