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.
This XML example shows the contents for an Earning Account POST call.
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:
This XML example shows all the fields that can be PUT when creating a Earning Account:
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:
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.
Comments
0 comments
Please sign in to leave a comment.