PDF

Working with Demand Objects

Last updated on August 10, 2020

This page describes how to use the API to list or create orders, line items, ads, and creatives.

Retrieving the List of Demand Objects

To retrieve the list of demand objects that the current user has access to, issue one of the following HTTP GET requests:

GET/order to retrieve the list of orders:

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

GET/lineitem to retrieve the list of line items:

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

GET/ad to retrieve the list of ads in alphabetical order:

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

Retrieving Information About a Demand Object

To retrieve information about a specific demand object, query the API using the following:

GET /order/<order_uid>
GET /lineitem/<lineitem_uid>
GET /ad/<ad_uid>

For example, query the API for details about order UID 20003303-c001-fff1-8123-0c9a66:

curl -X GET http://openx_server_name/ox/4.0/order/20003303-c001-fff1-8123-0c9a66 --cookie "openx3_access_token=token_string"

The API returns the attributes and value details for the specific order

[
    {
    "account_id": "537242118",
    "account_uid": "2005aa06-accf-fff1-8123-0c9a66",
    "budget": null,
    "click_through_window": "86400",
    "created_date": "2013-10-10 20:38:49",
    "deleted": "0",
    "end_date": null,
    "external_id": "",
    "id": "536883971",
    "instance_uid": "f2d88c60-cd72-11e2-8b8b-0800200c9a66",
    "modified_date": "2013-10-10 20:38:49",
    "name": " Kcarey_Revshare_SubNetwork1_ExchAdv1_Order1",
    "notes": "",
    "primary_analyst_id": null,
    "primary_analyst_uid": null,
    "primary_trafficker_id": null,
    "primary_trafficker_uid": null,
    "revision": 1,
    "sales_lead_id": null,
    "sales_lead_uid": null,
    "secondary_trafficker_id": null,
    "secondary_trafficker_uid": null,
    "single_ad_limitation": null,
    "start_date": "2013-10-10 00:00:00",
    "status": "Pending",
    "type": "order",
    "uid": "20003303-c001-fff1-8123-0c9a66",
    "v": "3",
    "view_through_window": "86400"
    }
]

Creating an Order

To create an order:

Retrieve the list of accounts to determine the account UID for which you want to create the order.

Retrieve the list of available fields for creating an order.

curl http://openx_server_name/ox/4.0/order/available_fields --cookie "openx3_access_token=token_string"

This returns the list of fields that you can set, and those that are required for creating an order.

{
  "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"
  },
  "budget": {
    "acl": "order.budget",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "decimal(21,2)"
  },
  "click_through_window": {
    "acl": "order.conversion_window",
    "default": "86400",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "int"
  },
  "created_date": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "datetime"
  },...
}

Create the order object passing in at a minimum the required parameters which include:

Parameter	Description
`name`	The name of the new order.
`status`	The status for the new order.
`start_date`	The beginning date for the new order.
`account_uid`	The ID for the advertiser account that the new order belongs to.

For example, create an order for a specified account:

curl http://openx_server_name/ox/4.0/order --cookie "openx3_access_token=token_string" -X POST
      --header "Content-Type:application/json" --data '{"account_uid":
      "20058a53-accf-fff1-8123-0c9a66", "name": "demo_order", "status":
      "Pending", "start_date": "2014-01-21", "view_through_window": "86400",
      "click_through_window": "86400"}'

The API creates the order and returns the ID for the new order object.

Creating a Line Item

Before you create a line item, you must either create the order that you want to create the line item for, or retrieve the list of orders to determine the target order.

To create a new demand line item:

Get the list of available fields for creating a line item:

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

The following error response indicates that a type_full value is required:

{
    "attribute": "type_full",
    "choices": [
    "lineitem.exchange",
    "lineitem.house",
    "lineitem.preferred",
    "lineitem.exclusive",
    "lineitem.share_of_voice",
    "lineitem.volume_goal",
    "lineitem.non_guaranteed"
    ],
    "field": {},
    "http_status": 400,
    "message": "Field type_full value must be one of \"lineitem.exchange\", \"lineitem.house\", \"lineitem.preferred\", \"lineitem.exclusive\", \"lineitem.share_of_voice\", \"lineitem.volume_goal\" or \"lineitem.non_guaranteed\" (\"None\" not allowed)",
    "type": "Value Error",
    "value": null
}

Modify the request by adding a type_full URI parameter:

curl -X GET http://openx_server_name/ox/4.0/lineitem/available_fieldstype_full=lineitem.house --cookie
      "openx3_access_token=token_string"

The response lists the fields that you can set and those that are required for creating a line item:

{
  "account_id": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "account_uid": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "account_uid"
  },
  "ad_delivery": {
    "acl": "lineitem.ad_delivery_mode",
    "default": "equal",
    "has_dependencies": false,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "url": "/options/ad_delivery_options"
  },
  "ad_delivery_id": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "buyer_id": {
    "acl": "instance.json_flags.programmatic_premium",
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "buyer_uid": {
    "acl": "instance.json_flags.programmatic_premium",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "uid",
    "url": "/options/market_advertiser_options"
  },...
}

