We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

Cxense Advertising Developer Guide

The Cxense Advertising platform has been engineered with extensibility as a key tenet and, as such, exposes a number of powerful APIs allowing key components of the system to be managed externally.

Standards for REST API calls

  • Protocol: All access to Cxense Advertising APIs must be done using the HTTPS connection protocol.

  • Serialization: All requests made to Cxense Advertising APIs accept/return data serialised XML, please refer to the API specific pages linked below for details for each API.

  • Status codes: All requests made to Cxense Advertising APIs will return an HTTP status code denoting whether they were successful or not.  See below for a breakdown of the possible error codes returned and their meanings.

  • POST requests take a serialized representation of a new object, and return the HTTP status code (200 if successful) and a serialized representation of the newly created object (including its new object id where applicable).

  • GET requests take an object id and return the HTTP status code (200 if successful) and a serialized representation of the object with that id, in the same format as returned in the original POST call that created the object.

  • DELETE requests take an object id, perform the deletion on the object, and return the HTTP status code (200 if successful).  A serialized representation is not returned.

  • PUT requests take an object id and a serialized representation of the fields which are to be updated, and return the HTTP status code (200 if successful).  A serialized representation is not returned.

    • The serialized representation of the object provided to PUT is similar in form to that returned from GET for the object.  It should include any fields that you wish to update, but it is not necessary to specify all field values – when no new value is supplied for a field, that field is left untouched..  For the object with the given id, all updatable fields specified in the given serialized representation will be updated.  If a new value is specified for a field but that field is not changeable, the field will be left alone and no error will be returned.  A return code of 200 is returned on successful update. A serialized representation is not returned.  If you wish to verify the results of a PUT, you may do a subsequent GET call with the same object id and examine the results.

 

CXAD.xsd the XML Schema Definition (XSD)

All Cxense Advertising APIs return XML data that is governed by an XML schema.

The schema can be obtained through the REST API by making an authenticated GET call to https://cxad.cxense.com/api/secure/schema/cxad.xsd.

For Example:

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

Note that this XSD only specifies the format of the data that Advertising returns; the format for data that you put into PUT and POST calls will typically be similar but not explicit verified against the XSD.

Latest documentation of XSD and its datatypes is available on W3.org: http://www.w3.org/TR/xmlschema-2/

HTTP status codes

Our APIs follow the HTTP standard codes wherever possible. You can find more on these codes in the RFC2616 specification, and you will typically see the following return codes.

Status code

Type

Description

200

Success - OK

The request was completed successfully.

202

Success - Accepted

The request has been received and will be processed at a later time. This may happen if we have a transient error that can be recovered without any further action from you.

400

Error - Bad request

The request could not be understood by the server due to malformed syntax.

401

Error - Unauthorized

The user is either not authenticated or is not authorized to perform the request.

403

Error - Forbidden

The contents of the entity sent with the request failed Cxense Advertising validation rules (eg. an attempt was made to create an Advertising Account in a folder which already contains one).

404

Error - Not found

The request URI either does not map to one of Cxense Advertising's REST APIs or it contains an invalid object id (one for which either an object does not exist or is of the wrong type).

405

Error - Method not allowed

The method specified (eg, PUT, DELETE, etc) is not permitted for the REST API being called.

422

Error - Unprocessable_entity

The server understands the content type of the request entity (syntactically correct) but was unable to process the contained instructions (eg. in the event that a malformed apiCustomerRedirectUrl has been supplied when registering a payment via the Payment REST API).

429

Error - Max concurrent API calls

The maximum number of concurrent system-wide API requests has been exceeded. The API request will need to be retried.

500

Error - Server error

The server encountered an unexpected condition which prevented it from fulfilling the request.

503

Error - Service Unavailable

The service is not available due to a temporary overload. You can either reduce the number of parallel feeding threads or retry at a later time.

Keeping inventory synchronised between REST API clients and Cxense Advertising.

