Campaign and Contract REST API

This API exposes operations to allow management of Campaigns and their Contracts within the Cxense Advertising platform.

This API can be accessed by users with the appropriate permissions to manage Campaigns and supports the following combination of operations on the Campaign and Contract domain objects:

Object	Supported operations
Campaign list	GET
Campaign	POST, GET, PUT and DELETE
Contract list	GET
Contract	POST, GET and PUT

Retrieving the list of Campaigns within a Folder

The GET operation is supported for listing existing Campaigns.

GET

Retrieve all of the Campaigns contained within the Folder with the given folderId.

https://{cxadbaseurl}/api/secure/campaigns/{folderId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
folderId the id of the Folder for which the Campaigns are to be retrieved (can be determined as detailed in Folder REST API - GET operation)

Example commands:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/campaigns/00000000000392f2

Individual Campaigns

The POST, GET, PUT and DELETE operations are supported for management of individual Campaigns.

POST

In order to be able to create a Campaign the user must first decide in what location (or Folder) the Campaign is to be created.

A list of Folders at any given point in the tree of advertising accounts can be retrieved, starting from the top-level Advertising Folder and working down the tree. Please refer to Folder REST API for details on how to discover Folders in Cxense Advertising.

Perform a POST operation with the following URL to create a new Campaign under the Folder with the given folderId.

https://{cxadbaseurl}/api/secure/campaign/{folderId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
folderId the id of the Folder under which the new Campaign is to be created (can be determined as detailed in Folder REST API - GET operation)

This XML example shows the mandatory and optional contents required to be supplied for a POST call:

<?xml version="1.0" encoding="UTF-8"?>
<cx:campaign xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:name>Test Campaign</cx:name>
  <cx:productId>0000000000004ae5</cx:productId>
  <!-- the user impression capping element below is optional. The available periods are: DAILY, WEEKLY, MONTHLY -->
  <!-- a max cap value of 0 will turn the cap off -->
  <cx:perUserCap>
     <cx:max>5</cx:max>
     <cx:period>DAILY</cx:period>
  </cx:perUserCap>
  <!-- optional elements end -->
</cx:campaign>

Example commands:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X POST https://cxad.cxense.com/api/secure/campaign/advertising -d @input.xml

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X POST https://cxad.cxense.com/api/secure/campaign/00000000000392f2 -d @input.xml

GET

Retrieve the Campaign with the given campaignId

https://{cxadbaseurl}/api/secure/campaign/{campaignId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
campaignId the id of the Campaign to be retrieved

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/campaign/0000000000039306

This XML example shows the contents returned from a GET call for a campaign with no per user impression cap:

<?xml version="1.0"?>
<cx:campaign xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:campaignId>0000000000004e2f</cx:campaignId>
  <cx:name>Making an Impression</cx:name>
  <cx:productId>0000000000004a52</cx:productId>
</cx:campaign>

This XML example shows the contents returned from a GET call for a campaign with a per user impression cap:

<?xml version="1.0"?>
<cx:campaign xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:campaignId>0000000000004e2f</cx:campaignId>
  <cx:name>Making an Impression</cx:name>
  <cx:productId>0000000000004a52</cx:productId>
  <cx:perUserCap>
     <cx:max>5</cx:max>
     <cx:period>DAILY</cx:period>
  </cx:perUserCap>
</cx:campaign>

PUT

Update the Campaign with the given campaignId

https://{cxadbaseurl}/api/secure/campaign/{campaignId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
campaignId the id of the Campaign to be updated

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X PUT https://cxad.cxense.com/api/secure/campaign/0000000000039306 -d @input.xml

DELETE

Delete the Campaign with the given campaignId

https://{cxadbaseurl}/api/secure/campaign/{campaignId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
campaignId the id of the Campaign to be deleted

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X DELETE https://cxad.cxense.com/api/secure/campaign/0000000000039306

Retrieving the list of Contracts for a Campaign

The GET operation is supported for listing existing Contracts.

GET

Retrieve all of the Contracts for the Campaign with the given campaignId.

https://{cxadbaseurl}/api/secure/contracts/{campaignId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
campaignId the id of the Campaign for which the Contracts are to be retrieved

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/contracts/0000000000039306

