PDF

Requests and Responses

Call	Description
`GET /resource_type`	Lists all objects or services of the specified type.
`GET /object_type/object_UID`	Retrieves information about the object specified by its UID.
`POST /object_type`	Creates a new object using the values encoded in a JSON object, which must include all fields that are required for the create operation. You can make batch create requests by including multiple JSON objects.
`PUT /object_type`	Updates in batch. Requests include a set of valid JSON objects with any fields that are being changed by the update. You can optionally include unchanged data.
`PUT /object_type/object_UID`	Updates the specified object with changed values specified in a JSON object. You can optionally include unchanged data.
`DELETE /object_type`	Deletes in batch, where the request includes multiple UIDs.
`DELETE /object_type/object_UID`	Deletes the specified object.

The request samples in the following sections use cURL (client URL request library) to send HTTP requests to access, create, and manipulate OpenX API resources.

Create

To create a new object, send a POST request including the JSON-encoded contents of the object.

Sample create request

curl -X POST --header "Content-Type: application/json" http://openx_server_name/ox/4.0/account \
    --cookie "openx3_access_token=token_string" \
    --data='{
    "account_uid": "account_uid",
    "account_id": "account_id",
    "name": "API+Demo+Advertiser",
    "country_of_business":"us",
    "currency":"USD",
    "experience":"advertiser",
    "notes":"",
    "single_ad_limitation":"0",
    "status":"Active",
    "timezone":"America/Los_Angeles",
    "type_full":"account.advertiser"
}'

token_string is a string of characters returned by the GET session request at login. When you create a single object, the response should contain a list with a single object.

Sample create response

If successful, a 200 Created is returned along with the response body:

[
    {            
    "account_id": "account_id",
    "name": "API+Demo+Advertiser",
    "status":"Active",
    "account_type_id":"4",
    "currency":"USD",
    "timezone": "America/Los Angeles",
    "country_of_business_id":"us",
    "single_ad_limitation":"0",
    }
]

account_uid is the UID of the account that was created.
account_id is the ID of the account that was created.

For more details, see About IDs and UIDs.

Update

To change the data on an object that already exists, send a PUT request to the object URI with the values you want to change.

Sample update request

curl -X PUT --header "Content-Type: application/json" http://openx_server_name/ox/4.0/account/account_uid \
--cookie "openx3_access_token=token_string" \
  --data='{
    "status":"Inactive",
  }'

account_uid is the UID of the account to be updated. Alternatively, you can send the account_id.

Sample update response

The response body includes all of the object’s fields:

[
    {
    "uid" : "account_uid",
    "name": "API+Demo+Advertiser",
    "status":"Inactive",
    "account_id":"account_id",
    "account_type_id":"4",
    "currency_id":"1",
    "timezone_id":"5",
    "country_of_business_id":"us",
    "single_ad_limitation":"0",
    "primary_contact_id":null,
    "billing_contact_id":null,
    "external_id":null,
    "notes":null,
    "uplift":null,
    "requests":null,
    "fill_rate":null,
    "buyer_breakout":null,
    "clicks":null,
    "total_conversions":null
    }
]

Delete

To delete an object, send a DELETE request to its URI.

Sample delete request

curl -X DELETE --header "Content-Type: application/json" http://openx_server_name/ox/4.0/account \
            --cookie "openx3_access_token=token_string" \
        --data='["account_uid_1", "account_uid_2"]'

account_uid_n is the UID of the account to be deleted. Alternatively, you can send account IDs.

Sample delete response

[
    {
    "account_uid_1": true,
    "account_uid_2": true
    }
]

Read

To get the field values for a specific object.

Sample read request

curl -X GET http://openx_server_name/ox/4.0/account/account_uid--cookie "openx3_access_token=token_string"

account_uid_n is the UID of the account to be read.

Sample read response

[
    {
    "uid" : "account_uid",
    "name": "API+Demo+Advertiser",
    "status":"Inactive",
    "account_id":"account_id",
    "account_type_id":"4",
    "currency_id":"1",
    "timezone_id":"5",
    "country_of_business_id":"us",
    "single_ad_limitation":"0",
    "primary_contact_id":null,
    "billing_contact_id":null,
    "external_id":null,
    "notes":null,
    "uplift":null,
    "requests":null,
    "fill_rate":null,
    "buyer_breakout":null,
    "clicks":null,
    "total_conversions":null
    }
]

Sample list request

To list all the objects of the specified type:

curl -X GET http://openx_server_name/ox/4.0/account --cookie "openx3_access_token=token_string"

Batch Operations

Batch operations allow you to create, update, or delete multiple objects in one call.

Sample batch create

