Link Search Menu Expand Document

PDF

Working with Inventory

Platform API

Last updated on August 10, 2020


This page describes how to use the Platform API to manage inventory objects.


on this page


Retrieving the List of Inventory Objects

To retrieve the lists of inventory objects to which the current user has access:

  1. List all sites:

     curl http://openx_server_name/ox/4.0/site --cookie "openx3_access_token=token_string"
    
  2. List all site sections:

     curl http://openx_server_name/ox/4.0/sitesection --cookie "openx3_access_token=token_string"
    
  3. List all ad units:

     curl http://openx_server_name/ox/4.0/adunit --cookie "openx3_access_token=token_string"
    
  4. List all packages:

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

Retrieving Information About Specific Inventory Objects

To retrieve information about specific inventory objects, use the UIDs from the list responses for the following calls:

  1. Read the site with the specified UID:

     curl http://openx_server_name/ox/4.0/site/2000002b-e000-fff1-8123-0c9a66 --cookie "openx3_access_token=token_string"
    
  2. Read the site section with the specified ID:

     curl http://openx_server_name/ox/4.0/sitesection/536870925 --cookie "openx3_access_token=token_string"
    
  3. Read the ad unit with the specified ID:

     curl http://openx_server_name/ox/4.0/adunit/536871402 --cookie "openx3_access_token=token_string"
    
  4. Read the package with the specified ID:

     curl http://openx_server_name/ox/4.0/package/536870936 --cookie "openx3_access_token=token_string"
    

Creating a Site

To create a site:

  1. See working with accounts to determine the account for which you want to create a site.

  2. Retrieve the list of available fields for creating a site.

    curl http://openx_server_name/ox/4.0/site/available_fields?account_uid=publisher_account_UID
    

    This returns the list of fields that you can set and those that are required for creating a site.

    {
      "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"
      },
      "autorefresh": {
        "acl": "site.auto_refresh",
        "has_dependencies": false,
        "items": {
          "available_fields": {
            "refresh_country": {
              "has_dependencies": false,
              "readonly": false,
              "required": false,
              "type": "varchar",
              "url": "/options/country_options"
            },
            "refresh_delay": {
              "has_dependencies": false,
              "readonly": false,
              "required": true,
              "type": "int"
            },
            "refresh_max": {
              "has_dependencies": false,
              "readonly": false,
              "required": true,
              "type": "int"
            }
          },
          "has_dependencies": false,
          "readonly": false,
          "required": false,
          "type": "object"
        },
        "readonly": false,
        "required": false,
        "type": "array"
      },
      "category_override": {
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "int"
      },
      "content_topic": {
        "acl": "site.default_content_settings",
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "int",
        "url": "/options/content_topic_options"
      },...
    }
    
  3. Create the site object, passing in at a minimum the following required parameters:

    • account_uid: UID of the publisher account
    • name: Name for the new site
    • status: Status for the site, which is described by /options/status_options_common
    • url: URL for the site

    For example, create a site for the web delivery medium:

    curl http://openx_server_name/ox/4.0/site --cookie "openx3_access_token=token_string" -X POST
          --header "Content-Type:application/json" --data '{"account_uid":
          "account_uuid_goes_here", "name": "desired_site_name", "status":
          "Active", "url": "http://www.example.com", "delivery_medium_id": "2"}'
    

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


Creating an Ad Unit

To create an ad unit:

  1. Retrieve the list of sites to determine the one to create the ad unit for.

  2. Retrieve the list of available fields for creating an ad unit:

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

    The following error response indicates that the type_full attribute is needed:

    {
    	"http_status": 400,
    	"type": "Value Error",
    	"message": "Field type_full value must be one of \"adunit.email\", \"adunit.linearvideo\", \"adunit.mobile\", \"adunit.native\", \"adunit.nonlinearvideo\", \"adunit.placement\", \"adunit.videocompanion\" or \"adunit.web\" (\"None\" not allowed)",
    	"value": null,
    	"attribute": "type_full",
    	"field": {
    
    	},
    	"choices": [
    	"adunit.email",
    	"adunit.linearvideo",
    	"adunit.mobile",
    	"adunit.native",
    	"adunit.nonlinearvideo",
    	"adunit.placement",
    	"adunit.videocompanion",
    	"adunit.web"
    	]
    }
    
  3. Specify the desired type_full value, such as adunit.web in the following sample:

    curl http://openx_server_name/ox/4.0/adunit/available_fields?type_full=adunit.web --cookie "openx3_access_token=token_string"
    

    When using adunit.mobile for the type_full value, you must also pass in the site_uid. For example:

    curl http://openx_server_name/ox/4.0/adunit/available_fields?type_full=adunit.mobile&site_uid=site_uid --cookie "openx3_access_token=token_string"
    

    This returns the list of fields that you can set and those that are required for creating a web ad unit:

    {
      "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"
      },
      "alt_sizes": {
        "acl": "adunit.addl_sizes",
        "has_dependencies": false,
        "readonly": false,
        "required": false,
        "type": "varchar",
        "url": "/options/web_size_options"
      },...
    }
    
  4. Create the ad unit object by passing in at a minimum the following required parameters:

    • site_uid: ID for the site that the ad unit belongs to.
    • name: Name for the ad unit.
    • status: Status for the ad unit (Active or Inactive).
    • delivery_medium_id: ID for the delivery medium that the new ad unit is intended to run on.
    • tag_type_id: ID for the type of ad tag to use to request ads for this ad unit, such ad image or JavaScript.
    • type_full: Type of ad unit such as adunit.web.

    For example, create a web ad unit:

    curl http://openx_server_name/ox/4.0/adunit --cookie "openx3_access_token=token_string" -X POST --header "Content-Type:application/json" --data '{"site_uid":
     "site_uid_goes_here", "name": "desired_adunit_name", "status": "Active", "delivery_medium_id": "2", "type_full": "adunit.web", "primary_size": "300x250"}'
    

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