Articles in this section

See more

CxAd: APIs to Manage Billing and Earnings Accounts and other permissions

Follow

The REST API now allows you to manage Billing and Earnings Accounts inside Cxense Advertising.

The API can be accessed with the appropriate permissions to manage Billing and Earning Accounts and supports the following combination of operations on Account domain objects:

Object

Supported operations

Account list

GET

Billing Account

POST, GET, PUT and DELETE

Earning Account

POST, GET, PUT and DELETE

Please note the following operational constraints:

  • A Billing Account can be added either to the user's Advertising Folder or to any Folder below the user's Advertising Folder in the tree
  • An Earning Account can only be added to the user's Publishing Folder, it cannot be added at any other point in the Folder tree.

For more details on discovering Folders in Cxense Advertising please refer to Folder REST API.

Retrieving a list of Accounts

The GET operation is supported for listing existing Accounts.

Existing accounts can be listed in one of two ways. Either the Accounts beneath the current user's Advertising/Publishing folders can be listed, or, if the folderId of a specific user's Home folder is included in the URL, then the Accounts beneath that user's Advertising/Publishing folders will be listed.

GET

Option 1

Retrieve the list of all Accounts that exist beneath the current user's Advertising/Publishing folders.

https://{cxadbaseurl}/api/secure/accounts

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system

Example commands:

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

Option 2

Retrieve the list of all Accounts beneath the Advertising/Publishing folders for the given Home folder.

https://{cxadbaseurl}/api/secure/accounts/{homeFolderId}

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • homeFolderId the id of the Home folder of a user for which the current user has the authority to access

Example commands:

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

If a homeFolderId is specified then it must be the folderId of a Home folder that the user making the API call has access to. ie. it must be the Home folder of a user created below the calling user's Home folder.

Individual Accounts

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

POST

Create a new Account under the Folder with the given folderId. The User Role of the caller defines which operations and elements can be in the POST data. See Notes on Permissions for details.

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

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • folderId the id of the Folder under which the new Account is to be created (can be determined as per Retrieving the list of existing Folders)

This XML example shows the contents for a Billing Account POST call.

 Click to view XML example

This XML example shows the contents for an Earning Account POST call.

 Click to view XML example

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X POST https://cxad.cxense.com/api/secure/account/0000000000000111 -d @/home/jsmith123/tmp/create-account.xml

A Folder can have at most one Account of each type. If an attempt is made to add an Account to a Folder already having an Account of that type a validation error will be thrown.

Earning accounts can only be created under a home containers publishing container. There can be only one earnings account per home container.

GET

Retrieve the Account with the given accountId

https://{cxadbaseurl}/api/secure/account/{accountId}

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • accountId the id of the Account to be retrieved

Example command:

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

PUT

Update the Account with the given accountId

https://{cxadbaseurl}/api/secure/account/{accountId}

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • accountId the id of the Account to be updated

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X PUT https://cxad.cxense.com/api/secure/account/0000000000000222 -d @/home/jsmith123/tmp/update-account.xml

This XML example shows all the fields that can be PUT when creating a Billing Account:

 Click to view XML example

This XML example shows all the fields that can be PUT when creating a Earning Account:

 Click to view XML example

DELETE

Delete the Account with the given accountId

https://{cxadbaseurl}/api/secure/account/{accountId}

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • accountId the id of the Account to be deleted

Example command:

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

Individual Account Balances

The GET operation is supported to view the account balance of individual Accounts.

GET

Retrieve the balance of Account with the given accountId at a specified time.

https://{cxadbaseurl}/api/secure/account/{accountId}/balance?at={YYYYmmDDHHMM}

Parameters:

  • cxadbaseurl the base URL of the Cxense Advertising system
  • accountId the id of the Account to be retrieved
  • at the optional time to retrieve the balance, in the format YYYYmmDDHHMM. If not specified, the current balance is retrieved.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith123:password1 -X GET https://cxad.cxense.com/api/secure/account/0000000000000222/balance?at=201101290930

This XML example shows the contents returned when getting the balance of an Account:

 Click to view XML example

Notes: Tax

Cxense Advertising currently supports VAT or sales tax rates on Advertiser Billing Accounts. This rate can be set via the API or omitted and the default tax rate for the parent broker will be used.

If setting the tax rate then it should be specified as a decimal value between 0 and 1. The below example indicates a tax rate of 12.5%.

<cx:taxRate>0.125</cx:taxRate>

 

Notes: Permissions checks on users to perform actions

Below is a list of the various account permission checks performed for actions and lists of users allowed to perform the action. These permissions are in addition to the access checks performed that ensure users have access to the account in question.

Read Billing Account

  • Self Service Advertiser
  • Agency User
  • Advertiser Account Manager
  • Full Service Advertiser
  • Advertising Analyst
  • Advertising Helpdesk
  • Business Owner
  • System Administrator

Read Earnings Account

  • Self Service Publisher
  • Publisher Account Manager
  • Full Service Publisher
  • Business Owner

Create Billing Account

  • Self Service Advertiser
  • Agency User
  • Advertiser Account Manager

Create Earnings Account

  • Self Service Publisher
  • Publisher Account Manager

Update Billing Account

  • Self Service Advertiser
  • Agency User
  • Advertiser Account Manager
  • Advertising Helpdesk
  • Business Owner

Update Earnings Account

  • Self Service Publisher
  • Publisher Account Manager
  • Business Owner

Delete Billing Account

  • Self Service Advertiser
  • Agency User
  • Advertiser Account Manager

Delete Earnings Account

  • Self Service Publisher
  • Publisher Account Manager

Set Billing Account Tax Rate

  • Advertiser Helpdesk
  • Agency User
  • Business Owner

Notes: Min Balance Effect

The minimum balance effect is only available for billing accounts and controls what will happen when an account reaches the configured minimum balance.  The options available to set are outlined below:

  • NO_EFFECT: The account balance and minimum balance have no effect on campaigns.
  • SHOW_ACCOUNT_WARNING: Shows a warning when account balance is less than the minimum balance.
  • STOP_CONTRACTS_SERVING_ADS: Stops contracts from serving ads when account balance is less than the minimum balance.

Related articles

Comments

0 comments

Please sign in to leave a comment.