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": 12.50
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 a future 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: