PDF

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 the GET 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 as account_uid. Of the required fields, most include a url field, such as account_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 as network.display and network.mobile in the above sample. Some fields reference other API objects, such as the account_uid field. For such fields, their options call return a list very similar to list calls (such as GET /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"

PDF