curl -X POST --header "Content-Type: application/json" openx_server_name/ox/4.0/account \
--cookie "openx3_access_token=token_string\
--data='[
         {    "account_uid": "[Code]parent_account_uid
               parent_account_id",
              "account_id": "parent_account_uid",
              "name": "Batch Account 1",
              "type_full": "account.publisher",
              "currency": "USD",
              "experience": "publisher"
          },
          {
              "account_uid": "parent_account_idcurl -X POST --header "Content-Type: application/json" http://",
              "account_id": "",
              "name": "Batch Account 2",
              "type_full": "account.advertiser",
              "currency": "USD",
              "experience": "advertiser"
          }
 ]'

Sample batch create response

If the creation is successful, the HTTP response includes 200 Created and a response body such as the following example:

[
{
    "account_uid": "
  parent_account_uid
  instance_uid",
     "acl_override": {},
     "compiled_acl": "__IGNORE__",
     "country_of_business": "us",
     "created_date": "2015-01-01 00:00:00",
     "currency": "USD",
     "currency_id": "1",
     "deleted": "0",
     "experience": "publisher",
     "external_id": null,
     "hidden": "0",
     "id": "__IGNORE__",
     "instance_uid": "parent_account_id",
     "market": null,
     "market_active": "0",
     "modified_date": "2015-01-01 00:00:00",
     "name": "Batch Account 1",
     "notes": "",
     "parent_name": "Parent Account Name",
     "payment_info": null,
     "status": "Active",
     "timezone": "UTC",
     "timezone_id": "1",
     "type": "account",
     "type_full": "account.publisher",
     "uid": "__IGNORE__",
     "v": "3"
 },
 {
     "account_id": "parent_account_uid",
     "account_uid": "instance_uid"
       "acl_override": {},
       "compiled_acl": "__IGNORE__",
       "country_of_business": "us",
       "created_date": "2015-01-01 00:00:00",
       "currency": "USD",
       "currency_id": "1",
       "deleted": "0",
       "exchange": null,
       "experience": "advertiser",
       "external_id": null,
       "has_exchange": false,
       "has_ssrtb": false,
       "hidden": "0",
       "id": "__IGNORE__",
       "instance_uid": "",
       "modified_date": "2015-01-01 00:00:00",
       "name": "Batch Account 2",
       "notes": "",
       "parent_name": "Parent Account Name",
       "single_ad_limitation": "0",
       "status": "Active",
       "timezone": "UTC",
       "timezone_id": "1",
       "type": "account",
       "type_full": "account.advertiser",
       "uid": "__IGNORE__",
       "v": "3"
 }
]

Sample batch delete

curl -X DELETE --header "Content-Type: application/json" http://openx_server_name/ox/4.0/account \
--cookie "openx3_access_token=token_string" \
  --data='["account_uid_1", account_uid_2", "account_uid_3", "account_uid_n]'

Available Fields

You can make an available_fields request to determine an object’s fields and values. Some available_fields requests require URI parameters, but if you do not include them the error response indicates what is needed.

For example, if you call GET /account/available_fields, you will receive the following error response:

Sample `available_fields` error 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
}

This response points out that you need to include a type_full request parameter in your call to the account object. For example, if you append ?type_full=account.publisher to your request, the Ad Server will provide information about all the account fields for an account of type account.publisher.

Sample `available_fields` request with a `type_full` value

openx_server_name/ox/4.0/account/available_fields?type_full=account.publisher --cookie "openx3_access_token=curl -X GET http://token_string"

Sample `available_fields` response

Click to expand sample response

