Banner Management

Documentation for all functionality to manage banners using the Revive Adserver REST API, with methods to retrieve all banners in a campaign, retrieve the details of a single banner, to add a new banner, to modify an existing banner, to delete a banner.

There is a wide variety of banner types and associated properties in the Revive Adserver software. See the special page about all fields and properties to get a full picture of the available options for banners.

getBannerListByCampaignId

Description: Get all banners from a specific campaign

Implementation: URL/bnn/cam/[campaignId]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/cam/2

Response example

[
    {
        "bannerId": "12",
        "campaignId": "4",
        "bannerName": "Statistics Demo Banner",
        "storageType": "web",
        "imageURL": "",
        "htmlTemplate": "",
        "width": "320",
        "height": "65",
        "weight": "1",
        "target": "_self",
        "url": "https:\/\/www.reviveadserverrestapi.com\/",
        "bannerText": "",
        "status": "0",
        "adserver": "",
        "transparent": "0",
        "capping": "0",
        "sessionCapping": "0",
        "block": "0",
        "aImage": null,
        "aBackupImage": null,
        "comments": "",
        "alt": "Revive Adserver REST API",
        "filename": "968fd0ae42ce2f28941bb9c15539a7c6.png",
        "append": "",
        "prepend": ""
    }
]

getBanner

Description: Get the details of an existing banner

Implementation: URL/bnn/[bannerId]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/12

Response example

{
    "bannerId": "12",
    "campaignId": "4",
    "bannerName": "Statistics Demo Banner",
    "storageType": "web",
    "imageURL": "",
    "htmlTemplate": "",
    "width": "320",
    "height": "65",
    "weight": "1",
    "target": "_self",
    "url": "https:\/\/www.reviveadserverrestapi.com\/",
    "bannerText": "",
    "status": "0",
    "adserver": "",
    "transparent": "0",
    "capping": "0",
    "sessionCapping": "0",
    "block": "0",
    "aImage": null,
    "aBackupImage": null,
    "comments": "",
    "alt": "Revive Adserver REST API",
    "filename": "968fd0ae42ce2f28941bb9c15539a7c6.png",
    "append": "",
    "prepend": ""
}

addBanner

Description: Add new banner

Implementation: URL/bnn/new

Method: POST/PUT

Pro tips

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

The easiest way to find out which banner parameters exist, but more importantly in which combination they work together, is to create a banner in the Revive Adserver user interface, and then to retrieve the details of that banner through the API using the getBanner method described above. This will show all banner parameters as entered, but now returned in JSON formatting. This is particularly useful to find out how to combine things like banner type, banner filename, url, htmlTemplate and so on.

Notes

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

modifyBanner

Description: Modify existing banner

Implementation: URL/bnn/[bannerId]

Method: POST/PUT

Pro tips

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

Notes

Starting with v4.0, the modifyBanner method will return full details of the newly created banner, instead of just {“OK”}.

deleteBanner

Description: Delete existing banner

Implementation: URL/bnn/[bannerId]

Method: DELETE

Json example

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

getBannerTargeting

Description: Returns all banner’s delivery limitations

Implementation: URL/bnn/[bannerId]/targeting

Method: GET

Json example

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

setBannerTargeting

Description: Sets delivery limitation for particular banner. All previous delivery limitation for the banner will be deleted.

Implementation: URL/bnn/[bannerId]/targeting

Method: POST/PUT

Parameters

**modifyBanner**
Name	Description:	Allowed Values	Required / Optional
logical	logical parameter	enum(and,or)	required
type	type of the delivery limitation	string	required
comparison	type of comparison	enum (=~,!=~,==,!=,>,<….)	required
data	comparison data	string	required

Json example

Method: 
    POST http://api.example.com/bnn/1/targeting
Request Body:
[
    {
        "logical": "and",
        "type": "deliveryLimitations:Client:Browser",
        "comparison": "=~",
        "data": "FX,MZ,OP"
    },
    {
        "logical": "and",
        "type": "deliveryLimitations:Client:Ip",
        "comparison": "!=",
        "data": "10.0.0.1"
    }
]

Notes

Starting with version 4.2.0, is is now possible to remove delivery limitations (delivery rules) currently assigned to an existing banner, by calling the setBannerTargeting method and pass it an empty array ([]).

Current version

The most recently released version of the Revive Adserver REST API is v5.2.0 (publication date April 18, 2024).

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.

Sorting 'Lst' output

Version 5.2.0 (released April 18, 2024)) introduced the ability to sort the output of the 'list' feature by any of the available columns (in ascending or descending order), and to limit the number of rows of the output. This is supported for the List output of any of the categories.

Please see the generic Documentation for the sort order output of lists.