You can retrieve details about fields that include a url value. For example, ad_delivery includes the following value: “url”: "/options/ad_delivery_options"
```
curl -X GET http://openx_server_name/ox/4.0/options/ad_delivery_options --cookie
      "openx3_access_token=token_string"
```

Create the line item object passing in at a minimum the following required parameters:

Parameter	Description
`ad_delivery`	The ad delivery method.
`name`	The name of the line item.
`status`	The status of the line item.
`order_uid`	The ID for the order that the line item belongs to.
`start_date`	The beginning date for the line item.
`rtb_data_required`	The matched user requirement.
`delivery_medium`	The delivery medium.
`targeting`	The targeting rules.
`type_full`	The type of line item.

For example, create a house line item:

curl -X POST --header "Content-Type: application/json" http://openx_server_name/ox/4.0/lineitem \
--cookie "openx3_access_token=token_string" \
  --data='{
    "ad_delivery":"manual",
    "delivery_medium":"WEB",
    "name":"Demo line item",
    "status":"Pending",
    "order_uid":"20004055-c001-fff1-8123-0c9a66",
    "start_date":"now",
    "rtb_data_required":"1",
    "targeting":{"geographic":{"value_count":0},"content":{"value_count":0},"inter_dimension_operator":"OR"},
    "type_full":"lineitem.house",
    "account_uid":"2005aa92-accf-fff1-8123-0c9a66"
    }'

The API creates the line item and returns the UID for the new line item object.

Creating an Ad

NOTE
Flash support deprecation: July 3, 2017. After this date, Flash creatives will be blocked. You may still see Flash-related options as OpenX makes updates to the user interface and API.

To create an ad:

Create a line item and retrieve its UID, or retrieve the list of line items to determine the one to create the ad for.
Upload a creative.
Create a creative.

Get the list of available fields for creating an ad:

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

The following error response indicates that a type_full value is required:

{
    "attribute": "type_full",
    "choices": [
    "ad.nonlinearvast",
    "ad.nonlinearvideo.html",
    "ad.linearvast",
    "ad.mobile",
    "ad.image",
    "ad.linearvideo",
    "ad.thirdparty",
    "ad.exchange.ssrtb",
    "ad.nonlinearvideo.image",
    "ad.exchange.image",
    "ad.exchange.html",
    "ad.programmatic",
    "ad.html",
    "ad.exchange.thirdparty",
    "ad.mobilehtml"
    ],
    "field": {},
    "http_status": 400,
    "message": "Field type_full value must be one of \"ad.nonlinearvast\", \"ad.nonlinearvideo.html\", \"ad.linearvast\", \"ad.mobile\", \"ad.image\", \"ad.linearvideo\", \"ad.thirdparty\", \"ad.exchange.ssrtb\", \"ad.nonlinearvideo.image\", \"ad.exchange.image\", \"ad.exchange.html\", \"ad.programmatic\", \"ad.html\", \"ad.exchange.thirdparty\" or \"ad.mobilehtml\" (\"None\" not allowed)",
                    "type": "Value Error",
                    "value": null
                    }

Modify the request by adding a type_full URI parameter. For example, retrieve the list of available fields for an image ad:

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

This returns the list of fields that you can set, and those that are required, for creating an image ad.

{
  "account_id": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int"
  },
  "account_uid": {
    "auto": true,
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "account_uid"
  },
  "ad_type_id": {
    "auto": true,
    "default": "1",
    "has_dependencies": false,
    "readonly": true,
    "required": false,
    "type": "int",
    "value": "1"
  },
  "ad_weight": {
    "acl": "ad.weight",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "decimal(4,1)"
  },
  "alt_text": {
    "acl": "ad.alt_text",
    "has_dependencies": false,
    "readonly": false,
    "required": false,
    "type": "varchar"
  },
  "click_target_window": {
    "acl": "ad.click_info",
    "default": "_self",
    "has_dependencies": false,
    "readonly": false,
    "required": true,
    "type": "varchar",
    "url": "/options/click_target_window_options"
  },...
 }

Create the image ad object passing in at a minimum the following required parameters:

Parameter	Description
`name`	The name for the new image ad.
`status`	The status of the new ad.
`ad_type_id`	The ID for the type of ad you are creating, such as image.
`line_item_uid`	The UID for the line item that the new ad belongs to.
`size`	The size of the ad.
`primary_creative_uid`	The UID of the creative.
`click_url`	The click URL for the image ad.
`click_target_window`	The click target window for the image ad.
`type_full`	The type of ad.

For example, create an image ad:

curl -X POST --header "Content-Type: application/json" http://openx_server_name/ox/4.0/ad \
        --cookie "openx3_access_token=token_string" \
        --data='{
        "name":"Demo image ad",
        "status":"Active",
        "start_date":"now",
        "click_target_window":"_blank",
        "click_url":"http://www.example.com",
        "line_item_uid":"20004055-c001-fff1-8123-0c9a66",
        "primary_creative_uid":"null",
        "size":"300x600",
        "type_full":"ad.image"
        }'

The API creates the image ad and returns the ID for the new image ad object.

PDF