When creating or updating most inventory, you have the option of providing an externalSystemId field. This represents an id or primary key for the inventory that exists in your system.  This must be unique across the type of inventory that you are creating (i.e. you can't have 2 campaigns with the same external system id, but a campaign and an ad could have the same external system id.)

Providing this external system id is useful when you have made a create request that completes successfully in our system but the successful response doesn't make it back to your system, or your system is unable to process the response. In this case your system will have inventory with your id, but without ours, even though the inventory exists in our system. The two systems are out of sync. If you now make the same create request again with the same external system id, the inventory on our side will be replaced - we will look up the existing inventory via your external system id, and replace its data with that provided by the second create request. If, for example, an external system id was not provided on that second create request, a duplicate of the inventory would have been created in our system.

Cxense Advertising enforces some rules around the use of the externalSystemId field:

  • If you are creating new inventory with an external system id that is already found in our system, and the new and existing inventory have different parents, then a 403 forbidden will be returned.

  • If you are updating existing inventory with an external system id that exists on a different piece of inventory, then a 403 forbidden will be returned.

The updateDate field is now returned so you can see the last time a piece of inventory was updated in our system.  You can't update this value yourself, and you should not send it through as part of a PUT or POST request.

When performing a PUT request (an update), you can keep track of the status of the transaction locally.  For example, you may have a field that stores the status of a transaction against a piece of inventory.  Before calling our system with the new update, clear this field.  On receiving a successful response (200), update this field with something meaningful.  After a batch of updates of updates has completed, any inventory that hasn't been marked as successful can be resent with no adverse side affects.

The APIs that expose an externalSystemId and updateDate are as follows:

  • Account REST API

  • Ad REST API

  • Ad Space REST API

  • Budget REST API

  • Campaign REST API

  • Contract REST API

  • Feed REST API

  • Folder REST API

  • Combo Creative Feature REST API

  • Flash Creative Feature REST API

  • Image Creative Feature REST API

  • Video Creative Feature REST API

  • Text Creative Feature REST API

  • Day Parting Feature REST API

  • Keyword Feature REST API

  • Location Feature REST API

  • Publisher Targeting Feature REST API

  • Retargeting Feature REST API

 


Advertising APIs

  • Advertisement REST API — This API exposes operations to allow management of Ads within the Cxense Advertising platform.

  • Audience Targeting APIs

    • Ad Space Targeting Feature REST API — This API exposes operations to allow management of Ad Space Targeting features on Campaigns and Ads within the Cxense Advertising platform.

    • Category Targeting API — This API exposes operations to allow management of Category Targeting features on Campaigns and Ads within the Cxense Advertising platform.

    • Day Parting Feature REST API — This API exposes operations to allow management of Day Parting features on Campaigns and Ads within the Cxense Advertising platform.

    • Device Targeting Feature REST API — This API exposes operations to allow management of Device Targeting features on Campaigns and Ads within the Cxense Advertising platform.

    • Geocoding API — This API exposes the ability to perform searches for geographic addresses in order to retrieve their latitude and longitude coordinates.

    • Geospatial Targeting Feature REST API — This API exposes operations to allow management of Geospatial Targeting features on Campaigns and Ads within the Cxense Advertising platform.

    • Keyword Feature REST API — This API exposes operations to allow management of Keyword features within the Cxense Advertising platform.

    • Location Feature REST API — This API exposes operations to allow management of Location features within the Cxense Advertising platform.

    • Retargeting Feature REST API — This API exposes operations to allow management of Retargeting features within the Cxense Advertising platform.

    • Site Targeting Feature REST API — This API exposes operations to allow management of Site Targeting features on Campaigns and Ads within the Cxense Advertising platform.

    • User Segment Targeting API — This API exposes operations to allow management of User Segment Targeting features on Campaigns and Ads within the Cxense Advertising platform.

  • Budget REST API — This API defines operations to allow management of the spending limits in effect for inventory items within the Cxense Advertising platform.

  • Campaign and Contract REST API — This API exposes operations to allow management of Campaigns and their Contracts within the Cxense Advertising platform.

  • Creative APIs — Creative feature types allow Advertisers to generate different combinations and formats of advertising content to their Advertisements.

    • Combo Creative Feature REST API — This API exposes operations to allow management of Combo Creative features within the Cxense Advertising platform.

    • Flash Creative Feature REST API — This API exposes operations to allow management of Flash Creative features within the Cxense Advertising platform.

    • HTML 5 Creative Feature REST API — This API exposes operations to allow management of HTML 5 Creative features within the Cxense Advertising platform.

    • Image Creative Feature REST API — This API exposes operations to allow management of Image Creative features within the Cxense Advertising platform.

    • Text Creative Feature REST API — This API exposes operations to allow management of Text Creative features within the Cxense Advertising platform.

    • Third Party Creative Feature API — This API exposes operations to allow management of Third Party Creative features within the Cxense Advertising platform.

    • Video Creative Feature REST API — This API exposes operations to allow management of Video Creative features within the Cxense Advertising platform.

Finance APIs

  • Account REST API — This API exposes operations to allow management of Billing and Earnings Accounts within the Cxense Advertising platform.

  • Billing REST API — This API allows Transactions to be created against Accounts within the Cxense Advertising platform.

  • Payment REST API — This API exposes operations to allow payments to be made against Accounts within the Cxense Advertising platform.

General APIs

  • Folder REST API — Much like a computer's filesystem the Cxense Advertising platform structures its inventory items in the form of a tree of Folders. The structure of this tree (ie. the name and location of the Folders that make it up) can be managed via the Folder REST API.

Inventory APIs

  • Feed REST API — This API exposes operations to allow management of Feeds within the cX::ad platform.

  • Product REST API — This API exposes operations to allow retrieval of Product data within the Cxense Advertising platform.

Management APIs

  • Location REST API — This API exposes operations to allow management of the geotargeting data made available to Advertisers on their Campaigns within the cX::ad platform.

  • Shared Folder Access REST API — This API exposes operations to allow the access to Folders that are shared with other users in their system to be managed. The users must have been invited to share access to the same area of the application as the user modifying shared folders.

  • User REST API — This API allows more privileged users to manage users within the Cxense Advertising system. To create and invite new users, control which sections of the Folder tree they should be granted access to and the operations they should be allowed to perform there.

Publishing APIs

  • AdSpace REST API — This API exposes operations to allow management of AdSpaces within the Cxense Advertising platform.

  • Search REST and JavaScript API — This API allows access to advertising content from the Cxense Advertising platform either by using REST or Javascript as the transport protocol.

    • Advanced javascript examples

    • Creative template / Client-side template-based rendering

    • Insert multiple ad spaces with one ad server request

    • JavaScript-only rendering

Reporting APIs

  • Data Extract REST API — This API allows management of Data Extracts in Cxense Advertising. Extracts can be generated, downloaded and deleted via this API.

  • Data Extract Schedule REST API — This API allows management of Data Extract Schedules in cX::ad. Extract Schedules can be created, updated and deleted via this API.

  • Statistics REST API — This API allows the Advertising and Publishing statistics collected by the Cxense Advertising platform to be accessed.  These statistics can be retrieved in summary or detailed format across a specified date range, and for multiple statistics objects.

Last updated: