Campaign Properties and API fields

This page describes the properties that can be set or retrieved for campaigns when using the Revive Adserver REST API. The order of this page follows the order of the fields in the Revive Adserver user interface,

Campaign ID

Field name: campaignId

Description: The unique ID of a campaign. Once a campaign has been created and a unique campaign ID has been assigned, the ID can not be changed.

Usage:

  • Omit when adding a new campaign;
    the ID of the newly created campaign will be part of the API response, enabling developers to record it in their own application and use it later for other purposes. Example:

    "campaignId": "1"
  • Include an existing campaign ID in the API URL when retrieving a campaign, modifying a campaign, deleting a campaign

Advertiser ID

Field name: advertiserId

Description: The ID of the advertiser that the campaign is associated with.

Usage:

  • Required when adding a new campaign; The newly created campaign will be associated with the advertiser with the provided ID.
  • Optional when modifying an existing campaign (recommend not to include)

Syntax example:

"advertiserId": "1"

Campaign Name

Field name: campaignName

Description: The name of the campaign

Type: String, maximum length 255 characters

Usage:

  • Mandatory when adding a new campaign.
  • Optional when modifying an existing campaign

Syntax example:

"campaignName": "Name of the campaign"

Campaign Type

Field name: priority

Description: The campaign type

Type: int;

Allowed values: -1, 0, 1-10

Usage:

  • For a Remnant campaign, set priority to value 0
  • For a Contract campaign, set priority to value 1 – 10
  • For an Override campaign, set priority to value -1

Syntax example:

"priority": "0"

Start date

Field name: startDate

Description: Start date of the campaign

Type: date

Usage:

  • when creating a campaign, omitting the start date will set it to start immediately

Syntax example 1:

"startDate": "2018-09-01",

Syntax example 2:

"startDate": {
        "year": "2018",
        "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
        }
    },

End date

Field name: endDate

Description: End date of the campaign

Type: date

Usage:

  • when creating a campaign, omitting the end date will set it to not expire, assuming the use case allows for not having an end date.
  • the end date, if used, must be later than the start date.
  • in some situation, a campaign can not have an end date; for example, a remnant campaign with a fixed total number of booked impressions, will expire after the booked impressions have been delivered, and therefore does not need (and does not allow tus the use of) an end date.
  • in some situations, a campaign must have an end date; for example, a contract campaign with a fixed total number of booked impressions (not a daily limit), must have an end date.
  • once a campaign has an end date, it can not be turned back into ‘don’t expire’. This is a known issue in the core Revive Adserver software itself, due to the fact that the XML-RPC API inside can not support a ‘null’ value (since that’s not part of the specifications of XML-RPC)

Syntax example 1:

"startDate": "2018-12-31",

Syntax example 2:

"startDate": {
        "year": "2018",
        "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
        }
    },

Pricing model

Field name: revenueType

Description: pricing model for the campaign

Type: integer

Allowed values: 1, 2, 3, 4

Usage:

  • For a CPM pricing model, set the value to 1
  • For a CPC pricing model, set the value to 2
  • For a CPA pricing model, set the value to 3
  • For a Tenancy pricing model, set the value to 4

Syntax example:

"revenueType": "1"

Rate / Price

Field name: revenue

Description: rate or price of the campaign

Range: numeric, decimal(10,4), pattern x.xxxx

Usage:

  • For a CPM pricing model, set the value to the rate to be charged per 1,000 impressions
  • For a CPC pricing model, set the value to the rate to be charged per click
  • For a CPA pricing model, set the value to the rate to be charged per conversion
  • For a Tenancy pricing model, set the value to the amount to be charged per month

Syntax example:

"revenue": "10.0000"

Impressions booked

Field name: impressions

Description: the number of impressions the campaign is supposed to deliver

Range: numeric

Usage:

  • available only when the pricing model (field name revenueType) is set to 1 = CPM, 2 = CPC, or 3 = CPA
  • available for a contract campaign or for a remnant/override campaign with no end date
  • Set the value to -1 to indicate the booked number of impressions is unlimited

Syntax example:

"impressions": "-1"
"impressions": "100000"

Clicks booked

Field name: clicks

Description: the number of clicks the campaign is supposed to deliver

Range: numeric

Usage:

  • available only when the pricing model (field name revenueType) is set to 2 = CPC or 3 = CPA
  • available for a contract campaign or for a remnant/override campaign with no end date
  • Set the value to -1 to indicate the booked number of clicks is unlimited

Syntax example:

"clicks": "-1"
"clicks": "1000"

Conversions booked

note: this field is currently missing in the REST API. This is a known issue that will be fixed in the next release.

Field name: conversions

Description: the number of conversions the campaign is supposed to deliver

Range: numeric

Usage:

  • available only when the pricing model (field name revenueType) is set to 3 = CPA
  • available for a contract campaign or for a remnant/override campaign with no end date
  • Set the value to -1 to indicate the booked number of conversions is unlimited

Syntax example:

"conversions": "-1"
"conversions": "100"

Weight

Field name: weight

Description: weight of a campaign, used to set the priority of the campaign relative to the weight of other campaigns

Range: numeric, 1-127, defaults to 1

Usage:

  • Available only when the value of the field ‘priority’ equals 1 (remnant) or -1 (override)
  • Set a weight as a numeric value

Syntax example:

"weight": "1"

Delivery capping per visitor: Limit campaign views to x in total

Field name: capping

Description: Limits the total number of impressions of a campaign’s banners for an individual visitor

Type: integer

Usage:

  • Set as a numeric value
  • Use a value of 0 to indicate unlimited views per visitor

Syntax example:

"capping": "100"

Delivery capping per visitor: Limit campaign views to x per session

Field name: sessionCapping

Description: Limits the number of impressions of a campaign’s banners for an individual visitor in a single session

Type: integer

Usage:

  • Set as a numeric value
  • Use a value of 0 to indicate unlimited views per visitor

Syntax example:

"sessionCapping": "10"

Delivery capping per visitor: reset view counters after x seconds

Field name: block

Description: Reset the counter for the number of views after the specified number of seconds. The API (like the underlying database table) stores the number of seconds, whereas the Revive Adserver user interface shows this in ‘hours, minutes, seconds’.

Type: integer

Usage:

  • Set as a numeric value
  • Use a value of 0 to indicate view counters should never be reset

Syntax example:

"block": "1200"

Miscellaneous: Hide the advertiser and websites of this campaign.

This property is currently not supported by the Revive Adserver REST API. This is a known issue that we hope to resolve in a future release

Miscellaneous: Companion Positioning

This property is currently not supported by the Revive Adserver REST API. This is a known issue that we hope to resolve in a future release

Comments

Field name: comment

Description: A comment about the campaign

Type: string, maximum length 65,535 characters

Syntax example:

"comments": "A campaign comment goes here."