Individual Contracts

The POST, GET, PUT and DELETE operations are supported for management of individual Contracts.

POST

Create a new Contract under the Campaign with the given campaignId.

https://{cxadbaseurl}/api/secure/contract/{campaignId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
campaignId the id of the Campaign under which the new Contract is to be created

When a new Contract is created under a Campaign this is the equivalent of clicking the Publish button in the UI for the Campaign and hence results in the Campaign going LIVE. Therefore, equivalently, when POSTing a new Contract via this REST API the status field is defaulted to LIVE meaning any value supplied for this field in the request XML is ignored.

When creating a contract for a Tenancy product, the start and end date will be converted into the same time zone as that used for the product, so the dates may change if you use a different time zone.

CPC

This XML example shows the contents required to be supplied when POSTing a new Contract for a Campaign created from a CPC Product:

<?xml version="1.0"?>
<cx:cpcContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <!-- start date and end date, which are called flight dates in the UI, are optional for a CPC campaign -->
  <cx:startDate>2011-02-25T00:00:00.000+11:00</cx:startDate>
  <cx:endDate>2011-03-31T00:00:00.000+11:00</cx:endDate>
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
</cx:cpcContract>

CPM

This XML example shows the contents required to be supplied when POSTing a new Contract for a Campaign created from a CPM Product:

<?xml version="1.0"?>
<cx:cpmContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:startDate>2011-02-25T00:00:00.000+11:00</cx:startDate>
  <cx:endDate>2011-03-31T00:00:00.000+11:00</cx:endDate>
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
  <cx:requiredImpressions>100</cx:requiredImpressions>
  <!-- costPerThousand is optional and only available to users with appropriate permission -->
  <cx:costPerThousand class="currency" currencyCode="USD" value="50.00"/>
</cx:cpmContract>

Tenancy

This XML example shows the contents required to be supplied when POSTing a new Contract for a Campaign created from a Tenancy Product:

<?xml version="1.0"?>
<cx:tenancyContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:startDate>2011-02-25T00:00:00.000Z</cx:startDate>
  <cx:endDate>2011-03-07T23:59:59.999Z</cx:endDate>
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
</cx:tenancyContract>

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X POST https://cxad.cxense.com/api/secure/contract/0000000000039306 -d @input.xml

GET

Retrieve the Contract with the given contractId

https://{cxadbaseurl}/api/secure/contract/{contractId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
contractId the id of the Contract to be retrieved

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/contract/0000000000035506

CPC

The following XML example shows the contents returned from a GET call when retrieving a CPC Contract:

<?xml version="1.0"?>
<cx:cpcContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:contractId>0000000000005627</cx:contractId>
  <cx:startDate>2013-08-26T05:47:09.165Z</cx:startDate>
  <cx:productId>0000000000004aab</cx:productId>
  <cx:setupFee currencyCode="USD" value="5.000000"></cx:setupFee>
  <cx:totalCost currencyCode="USD" value="5.000000"></cx:totalCost>
  <cx:estimatedCost currencyCode="USD" value="5.000000"></cx:estimatedCost>
  <cx:status>LIVE</cx:status>
  <cx:priority>0.5</cx:priority>
</cx:cpcContract>

CPM

The following XML example shows the contents returned from a GET call when retrieving a CPM Contract:

<?xml version="1.0"?>
<cx:cpmContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:contractId>0000000000005612</cx:contractId>
  <cx:startDate>2013-09-06T00:00:00.000Z</cx:startDate>
  <cx:endDate>2013-09-13T23:59:59.999Z</cx:endDate>
  <cx:productId>0000000000004a52</cx:productId>
  <cx:setupFee currencyCode="USD" value="5.000000"></cx:setupFee>
  <cx:totalCost currencyCode="USD" value="5.000000"></cx:totalCost>
  <cx:estimatedCost currencyCode="AUD" value="16.500000"></cx:estimatedCost>
  <cx:status>LIVE</cx:status>
  <cx:priority>0.5</cx:priority>
  <cx:requiredImpressions>10000</cx:requiredImpressions>
  <cx:smoothingEnabled>true</cx:smoothingEnabled>
  <cx:costPerThousand currencyCode="AUD" value="1.050000"></cx:costPerThousand>
