Working with Accounts
Depending on your use case, the account object is used in the following way:
- Advertiser accounts are containers for orders and other demand objects.
- Publisher accounts are containers for sites, ad units, and other inventory objects.
- Ad networks are containers for other accounts.
The account object fields can change as a result of different parameters such as the following:
- action
- instance configuration
- object
type_full
To determine the available fields and appropriate values, you should make available_fields
calls and options
calls as needed. The Platform API provides informative responses even when the input has errors. Building a request may take a few attempts but the error messages guide you to the correct request format.
Creating an Account
To create an account:
Refer to the authentication topic to obtain an
openx3_access_token
.Get the available fields for an account:
Sample available fields request
openx_server_name/ox/4.0/account/available_fields --cookie "openx3_access_token=curl http://token_string"
Where
token_string
is a string of characters returned by theGET session
request at login.Sample available fields response
{ "attribute": "type_full", "choices": [ "account.agency", "account.advertiser", "account.network", "account.publisher" ], "field": {}, "http_status": 400, "message": "Field type_full value must be one of \"account.agency\", \"account.advertiser\", \"account.network\" or \"account.publisher\" (\"None\" not allowed)", "type": "Value Error", "value": null }'
Accounts fields change based the different account types. The response indicates that a
type_full
value is required.Modify the request by adding a
type_full
URI parameter:Sample type full account request
openx_server_name/ox/4.0/account/available_fieldstype_full=account.network --cookie "openx3_access_token=curl http://token_string"
Sample type full account response
Click to expand this sample
{ "account_id": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "int" }, "account_uid": { "has_dependencies": false, "readonly": false, "required": true, "type": "account_uid", "url": "/options/account_options" }, "acl_override": { "acl": "network.acl_override", "available_fields": {}, "default": {}, "has_dependencies": false, "readonly": false, "required": false, "type": "object" }, "country_of_business": { "acl": "network.region_settings", "default": "us", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/country_options" }, "created_date": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "datetime" }, "currency": { "acl": "network.region_settings", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/currency_options" }, "currency_id": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "int" }, "deleted": { "auto": true, "default": "0", "has_dependencies": false, "readonly": true, "required": false, "type": "int" }, "experience": { "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/network_experience_options" }, "external_id": { "acl": "network.addl_info", "has_dependencies": false, "readonly": false, "required": false, "type": "varchar" }, "hidden": { "acl": "network.hidden", "default": "0", "has_dependencies": false, "readonly": false, "required": false, "type": "int" }, "id": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "int" }, "instance_uid": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "uid" }, "modified_date": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "datetime" }, "name": { "acl": "network.name", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar" }, "notes": { "acl": "network.addl_info", "has_dependencies": false, "readonly": false, "required": false, "type": "varchar" }, "status": { "acl": "network.status", "default": "Active", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/account_status_options" }, "timezone": { "default": "UTC", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/timezone_options" }, "timezone_id": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "int" }, "type": { "auto": true, "default": "account", "has_dependencies": false, "readonly": true, "required": false, "type": "varchar", "value": "account" }, "type_full": { "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "value": "account.network" }, "uid": { "auto": true, "has_dependencies": false, "readonly": true, "required": false, "type": "uid" }, "v": { "auto": true, "default": "3", "has_dependencies": false, "options": [], "readonly": true, "required": false, "type": "int" } }
Within the response, several fields are marked
"required": true
, such asaccount_uid
. Of the required fields, most include aurl
field, such asaccount_uid
’s\"url\": \"/options/account\_options\"
.To see a list of available options, make the options calls indicated by the URLs. The following call shows an options call for only one of the required fields:
Sample experience options request
openx_server_name/ox/4.0/options/network_experience_options --cookie "openx3_access_token=curl http://token_string"
Sample experience options response
[ { "id": "network.display", "name": "Display Network" }, { "id": "network.mobile", "name": "Mobile App Developer" }]
By default, the acceptable values are the
id
values, such asnetwork.display
andnetwork.mobile
in the above sample. Some fields reference other API objects, such as theaccount_uid
field. For such fields, theiroptions
call return a list very similar to list calls (such asGET /account
).Build a request to create an account using the following five fields along with
type_full
:Sample create account request with experience and status typos
openx_server_name/ox/4.0/account --cookie "openx3_access_token=curl http://token_string" -X POST --header "Content-Type:application/json" --data '{"account_uid": "200571f0-accf-fff1-8123-0c9a66", "currency": "USD", "experience": "network.displayy", "name": "My Network", "status": "Activee", "type_full": "account.network", "timezone": "America/Los_Angeles"}'
The API returns multiple errors and a field errors dictionary with experience and status keys indicating the values passed in are invalid.
Sample error response
[ { "field_errors": { "experience": { "attribute": "experience", "choices": [ "network.mobile", "network.display" ], "field": { "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/network_experience_options" }, "http_status": 400, "message": "Field experience value must be one of \"network.mobile\" or \"network.display\" (\"network.displayy\" not allowed)", "type": "Value Error", "value": "network.displayy" }, "status": { "attribute": "status", "choices": [ "Active", "Inactive" ], "field": { "acl": "network.status", "default": "Active", "has_dependencies": false, "readonly": false, "required": true, "type": "varchar", "url": "/options/account_status_options" }, "http_status": 400, "message": "Field status value must be one of \"Active\" or \"Inactive\" (\"Activee\" not allowed)", "type": "Value Error", "value": "Activee" } }, "http_status": 400, "message": "Validation of new networkaccount failed:\n status: Field status value must be one of \"Active\" or \"Inactive\" (\"Activee\" not allowed)\n experience: Field experience value must be one of \"network.mobile\" or \"network.display\" (\"network.displayy\" not allowed)", "object": "networkaccount", "type": "Object Validation Error", "uid": null } ]
Fix the mistakes and try again:
Sample create account request
openx_server_name/ox/4.0/account --cookie "openx3_access_token=curl http://token_string" -X POST --header "Content-Type:application/json" --data '{"account_uid": "200571f0-accf-fff1-8123-0c9a66", "currency": "USD", "experience": "network.display", "name": "My Network", "status": "Active", "type_full": "account.network", "timezone": "America/Los_Angeles"}'
The API returns the full object in the create response. Many fields that were not passed in are filled in with defaults, which depend on things such as instance settings, parent account, and other fields.
Sample create response
[ { "account_id": "537227760", "account_uid": "200571f0-accf-fff1-8123-0c9a66", "acl_override": {}, "country_of_business": "us", "created_date": "2013-10-04 05:52:57", "currency": "USD", "currency_id": "1", "deleted": "0", "experience": "network.display", "external_id": null, "hidden": "0", "id": "537241695", "instance_uid": "[Code]instance_uid", "modified_date": "2013-10-04 05:52:57", "name": "My Network", "notes": "", "revision": 1, "status": "Active", "timezone": "America/Los_Angeles", "timezone_id": "8", "type": "account", "type_full": "account.network", "uid": "2005a85f-accf-fff1-8123-0c9a66", "v": "3" } ]
Make a read request using the UID field of the newly created account:
Sample read account request
curl http://openx_server_name/ox/4.0/account/2005a85f-accf-fff1-8123-0c9a66 --cookie "openx3_access_token=token_string"
The account appears in the response and also for list calls:
Sample list accounts request
curl http://openx_server_name/ox/4.0/account --cookie "openx3_access_token=token_string"