{
  "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": {
    "acl": "acl",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "flags"
  },
  "acl_override": {
    "acl": "publisher.acl_override",
    "available_fields": {
      "publisher.reporting.buyer_breakout.read": {
        "acl": "publisher.acl_override",
        "default": false,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.clicks.read": {
        "acl": "publisher.acl_override",
        "default": false,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.fill_rate.read": {
        "acl": "publisher.acl_override",
        "default": true,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.requests.read": {
        "acl": "publisher.acl_override",
        "default": true,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.total_conversions.read": {
        "acl": "publisher.acl_override",
        "default": false,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.total_impressions.read": {
        "acl": "publisher.acl_override",
        "default": false,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      },
      "publisher.reporting.uplift.read": {
        "acl": "publisher.acl_override",
        "default": false,
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "bool"
      }
    },
    "default": {
      "publisher.reporting.buyer_breakout.read": false,
      "publisher.reporting.clicks.read": false,
      "publisher.reporting.fill_rate.read": true,
      "publisher.reporting.requests.read": true,
      "publisher.reporting.total_conversions.read": false,
      "publisher.reporting.total_impressions.read": false,
      "publisher.reporting.uplift.read": false
    },
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "object"
  },
  "country_of_business": {
    "default": "us",
    "has_dependencies": false,
    "maxlen": 255,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "url": "/options/country_options"
  },
  "created_date": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "datetime"
  },
  "currency": {
    "has_dependencies": false,
    "maxlen": 255,
    "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,
    "maxlen": 64,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "url": "/options/publisher_experience_options"
  },
  "external_id": {
    "has_dependencies": false,
    "maxlen": 255,
    "readonly": false,
    "required": false,
    "type": "varchar"
  },
  "hidden": {
    "acl": "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,
    "maxlen": 255,
    "readonly": true,
    "required": false,
    "type": "varchar"
  },
  "market": {
    "acl": "instance.market_active",
    "available_fields": {
      "allow_unbranded_buyers": {
        "default": "1",
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "int"
      },
      "blocked_adcategories": {
        "has_dependencies": false,
        "items": {
          "has_dependencies": false,
          "maxlen": 255,
          "readonly": false,
          "required": true,
          "type": "varchar",
          "url": "/options/ad_category_options"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "blocked_contentattributes": {
        "has_dependencies": false,
        "items": {
          "has_dependencies": false,
          "maxlen": 255,
          "readonly": false,
          "required": true,
          "type": "varchar",
          "url": "/options/content_attribute_options"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "blocked_creativetypes": {
        "has_dependencies": false,
        "items": {
          "has_dependencies": false,
          "maxlen": 255,
          "readonly": false,
          "required": true,
          "type": "varchar",
          "url": "/options/creative_type_options"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "blocked_languages": {
        "has_dependencies": false,
        "items": {
          "has_dependencies": false,
          "maxlen": 255,
          "readonly": false,
          "required": true,
          "type": "varchar",
          "url": "/options/language_options"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "brand_labels": {
        "available_fields": {
          "label_ids": {
            "has_dependencies": false,
            "items": {
              "has_dependencies": false,
              "maxlen": 255,
              "readonly": false,
              "required": false,
              "type": "varchar",
              "url": "/options/market_brand_group_options"
            },
            "readonly": false,
            "required": false,
            "type": "array"
          },
          "op": {
            "default": "allow_all",
            "has_dependencies": false,
            "maxlen": 255,
            "readonly": false,
            "required": true,
            "type": "varchar",
            "url": "/options/market_filter_region_options"
          }
        },
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "object"
      },
      "brands": {
        "available_fields": {
          "ids": {
            "has_dependencies": false,
            "items": {
              "has_dependencies": false,
              "readonly": false,
              "required": false,
              "type": "int"
            },
            "readonly": false,
            "required": false,
            "type": "array"
          },
          "op": {
            "default": "allow_all",
            "has_dependencies": false,
            "maxlen": 255,
            "readonly": false,
            "required": true,
            "type": "varchar",
            "url": "/options/market_filter_region_options"
          }
        },
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "object"
      },
      "currency": {
        "default": "USD",
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": false,
        "type": "varchar",
        "url": "/options/currency_options"
      },
      "domains": {
        "has_dependencies": false,
        "items": {
          "has_dependencies": false,
          "maxlen": 255,
          "readonly": false,
          "required": true,
          "type": "varchar"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "filters": {
        "has_dependencies": false,
        "items": {
          "available_fields": {
            "ids": {
              "has_dependencies": false,
              "items": {
                "has_dependencies": false,
                "readonly": false,
                "required": true,
                "type": "int"
              },
              "readonly": false,
              "required": false,
              "type": "array"
            },
            "op": {
              "default": "allow_all",
              "has_dependencies": false,
              "maxlen": 255,
              "readonly": false,
              "required": true,
              "type": "varchar",
              "url": "/options/market_filter_region_options"
            },
            "region": {
              "has_dependencies": false,
              "maxlen": 255,
              "readonly": false,
              "required": true,
              "type": "varchar",
              "url": "/options/market_operators"
            }
          },
          "has_dependencies": false,
          "readonly": false,
          "required": false,
          "type": "object"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      }
    },
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "object"
  },
  "market_active": {
    "auto": true,
    "default": "0",
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "market_currency_id": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "modified_date": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "datetime"
  },
  "name": {
    "has_dependencies": false,
    "maxlen": 255,
    "readonly": false,
    "required": true,
    "type": "varchar"
  },
  "notes": {
    "has_dependencies": false,
    "maxlen": 25000,
    "readonly": false,
    "required": false,
    "type": "varchar"
  },
  "payment_info": {
    "acl": "publisher.payment_info",
    "available_fields": {
      "address_1": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "address_2": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": false,
        "type": "varchar"
      },
      "city": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "company_name": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": false,
        "type": "varchar"
      },
      "country": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar",
        "url": "/options/country_options"
      },
      "first_name": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "last_name": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "phone": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "state": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "zip": {
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar"
      }
    },
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "object"
  },
  "revshare": {
    "acl": [
      "publisher.revshare",
      "instance.rev_share"
    ],
    "available_fields": {
      "cost_model": {
        "default": "variable",
        "has_dependencies": false,
        "maxlen": 255,
        "options": [
          "variable",
          "fixed"
        ],
        "readonly": false,
        "required": true,
        "type": "varchar"
      },
      "deal_type": {
        "default": "FIXED_WITH_FILL",
        "has_dependencies": false,
        "maxlen": 255,
        "readonly": false,
        "required": true,
        "type": "varchar",
        "url": "/options/deal_type_options"
      },
      "deal_type_id": {
        "auto": true,
        "default": "1",
        "has_dependencies": false,
        "readonly": true,
        "required": false,
        "type": "int"
      },
      "guaranteed_cpm": {
        "default": "0.0000",
        "has_dependencies": false,
        "maximum": "10000.0000",
        "readonly": false,
        "required": true,
        "type": "decimal(9,4)"
      },
      "house_fallback": {
        "default": "0",
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "int"
      },
      "house_payable": {
        "default": "0",
        "has_dependencies": false,
        "readonly": false,
        "required": true,
        "type": "int"
      },
      "rev_split": {
        "default": "100.00",
        "has_dependencies": false,
        "maximum": "100.00",
        "readonly": false,
        "required": true,
        "type": "decimal(5,2)"
      }
    },
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "object"
  },
  "status": {
    "acl": "publisher.status",
    "default": "Active",
    "has_dependencies": false,
    "maxlen": 12,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "url": "/options/account_status_options"
  },
  "timezone": {
    "default": "UTC",
    "has_dependencies": false,
    "maxlen": 255,
    "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,
    "maxlen": 255,
    "readonly": true,
    "required": false,
    "type": "varchar",
    "value": "account"
  },
  "type_full": {
    "has_dependencies": false,
    "maxlen": 64,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "value": "account.publisher"
  },
  "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"
  }
}

Where:

acl: A field used for permissions that you can typically ignore.
url: A path that you can follow to the base URI to return a list of options. The corresponding field only accepts values that are found in the response to the specified options call.

NOTE
You can also include action=create or action=update when calling the API for available and required fields of an object. For example, the set of required fields for creating a user is different than for updating a user, such as the user.email field, which is required when creating but not when updating.

Pagination

The size of the data displayed in a response is limited by the following request parameters:

limit: The maximum number of items to be returned on a single request. Default value is 10.
offset: The number of the first item to display for the current request, where the offset for first item on the first page is 0 (default).

If there is too much information to display in a single page, the response body includes "has_more": true. You can access the additional values by modifying the offset and limit paging values.

Sample list request including pagination parameters

For example, to list account records 50 through 75, specify an offset of 50 and a limit of 25:

curl -X GET http://openx_server_name/ox/4.0/account?offset=50&limit=25 --cookie "openx3_access_token=token_string"

URI Parameters

The URIs described in the Platform API reference represent the supported request syntax, to which you can add certain supported request parameters. You can include request parameters in your API calls as query string arguments; you can append the first parameter after a question mark (?) and additional parameters separated by ampersands (&) in any order or combination.

The OpenX API supports the various parameters, such as the following:

Parameter	Description
`action`	When calling the API for available and required fields for an object, set this parameter to `action=create` or `action=update` to specify the action for which you want to retrieve values. For example, the set of required fields for creating a user (`/user/available_fields?action=create`) is different than the set of required fields for updating a user (`/user/available_fields?action=update`), such as the `user.email` field, which is required for creating a user but not for updating a user.
`pretty`	(For debugging only) Display the JSON response into a more human readable format. Note: Routine use of the `pretty` parameter negatively impacts performance. Do not use it in your production calls.
Pagination	Pagination parameters. See pagination.
`type_full`	Some `available_fields` calls require this parameter. If so, the error response lists the choices for `type_full` if you do not specify an attribute. For example, when calling `/ad/available_fields`, you can specify the `type_full=ad.image` attribute. This parameter is also used for list operations.

Depending on the resource you are calling, many additional parameters may be available. Making calls without required parameters results in an error response, which typically indicates what was missing from the request. You can call available_fields for an object to see fields listed as required: true.

About IDs and UIDs

OpenX API objects have object_name_id (“ID”) and object_name_uid (“UID”) fields. For example, you can include account_id=string or account_uid=string values in some API calls.

IDs were supported in API v3 and OpenX continues to maintain IDs. UIDs were introduced with API v4 for internal reasons and they are typically interchangeable with IDs. You can usually specify both IDs and UIDs in API requests that include a full JSON object. For an example, see Create.

You do not have to specify UIDs unless they are listed as required by the available_fields create or update response for the object. For example, to create an order, the account_uid is required. If you specify the account_id instead, the call will not work. Use IDs whenever possible and if they’re not available or do not work, use UIDs instead.

PDF