</cx:cpmContract>

Tenancy

The following XML example shows the contents returned from a GET call when retrieving a Tenancy Contract:

<?xml version="1.0"?>
<cx:tenancyContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:contractId>0000000000005638</cx:contractId>
  <cx:startDate>2013-09-06T00:00:00.000+10:00</cx:startDate>
  <cx:endDate>2013-09-13T23:59:59.999+10:00</cx:endDate>
  <cx:productId>0000000000004aae</cx:productId>
  <cx:setupFee currencyCode="USD" value="5.000000"></cx:setupFee>
  <cx:totalCost currencyCode="USD" value="5.000000"></cx:totalCost>
  <cx:estimatedCost currencyCode="USD" value="14.200000"></cx:estimatedCost>
  <cx:status>LIVE</cx:status>
  <cx:priority>0.5</cx:priority>
  <cx:costPeriod>DAILY</cx:costPeriod>
  <cx:costingFunction>PER_PERIOD</cx:costingFunction>
  <cx:unitCost currencyCode="USD" value="1.150000"></cx:unitCost>
  <cx:numberOfPeriods>8</cx:numberOfPeriods>
  <cx:totalCombinations>1</cx:totalCombinations>
</cx:tenancyContract>

PUT (contract fields)

Update the Contract with the given contractId

https://{cxadbaseurl}/api/secure/contract/{contractId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
contractId the id of the Contract to be updated

CPC

This XML example shows the contents that can be supplied when updating an existing Contract for a Campaign created from a CPC Product:

<?xml version="1.0"?>
<cx:cpcContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <cx:startDate>2011-02-25T00:00:00.000+11:00</cx:startDate>
  <cx:endDate>2011-03-31T00:00:00.000+11:00</cx:endDate>
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
</cx:cpcContract>

CPM

This XML example shows the contents that can be supplied when updating an existing Contract for a Campaign created from a CPM Product:

<?xml version="1.0"?>
<cx:cpmContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
  <cx:startDate>2011-02-25T00:00:00.000+11:00</cx:startDate>
  <cx:endDate>2011-03-31T00:00:00.000+11:00</cx:endDate>
  <cx:requiredImpressions>600</cx:requiredImpressions>
  <cx:smoothingEnabled>true</cx:smoothingEnabled>
</cx:cpmContract>

Note that the ability to update startDate, endDate and requiredImpressions for a CPM Contract will be available shortly (estimated mid August 2015).

Tenancy

This XML example shows the contents that can be supplied when updating an existing Contract for a Campaign created from a Tenancy Product:

<?xml version="1.0"?>
<cx:tenancyContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <!-- priority is optional, if not specified it will be defaulted 0.5 -->
  <cx:priority>0.50</cx:priority>
</cx:tenancyContract>

PUT (contract status)

Update the status of the Contract with the given contractId

https://{cxadbaseurl}/api/secure/contract/{contractId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
contractId the id of the Contract to be updated

A Contract can have one of the following statuses:

LIVE
PAUSED
STOPPED

Only the following status changes are valid:

From LIVE to PAUSED
From LIVE to STOPPED
From PAUSED to LIVE
From PAUSED to STOPPED

CPC

This XML example shows the contents that should be supplied when unpausing a Contract for a Campaign created from a CPC Product:

<?xml version="1.0"?>
<cx:cpcContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <status>LIVE</status>
</cx:cpcContract>

CPM

This XML example shows the contents that should be supplied when pausing a Contract for a Campaign created from a CPM Product:

<?xml version="1.0"?>
<cx:cpmContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <status>PAUSED</status>
</cx:cpmContract>

Tenancy

This XML example shows the contents that should be supplied when stopping a Contract for a Campaign created from a Tenancy Product:

<?xml version="1.0"?>
<cx:tenancyContract xmlns:cx="http://cxense.com/cxad/api/cxad">
  <status>STOPPED</status>
</cx:tenancyContract>

Last updated: January 19, 2022