Introduction

Placements API v1 is a RESTful service and follows JSON api specification. Currently, the API covers:

Authentication and Authorization
Create, update and retrieval of various resources (see Resources)

More functionality will be added over time.

Base Endpoint

https://api.placements.io/v1

Authentication

Example request to retrieve a list of Accounts:

curl 'https://api.placements.io/v1/accounts' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Two authentication mechanisms are supported: Personal Access Token and OAuth2. Either way you will receive an access token (see below for detailed instructions).

To access the Placements API, set the token as a "Bearer Authorization" header in your HTTP request.

Be sure to replace YOUR_ACCESS_TOKEN with your actual access token!

Personal Access Token

A user can generate a Personal Access Token to directly access Placements API. Please keep in mind that any operation by this means is treated exactly like the user operated through UI. Please protect your Personal Access Token just like your normal login credentials.

Please talk to your admin first for API access. Once granted access, a user can go to API Access to generate a new token or list / revoke / regenerate existing tokens.

OAuth2

Note: replace YOUR_APPLICATION_ID, YOUR_APPLICATION_SECRET, YOUR_REDIRECT_URL and YOUR_AUTH_CODE with your actual data!

Example request your server sends to exchange auth code into access token:

curl 'https://api.placements.io/oauth/token' \
     -H "Content-Type: application/json" \
     -X POST -d "{\"client_id\":\"YOUR_APPLICATION_ID\",\"client_secret\":\"YOUR_APPLICATION_SECRET\",\"redirect_uri\":\"YOUR_REDIRECT_URL\",\"grant_type\":\"authorization_code\",\"code\":\"YOUR_AUTH_CODE\"}"

You will get back an access token and a refresh token:

{
  "access_token":"YOUR_ACCESS_TOKEN",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"YOUR_REFRESH_TOKEN",
  ...
}

Example request to refresh the tokens:

curl 'https://api.placements.io/oauth/token' \
     -H "Content-Type: application/json" \
     -X POST -d "{\"client_id\":\"YOUR_APPLICATION_ID\",\"client_secret\":\"YOUR_APPLICATION_SECRET\",\"grant_type\":\"refresh_token\",\"refresh_token\":\"YOUR_REFRESH_TOKEN\"}"

If it is a 3rd party application that needs to access Placements API on behalf of a user, OAuth2 is more appropriate. Specifically we support OAuth2 Authorization Code Grant for such 3rd party apps.

First, the 3rd party application developer needs to register the app with Placements. For now it is a manual process, please contact us with the following information:

the application name
the redirect URL: if the user authorizes your app to access his/her data inside Placements, your app will receive the authorization code at this URL

After successful registration, we will give you back:

Application Id
Application Secret

Your app will need both pieces of information to obtain an OAuth2 Access Token. The flow for getting an OAuth2 Access Token is as follows:

If the user has not given your app authorization yet, you need to ask the user to authorize your app by following a link, for example (notice that you need to replace YOUR_APPLICATION_ID and YOUR_REDIRECT_URL with your actual data): https://api.placements.io/oauth/authorize?client_id=YOUR_APPLICATION_ID&redirect_uri=YOUR_REDIRECT_URL&response_type=code
the user will be presented to login to Placements and authorize your app
then the user will be redirected to the URL you specified above, with an authorization code as query parameter, for example: YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE.

The server at your redirect URL needs to extract the authorization code, then send a POST request to exchange it into an OAuth2 access token. Note that for security purpose, the authorization code will only be valid for 10 minutes.

The access token will be valid for 2 hours, afterwards you will need to refresh with the lastest refresh token to get a new set of access token and refresh token.

As long as the user does not revoke the authorization, your app will continue to be able to obtain new sets of access token and refresh token in such a manner.

Common API Actions

The API supports a common set of actions for all resources. Below we will be using opportunity resource as an example.

List

curl 'https://api.placements.io/v1/opportunities' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "data": [
    {
      "id": "8",
      "type": "opportunities",
      "links": {
        "self": "https://api.placements.io/v1/opportunities/8"
      },
      "attributes": {
        "name": "Test RFP ",
        "close-date": "2015-07-31",
        ...
      },
      "relationships": {
        "advertiser": {
          "links": {
            "self": "https://api.placements.io/v1/opportunities/8/relationships/advertiser",
            "related": "https://api.placements.io/v1/opportunities/8/advertiser"
          },
          "data": {
            "type": "accounts",
            "id": "1912"
          }
        },
      }
    },
    ...
  ],
  "meta": {
    "record-count": 1524,
    "page-count": 153
  },
  "links": {
    "first": "https://api.placements.io/v1/opportunities?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "next": "https://api.placements.io/v1/opportunities?page%5Bnumber%5D=2&page%5Bsize%5D=10",
    "last": "https://api.placements.io/v1/opportunities?page%5Bnumber%5D=153&page%5Bsize%5D=10"
  }
}

GET resources will return a list of resources. Notice that each resource will have different attributes and relationships. See corresponding section in Resources for specific details.

List with Pagination

For the 2nd page of results, and each page contains 3 entries (notice that [ and ] are URL encoded for curl):

curl 'https://api.placements.io/v1/opportunities?page%5Bnumber%5D=2&page%5Bsize%5D=3' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

By default, list returns the first page of results, with each page contains 10 entries. You can derive paging information from the meta and links section. To change how many entries each page contains, use the page[size] parameter (currently the max size allowed is 200). To change which page of results to return, use the page[number] parameter.

List with Select Attributes (aka Sparse Fieldsets)

If you only want "name" and "description" in the results (notice that [ and ] are URL encoded for curl):

curl 'https://api.placements.io/v1/opportunities?fields%5Bopportunities%5D=name,description' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

By default, all attributes are returned. It is possible to return only specific attributes with the fields[TYPE] parameter.

List with Filter Results

To filter opportunities (notice that [, ] and are URL encoded for curl):

# id "100" or "101"
curl 'https://api.placements.io/v1/opportunities?filter%5Bid%5D=100,101' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# modified since 2019-01-20 05:04
curl 'https://api.placements.io/v1/opportunities?filter%5Bmodified-since%5D=2019-01-20T05:04Z' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# name "Test 1"
curl 'https://api.placements.io/v1/opportunities?filter%5Bname%5D=Test%201' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# uid "9835e019f6d316"
curl 'https://api.placements.io/v1/opportunities?filter%5Buid%5D=9835e019f6d316' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

It is also possible to filter resources with the filter[] parameter. Currently the following common ones are supported:

Filter	Description	Param Example
id	resources by id	`filter[id]=100`
modified-since	resources modified since a given timestamp	`filter[modified-since]=2019-01-20T05:04Z`
name	resources by exact name match (only when 'name' is a valid attribute)	`filter[name]=foo`
uid	resources by uid (only when 'uid' is a valid attribute)	`filter[uid]=barbaz`

Some resources support additional filters. See corresponding section in Resources for specific details. More filtering capabilities might come later.

Get

curl 'https://api.placements.io/v1/opportunities/1764' \
     -H 'Authorization:bearer YOUR_ACCESS_TOKEN'

{
  "data": {
    "id": "1764",
    "type": "opportunities",
    "links": {
      "self": "https://api.placements.io/v1/opportunities/1764"
    },
    "attributes": {
      "name": "offline recur1ng ",
      ...
    },
    "relationships": {
      "advertiser": {
        "links": {
          "self": "https://api.placements.io/v1/opportunities/1764/relationships/advertiser",
          "related": "https://api.placements.io/v1/opportunities/1764/advertiser"
        },
        "data": {
          "type": "accounts",
          "id": "67793"
        }
      },
      ...
    }
  }
}

GET resources/ID will return one resource.

If you want to include the data of the related "bill-to-account" in the response:

curl 'https://api.placements.io/v1/opportunities/1764?include=bill-to-account' \
     -H 'Authorization:bearer YOUR_ACCESS_TOKEN'

{
  "data": {
    "id": "1764",
    "type": "opportunities",
    "attributes": {
      ...
    },
    "relationships": {
      ...
      "bill-to-account": {
        ...
        "data": {
          "type": "accounts",
          "id": "67793"
        }
      },
      ...
    }
  },
  "included": [
    {
      "id": "67793",
      "type": "accounts",
      ...
      "attributes": {
        ...
      }
    }
  ]
}

By default, the relationship data only contains resource type and id. It is also possible to include the data of the related resources in the response, by specifying the include parameter.

Create

curl 'https://api.placements.io/v1/opportunities' \
     -H 'Authorization:bearer YOUR_ACCESS_TOKEN'  \
     -H 'Content-Type:application/vnd.api+json' \
     -X POST -d '{"data":{"type":"opportunities", "attributes":{"name":"test opp 1", "close-date": "2018-08-07", "stage-name": "Lead"}, "relationships": {"advertiser": {"data": {"type": "accounts","id": "38"}}} }}'

{
  "data": {
    "id": "1767",
    "type": "opportunities",
    "attributes": {
      ...
    },
    "relationships": {
      "advertiser": {
        "data": {
          "type": "accounts",
          "id": "67793"
        }
      },
      ...
    }    
  }
}

POST resources with appropriate payload will create, then return a new resource.

Note that you must set the correct header Content-Type: application/vnd.api+json

Update

curl 'https://api.placements.io/v1/opportunities/1767' \
     -H 'Authorization:bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type:application/vnd.api+json' \
     -X PATCH -d '{"data":{"id": "1767","type":"opportunities", "attributes":{"budget":"1000"} }}'

{
 "data": {
   "id": "1767",
   "type": "opportunities",
   "attributes": {
     ...
   },
   "relationships": {
     "advertiser": {
       "data": {
         "type": "accounts",
         "id": "67793"
       }
     },
     ...
   }    
 }
}

PATCH resources/ID with appropriate payload will update, then return the resource.

Note that you must set the correct header Content-Type: application/vnd.api+json

Delete

DELETE resources/ID will delete the resource. Note that we currently do NOT allow deletion yet.

Resources

Accounts

Example account (abbreviated for clarity):

{
  "data": {
    "id": "100268",
    "type": "accounts",
    "links": {
      "self": "https://api.placements.io/v1/accounts/100268"
    },
    "attributes": {
      "name": "The Home Depot",
      ...
      "ad-server-info": [
        {
          "ad-server": "dfp",
          "ad-server-id": 20227938,
          "ad-server-network-code": "88650439"
        }
      ],
      "freewheel-industries": [
        "12345",
        "54321"
      ],
      "madhive-iab-category-id": "IAB1",
      "octillion-iab-category-id": "IAB1",
      ...
    }
  }
}

Base: https://api.placements.io/v1/accounts

Data "type" is "accounts", identified by "id"

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"account 1"	required
description	String	""
account-type	String (Enum)	"ADVERTISER", "AGENCY", "AGENCY_HOLDING_COMPANY", "PARTNER", "BRAND", "VIEWABILITY_PROVIDER" or ""
category	String (Enum)	"Agriculture", "Apparel", "Banking", "Biotechnology", "Chemicals", "Communications", "Construction", "Consulting", "Education", "Electronics", "Energy", "Engineering", "Entertainment", "Environmental", "Finance", "Food & Beverage", "Government", "Healthcare", "Hospitality", "Insurance", "Machinery", "Manufacturing", "Media", "Not For Profit", "Recreation", "Retail", "Shipping", "Technology", "Telecommunications", "Transportation", "Utilities", "Other"
credit-status	String (Enum)	"ON_HOLD", "ACTIVE", "CREDIT_STOP", "INACTIVE" or "BLOCKED"
commission	Number	0.01
currency-code	String	"USD"
external-id	String	""
street-address1	String	""
street-address2	String	""
city	String	""
state	String	""
zip	String	""
country	String	""
time-zone	String	"Pacific Time (US & Canada)"
website	String	""
phone	String	""
fax	String	""
email	String	""
salesforce-id	String	"00781000000DdL2588"
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
ad-server-info	Array(Object)	(see example)	read-only
netsuite-id	String	""
payment-terms	String	"Net 30"
created-at	DateTime	"2018-08-22T22:54:09.023Z"	read-only
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
freewheel-industries	Array(String)	(see example)
uid	String	"e0864c2afd9ce9"
madhive-iab-category-id	String	(see example)
octillion-iab-category-id	String	(see example)
yahoo_dsp_iab_category_id	String	"4"
yahoo_dsp_iab_secondary_category_id	String	"402"

Relationships

Name	Type	Notes
advertiser-of-record	Account	(only applicable to Brand)
agency-of-record	Account	(only applicable to Advertiser)
contacts	Array(Contact)
rate-card	Rate Card

Additional Filters

Filter	Description	Param Example
account-type	by account type	`filter[account-type]=AGENCY`
external-id	by external id	`filter[external-id]=101`
salesforce-id	by salesforce id	`filter[salesforce-id]=ABCD`
archived	by archived	`filter[archived]=false`
advertiser-of-record	by the id of the advertiser of record	`filter[advertiser-of-record]=101`
agency-of-record	by the id of the advertiser of record	`filter[agency-of-record]=101`
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
ad-server-id	by ad server id	`filter[ad-server-id]=999`

Campaigns

Example campaign (abbreviated for clarity):

{
  "data": {
    "id": "41",
    "type": "campaigns",
    "links": {
      "self": "https://api.placements.io/v1/campaigns/41"
    },
    "attributes": {
      "name": "Test Campaign 1",
      ...
      "trafficker-info": {
        "email": "[email protected]"
      },
      "sales-planner-info": {
        "email": "[email protected]"
      },
      "primary-salesperson-info": {
        "email": "[email protected]",
        "split-percent": 80
      },
      "secondary-salespeople-info": [
        {
          "email": "[email protected]",
          "split-percent": 20
        }
      ],
      "ad-server-info": [
        {
          "ad-server": "dfp",
          "ad-server-id": 20227938,
          "ad-server-network-code": "88650439"
        }
      ],
      ...
    },
    "relationships": {
      "advertiser": {
        "links": {
          "self": "https://api.placements.io/v1/campaigns/41/relationships/advertiser",
          "related": "https://api.placements.io/v1/campaigns/41/advertiser"
        },
        "data": {
          "type": "accounts",
          "id": "3549"
        }
      },
      ...
    }
  }
}

Base: https://api.placements.io/v1/campaigns

Data "type" is "campaigns", identified by "id".

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"campaign 1"	required
description	String	""
start-date	DateTime	"2018-08-23T00:00:00.000Z"	required
end-date	DateTime	"2018-08-24T00:00:00.000Z"	required
time-zone	String	"Pacific Time (US & Canada)"
currency-code	String	"USD"	required
budget	Number	100.00
po-number	String	""
probability	Number	75
campaign-agency-commission	Number	5
approval-status	String (Enum)	"draft", "pending_review", "reviewed", or "partially_reviewed"	read-only
delivery-status	String	"live"	read-only
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
trafficker-info	Object	(see example)
sales-planner-info	Object	(see example)
primary-salesperson-info	Object	(see example)
secondary-salespeople-info	Array(Object)	(see example)
ad-server-info	Array(Object)	(see example)	read-only
billing-source	String (Enum)	"contracted", "first_party_actuals", or "third_party_actuals"
billing-schedule	String (Enum)	"prepaid", "straightline"
billing-cap	String (Enum)	"no_cap", "cap_contracted" or "cap_per_billing_cycle"
billing-period	String (Enum)	"monthly", "broadcast"
external-id	String	""
campaign-number	Number	42	read-only
payment-terms	String	"Net 30"
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
uid	String	"e0864c2afd9ce9"

Relationships

Name	Type	Notes
advertiser	Account	required
agency	Account
agency-holding-company	Account
brand	Account
partner	Account
bill-to-account	Account
opportunity	Opportunity
owner	User
rate-card	Rate Card
line-items	Array(Line Item)
groups	Array(Group)

Additional Filters

Filter	Description	Param Example
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
ad-server-id	by ad server id	`filter[ad-server-id]=999`
archived	by archived	`filter[archived]=false`
campaign-number	by campaign number	`filter[campaign-number]=101`
external-id	by external id	`filter[external-id]=101`

Contacts

Example contact (abbreviated for clarity):

{
  "data": {
    "id": "1337",
    "type": "contacts",
    "links": {
      "self": "https://api.placements.io/v1/contacts/1337"
    },
    "attributes": {
      "first-name": "Jon",
      "last-name": "Snow",
      "email": "[email protected]",
      ...
    },
    "relationships": {
      "account": {
        "links": {
          "self": "https://api.placements.io/v1/contacts/1337/relationships/account",
          "related": "https://api.placements.io/v1/contacts/1337/account"
        },
        "data": {
          "type": "accounts",
          "id": "80085"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/contacts

Data "type" is "contacts", identified by "id".

Attributes

Name	Type	Sample Value	Notes
comments	String	""
email	String	"[email protected]"
external-id	String	""
first-name	String	"Jon"	required
last-name	String	"Snow"	required
phone	String	"555.555.5555"
title	String	""
street	String	""
street2	String	""
city	String	"Seattle"
state	String	"WA"
zip	String	"98104"
country	String	"USA"
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
last-modified	DateTime	"2018-04-20T16:20:12.345Z"
salesforce-id	String	""
uid	String	"e0864c2afd9ce9"

Relationships

Name	Type	Notes
account	Account	required

Additional Filters

Filter	Description	Param Example
external-id	by external id	`filter[external-id]=101`
salesforce-id	by salesforce id	`filter[salesforce-id]=ABCD`

Creatives (BETA)

Example creative (abbreviated for clarity):

{
  "data": {
    "id": "7",
    "type": "creatives",
    "links": {
      "self": "https://api.placements.io/v1/creatives/7"
    },
    "attributes": {
      "last-modified": "2024-05-09T01:08:09.462Z",
      "ad-server-network-code": "12345678",
      "name": "test apn creative c3",
      "ad-server": "app_nexus",
      "ad-server-id": "998855",
      "creative-type": "standard",
      "status": "ACTIVE",
      "width": null,
      "height": null,
      "click-target": null,
      "media-url": null
    },
    "relationships": {
      "account": {
        "links": {
          "self": "https://api.placements.io/v1/creatives/7/relationships/account",
          "related": "https://api.placements.io/v1/creatives/7/account"
        },
        "data": {
          "type": "accounts",
          "id": "2"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/creatives

Data "type" is "creatives", identified by "id".

Attributes

Name	Type	Sample Value	Notes
name	String	"creative 1"	required
ad-server	String	"app_nexus"	required
ad-server-id	String
creative-type	String	"standard", "video"	required
status	String	"ACTIVE" or "INACTIVE"	required
width	Number	100
height	Number	100
click-target	String
media-url	String
audit-status	String		read-only
ad-server-network-code	String	"12345678"
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Relationships

Name	Type	Notes
account	Account	required

Additional Filters

Filter	Description	Param Example
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
ad-server-id	by ad server id	`filter[ad-server-id]=999`

Custom Fields

Example custom fields (abbreviated for clarity):

{
  "data": {
    "id": "999",
    "type": "custom-fields",
    "links": {
      "self": "https://api.placements.io/v1/custom_fields/999"
    },
    "attributes": {
      "last-modified": "2023-05-14T22:31:43.243Z",
      "active": false,
      "name": "XXXXXXX",
      "default-values": null,
      "entity": "Account",
      "field-type": "TEXT",
      "required": false,
      "values": null
    }
  }
}

Base: https://api.placements.io/v1/custom_fields

Data "type" is "custom-fields", identified by "id".

Attributes

Name	Type	Sample Value	Notes
name	String	"custom field 1"	required
entity	String (Enum)	"Account", "Bundle", "Campaign", "Contact", "Invoice", "LineItem", "Rfp", "BudgetLineItem", "PioProductTemplate", "PioProductPackage"	required
field-type	String (Enum)	"TEXT", "NUMBER", "DROPDOWN", "MULTI_SELECT"	required
required	Boolean	false
separator	String	","	For `entity` "MULTI_SELECT"
values	Key value pairs	{"1" => "value 1", "2" => "value 2"}	The key is value id and the value is value label. For `entity` "DROPDOWN" or "MULTI_SELECT"
default-values	Array (String)	["1"]	Array of id in `values`. For `entity` "DROPDOWN" or "MULTI_SELECT"
archived-values	Array (String)	["3"]	Array of id in `values`. For `entity` "DROPDOWN" or "MULTI_SELECT"

External Users (BETA)

Example external user (abbreviated for clarity):

{
  "data": {
    "id": "8",
    "type": "external-users",
    "attributes": {
      "last-modified": "2023-09-23T01:46:52.824Z",
      "ad-server-info": [
        {
          "ad-server": "dfp",
          "ad-server-id": 123990000,
          "ad-server-network-code": "88650439"
        },
      ],
      "email": "[email protected]",
      "first-name": "Cecile",
      "last-name": "Auer",
      "uid": "425351c6cd85df"
    },
    "relationships": {
      "user": {
        "data": {
          "type": "users",
          "id": "47"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/external_users

Data "type" is "external-users", identified by "id".

Attributes

Name	Type	Sample Value	Notes
email	String	""	required
first-name	String	""
last-name	String	""
salesforce-id	String	""
uid	String	"e0864c2afd9ce9"
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Additional Filters

Filter	Description	Param Example
email	by email	`filter[email][email protected]`
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
ad-server-id	by ad server id	`filter[ad-server-id]=999`

Groups

Known colloquially as the Bundle entity (as mentioned in Custom Fields doc above)

Example group:

{
  "data": {
    "id": "338",
    "type": "groups",
    "links": {
      "self": "https://api.placements.io/v1/groups/338"
    },
    "attributes": {
      "last-modified": "2023-08-30T23:14:59.115Z",
      "ad-server-network-code": "88650439",
      "custom-fields": null,
      "active": true,
      "archived": null,
      "ad-server": null,
      "ad-server-id": null,
      "bill-by-bundle": null,
      "billable": null,
      "billing-cap": null,
      "billing-schedule": null,
      "billing-source": null,
      "budget": "55552.50",
      "contracted-units": 12345,
      "cost-basis": "CPC",
      "cost-per-unit": "4.50",
      "currency-code": "USD",
      "description": null,
      "end-date": "2022-09-09T06:59:59.999Z",
      "name": "renamed label, does it still show the product name here? (2)",
      "pricing-budget-type": "PRICING_BUDGET_TYPE_REVENUE",
      "start-date": "2022-08-31T07:00:00.000Z",
      "time-zone": "Pacific Time (US & Canada)"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://api.placements.io/v1/groups/338/relationships/campaign",
          "related": "https://api.placements.io/v1/groups/338/campaign"
        },
        "data": {
          "type": "campaigns",
          "id": "4994"
        }
      },
      "line-items": {
        "links": {
          "self": "https://api.placements.io/v1/groups/338/relationships/line_items",
          "related": "https://api.placements.io/v1/groups/338/line_items"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/groups

Data "type" is "groups", identified by "id".

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"le grp 1"	required
description	String	""
ad-server	String (Enum)	"app_nexus", "dfp", or "offline"
ad-server-id	String	""
ad-server-network-code	String	"88650439"
start-date	DateTime	"2018-08-23T00:00:00.000Z"
end-date	DateTime	"2018-08-24T00:00:00.000Z"
time-zone	String	"Pacific Time (US & Canada)"
currency-code	String	"USD"
budget	Number	100.00
cost-basis	String (Enum)	"CPA", "CPC", "CPD", "CPE", "CPM", "CPU", "CPVM" or "FIXED"
cost-per-unit	Number	0.02
contracted-units	Number	100
billing-source	String (Enum)	"contracted", "first_party_actuals", or "third_party_actuals"
billing-schedule	String (Enum)	"prepaid", "straightline"
billing-cap	String (Enum)	"no_cap", "cap_contracted" or "cap_per_billing_cycle"
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
pricing-budget-type	String (Enum)	"PRICING_BUDGET_TYPE_REVENUE", or "PRICING_BUDGET_TYPE_IMPRESSIONS"	Defaults to "Pricing_BUDGET_TYPE_REVENUE". To represent a budget-type of "None", just keep it as revenue (default pricing-budget-type) with a group-budget of zero. When talking about impressions-based pricing, please set the group's contracted-units value accordingly.

Relationships

Name	Type	Notes
campaign	Campaign	required on create
line-items	Array(Line Item)

Additional Filters

Filter	Description	Param Example
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
ad-server-id	by ad server id	`filter[ad-server-id]=999`
campaign	by the id of the parent campaign	`filter[campaign]=101`

Advanced

For Example:

https://api.placements.io/v1/groups/1001?from_package_id=101

We provide an advanced feature to mimic one of our powerful UI capabilities: adding a package as a group into a campaign. To achieve this, you may add a query parameter from_package_id=YOUR_PACKAGE_ID when creating or updating a group resource.

When this parameter is detected, after creating or updating the group with normal attributes, we will auto-create lines inside this group based on the specified package configuration. If the package has budget allocation enabled, then each line will have a booked value and units according to the allocation. Otherwise, the lines will only contain cost but no units.

If you want to add multiple packages into a campaign, just execute the above operation multiple times.

Line Items

Example line item (abbreviated for clarity):

{
  "data": {
    "id": "106",
    "type": "line-items",
    "links": {
      "self": "https://api.placements.io/v1/line_items/106"
    },
    "attributes": {
      "name": "Line item 1",
      ...
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://api.placements.io/v1/line_items/106/relationships/campaign",
          "related": "https://api.placements.io/v1/line_items/106/campaign"
        },
        "data": {
          "type": "campaigns",
          "id": "41"
        }
      }
    }
  }
}

// With delivery-stats
{
  "data": {
    "id": "106",
    ...
    "attributes": {
      "delivery-stats": {
        "first-party": {
          "clicks": 724,
          "impressions": 94162670,
          "viewable-impressions": 81683683
        },
        "third-party": {
          "advertiser": "ACME Industries",
          "server": "ImpSlinger",
          "clicks": 956,
          "impressions": 95318149,
          "viewable-impressions": 79151545
        }
      },
      ...
    },
    "relationships": {
      ...
    }
  }
}

Base: https://api.placements.io/v1/line_items

Data "type" is "line-items", identified by "id".

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"line item 1"	required
description	String	""
ad-server	String (Enum)	"app_nexus", "dfp", or "offline"	required
ad-server-id	String	""
ad-server-network-code	String	"88650439"	Required if the targeted ad-server has multiple networks
approval-status	String (Enum)	"draft", "pending_review", "approved", or "rejected"	read-only
revision-status	String (Enum)	null, "draft", "pending_review", or "rejected"	read-only
delivery-status	String	"DELIVERING"	read-only
start-date	DateTime	"2018-08-23T00:00:00.000Z"	required
end-date	DateTime	"2018-08-24T00:00:00.000Z"	required
time-zone	String	"Pacific Time (US & Canada)"
currency-code	String	"USD"	required
cost-basis	String (Enum)	"CPA", "CPC", "CPD", "CPE", "CPM", "CPU", "CPVM" or "FIXED"	required
cost-of-goods-sold	Array (Cost Of Goods Sold)	(see Cost Of Goods Sold)	read-only
cost-per-unit	Number	0.02	required
contracted-units	Number	100
copied-from-id	Number	1	read-only
units	Number	100
priority	Number	14
item-type	String	"STANDARD"	required
goal	Number	70
environment-type	String (Enum)	"BROWSER", "NATIVE", or "VIDEO_PLAYER"
video-max-duration	Number	10
roadblocking-type	String (Enum)	"ALL_ROADBLOCK", "CREATIVE_SET", "AS_MANY_AS_POSSIBLE", "EXACT", "NONE", "NORMAL", "ONE_OR_MORE", "ONLY_ONE" or "PARTIAL"	AKA GAM Display Creatives
companion-delivery-option	String (Enum)	"OPTIONAL", "AT_LEAST_ONE", "ALL"	GAM Display Companions
external-id	String	""
total-booked	Number	20
billing-source	String (Enum)	"contracted", "first_party_actuals", or "third_party_actuals"
billing-schedule	String (Enum)	"prepaid", "straightline"
billing-cap	String (Enum)	"no_cap", "cap_contracted" or "cap_per_billing_cycle"
ad-locations	Array (String)	["preroll", "midroll", "postroll"]	consist of String (Enum)
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
delivery-stats	Object	(see example)	(see below)
line-item-number	Number	42	read-only
profit-margin	Number	70	read-only
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
uid	String	"e0864c2afd9ce9"
creative-sizes	Array(Creative Sizes)	(see Creative Sizes section)
frequency-caps	Object (Frequency Caps)	(see Frequency Caps section)
geo-targeting	Object (Geo Targeting)	(see Geo Targeting section)
inventory-targeting	Object (Inventory Targeting)	(see Inventory Targeting section)
content-targeting	Object (Content Targeting)	(see Content Targeting section)
device-category-targeting	Object (Device Category Targeting)	(see Device Category Targeting section)
day-part-targeting	Object (Day Part Targeting)	(see Day Part Targeting section)
segment-targeting	Object (Segment Targeting)	(see Segment Targeting section)
custom-targeting	Object (Custom Targeting)	(see Custom Targeting section)
split-targeting	Object (Split Targeting)	(see Split Targeting section)
wda-budget	Number	50.0	read-only
ad-slot-position-targeting	Object (Ad Slot Position Targeting)	(see Ad Slot Position Targeting section)
player-targeting	Object (Player Targeting)	(see Player Targeting section)
min_minutes_per_imp	Integer	AKA Xandr Recency Caps: The minimum number of minutes between impressions per person. This field may not be set to 0. See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#frequency
roadblocking_slot_type	String	The Xandr roadblock slot-type ie. "INTRO_BUMPER", "OUTRO_BUMPER", "AD_POD_FIRST", "AD_POD_LAST". Also see https://learn.microsoft.com/en-us/xandr/digital-platform-api/line-item-service#roadblock
deal-name	String	"My example deal name"	read-only via public api; applicable to Xandr NGDLI/PGDLI use-case.
deal-id	Integer	123	Optional, applicable to Xandr NGDLI/PGDLI use-case.
deal-buyer-id	Integer	123	Optional, applicable to Xandr NGDLI/PGDLI use-case.
enable-pacing	Boolean	true	Xandr specific.
lifetime-budget	Number	1337.00
lifetime-budget-impressions	Integer	1234
lifetime-pacing	Boolean	true	Xandr specific.
lifetime-pacing-percentage	Number	100	Xandr specific; when omitted will default to the network's default pacing percent setting.
budget-set-per-flight	Boolean	false	Xandr specific.
daily-budget	Number	42.35
daily-budget-impressions	Integer	1234
is-active	Boolean	true

delivery-stats is read-only and by default not included in the response (null value). Add query parameter stats=true to include it. For example: 'https://api.placements.io/v1/line_items/1001?stats=true

Relationships

Name	Type	Notes
campaign	Campaign	required on create, read-only on update
group	Group	optional
product	Product	read-only on update
package	Package	read-only

To create a line item from a Product, you can pass in "relationships": { "product": { "data": { "type": "products", "id": "xxx" } } } along with specific line item attributes. The newly created line item will get attribute values from the product first, then apply overwrites from the passed-in line item attributes.

Additional Filters

Filter	Description	Param Example
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
archived	by archived	`filter[archived]=false`
approval-status	by approval status	`filter[approval-status]=approved`
delivery-status	by ad server delivering status	`filter[delivery-status]=DELIVERING`
started-before	start-date earlier than a given timestamp	`filter[started-before]=2019-01-20`
started-after	start-date later than a given timestamp	`filter[started-after]=2019-01-20`
ended-before	end-date earlier than a given timestamp	`filter[ended-before]=2019-01-20`
ended-after	end-date later than a given timestamp	`filter[ended-after]=2019-01-20`
ad-server-id	by ad server id	`filter[ad-server-id]=20227938`
campaign	by the id of the parent campaign	`filter[campaign]=101`
group	by the id of the parent group	`filter[group]=42`
external-id	by external id	`filter[external-id]=101`

Line Item Creative Associations (BETA)

Example Line Item Creative Association (abbreviated for clarity):

{
  "data": {
    "id": "10",
    "type": "line-item-creative-associations",
    "attributes": {
      "last-modified": "2024-05-09T01:41:10.756Z",
      "status": "ACTIVE",
      "creative-ad-server-id": "998855"
    },
    "relationships": {
      "line-item": {
        "data": {
          "type": "line-items",
          "id": "1180"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/line_item_creative_associations

Data "type" is "line-item-creative-associations", identified by "id".

Attributes

Name	Type	Sample Value
status	String	"ACTIVE" or "INACTIVE"
creative-ad-server-id	String
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Relationships

Name	Type	Notes
line-item	Line Item	required

Opportunities

Example opportunity (abbreviated for clarity):

{
  "data": {
    "id": "52",
    "type": "opportunities",
    "links": {
      "self": "https://api.placements.io/v1/opportunities/52"
    },
    "attributes": {
      "name": "Amazon Fresh Campaign - Fall 2015",
      ...
      "trafficker-info": {
        "email": "[email protected]"
      },
      "sales-planner-info": {
        "email": "[email protected]"
      },
      "primary-salesperson-info": {
        "email": "[email protected]",
        "split-percent": 80
      },
      "secondary-salespeople-info": [
        {
          "email": "[email protected]",
          "split-percent": 20
        }
      ],
      "ad-server-info": [
        {
          "ad-server": "dfp",
          "ad-server-id": 20227938,
          "ad-server-network-code": "88650439"
        }
      ],
      ...
    },
    "relationships": {
      "advertiser": {
        "links": {
          "self": "https://api.placements.io/v1/opportunities/52/relationships/advertiser",
          "related": "https://api.placements.io/v1/opportunities/52/advertiser"
        },
        "data": {
          "type": "accounts",
          "id": "3549"
        }
      },
      ...
    }
  }
}

Base: https://api.placements.io/v1/opportunities

Data "type" is "opportunities", identified by "id".

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"opportunity 1"	required
description	String	""
stage-name	String	"Closed Won"	required
close-date	Date	"2018-08-07"	required
proposal-due-date	Date	"2018-08-09"
start-date	DateTime	"2021-03-22T00:00:00.000Z"
end-date	DateTime	"2021-03-22T23:59:59.000Z"
probability	Number	5
requirements	String	""
time-zone	String	"Pacific Time (US & Canada)"
currency-code	String	"USD"	required
budget	Number	100.00
is-programmatic	Boolean	false
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
trafficker-info	Object	(see example)
sales-planner-info	Object	(see example)
primary-salesperson-info	Object	(see example)
secondary-salespeople-info	Array(Object)	(see example)
ad-server-info	Array(Object)	(see example)	read-only
opportunity-order-number	Number	42	read-only
salesforce-id	String	"0064P00000v3PpcQAE"
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
uid	String	"e0864c2afd9ce9"

Relationships

Name	Type	Notes
advertiser	Account	required
agency	Account
partner	Account
bill-to-account	Account
owner	User
rate-card	Rate Card
opportunity-line-items	Array(Opportunity Line Item)

Additional Filters

Filter	Description	Param Example
archived	by archived	`filter[archived]=false`
opportunity-order-number	by opportunity order number	`filter[opportunity-order-number]=101`
salesforce-id	by salesforce id	`filter[salesforce-id]=ABCD`

Opportunity Line Items

Example opportunity line item (abbreviated for clarity):

{
  "data": {
    "id": "67",
    "type": "opportunity-line-items",
    "links": {
      "self": "https://api.placements.io/v1/opportunity_line_items/67"
    },
    "attributes": {
      "name": "Opportunity Line item 1",
      ...
    },
    "relationships": {
      "opportunity": {
        "links": {
          "self": "https://api.placements.io/v1/opportunity_line_items/67/relationships/opportunity",
          "related": "https://api.placements.io/v1/opportunity_line_items/67/opportunity"
        },
        "data": {
          "type": "opportunities",
          "id": "11"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/opportunity_line_items

Data "type" is "opportunity-line-items", identified by "id".

Attributes

Name	Type	Sample Value	Notes
archived	Boolean	false
name	String	"line item 1"	required
description	String	""
ad-server	String (Enum)	"app_nexus", "dfp", or "offline"	required
ad-server-network-code	Number	88650439
start-date	DateTime	"2018-08-23T00:00:00.000Z"	required
end-date	DateTime	"2018-08-24T00:00:00.000Z"	required
time-zone	String	"Pacific Time (US & Canada)"
currency-code	String	"USD"	required
cost-basis	String (Enum)	"CPA", "CPC", "CPD", "CPE", "CPM", "CPU", "CPVM" or "FIXED"	required
cost-per-unit	Number	0.02
units	Number	100
item-type	String	"STANDARD"	required
goal	Number	70
environment-type	String (Enum)	"BROWSER", "NATIVE", or "VIDEO_PLAYER"
video-max-duration	Number	10
roadblocking-type	String (Enum)	"ALL_ROADBLOCK", "CREATIVE_SET", "AS_MANY_AS_POSSIBLE", "EXACT", "NONE", "NORMAL", "ONE_OR_MORE", "ONLY_ONE" or "PARTIAL"	AKA GAM Display Creatives
companion-delivery-option	String (Enum)	"OPTIONAL", "AT_LEAST_ONE", "ALL"	GAM Display Companions
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
uid	String	"e0864c2afd9ce9"
frequency-caps	Object (Frequency Caps)	(see Frequency Caps section)
geo-targeting	Object (Geo Targeting)	(see Geo Targeting section)
inventory-targeting	Object (Inventory Targeting)	(see Inventory Targeting section)
content-targeting	Object (Content Targeting)	(see Content Targeting section)
device-category-targeting	Object (Device Category Targeting)	(see Device Category Targeting section)
day-part-targeting	Object (Day Part Targeting)	(see Day Part Targeting section)
segment-targeting	Object (Segment Targeting)	(see Segment Targeting section)
custom-targeting	Object (Custom Targeting)	(see Custom Targeting section)
secondary-ad-server-data	Array (Secondary Ad Server Data)	(see Secondary Ad Server Data section)

Relationships

Name	Type	Notes
opportunity	Opportunity	required

Additional Filters

Filter	Description	Param Example
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
archived	by archived	`filter[archived]=false`
started-before	start-date earlier than a given timestamp	`filter[started-before]=2019-01-20`
started-after	start-date later than a given timestamp	`filter[started-after]=2019-01-20`
ended-before	end-date earlier than a given timestamp	`filter[ended-before]=2019-01-20`
ended-after	end-date later than a given timestamp	`filter[ended-after]=2019-01-20`
opportunity	by the id of the parent opportunity	`filter[opportunity]=101`

Packages

Example package (abbreviated for clarity):

{
  "data": {
    "id": "2",
    "type": "packages",
    "links": {
      "self": "https://api.placements.io/v1/packages/2"
    },
    "attributes": {
      "name": "test package",
      "currency-code": "USD",
      "active": true,
      "archived": false,
      "price": 0,
      "pricing-mode": "PRICING_MODE_PERCENTAGE_BASED",
      "lock-percent-allocation": true,
      "pricing-floor": null,
      "pricing-ceiling": null,
      "billable": true,
      "billing-source": "first_party_actuals",
      "billing-schedule": "straightline",
      "billing-cap": "no_cap",
      "pricing-budget-type": "PRICING_BUDGET_TYPE_IMPRESSIONS",
      "pricing-units": 1234567,
      "cost-per-unit": 0,
      "cost-basis": "CPM",
      "units": null
    }
  }
}

Base: https://api.placements.io/v1/packages

Data "type" is "packages", identified by "id".

Attributes

Name	Type	Sample Value	Notes
active	Boolean	true
archived	Boolean	false
name	String	"line item 1"	required
description	String	""
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
currency-code	String	"USD"	required
price	Number	0	Typically translates to the Group "Budget" via product-wizard when we're talking about revenue-based pricing.
pricing-mode	String (Enum)	"PRICING_MODE_DISABLED", or "PRICING_MODE_PERCENTAGE_BASED"	PRICING_MODE_DISABLED (package-allocations disabled, default value), or PRICING_MODE_PERCENTAGE_BASED (AKA package-allocations enabled)
lock-percent-allocation	Boolean	false
pricing-floor	Number
pricing-ceiling	Number
billable	Boolean	false
billing-source	String (Enum)	"contracted", "first_party_actuals", or "third_party_actuals"	when left as blank, the resulting Group will default to the Campaign value at product-wizard submit-time
billing-schedule	String (Enum)	"prepaid", "straightline"	when left as blank, the resulting Group will default to the Campaign value at product-wizard submit-time
billing-cap	String (Enum)	"no_cap", "cap_contracted" or "cap_per_billing_cycle"	when left as blank, the resulting Group will default to the Campaign value at product-wizard submit-time
pricing-budget-type	String (Enum)	"PRICING_BUDGET_TYPE_REVENUE", or "PRICING_BUDGET_TYPE_IMPRESSIONS"	Defaults to "Pricing_BUDGET_TYPE_REVENUE". To represent a budget-type of "None", just keep it as revenue (default pricing-budget-type) with a price of zero.
pricing-units	Number	1234567	Applies when "PRICING_BUDGET_TYPE_IMPRESSIONS", overriding where units would of been referenced.
cost-per-unit	Number	3.21	Conditionally required (ie. billable, contracted, with revenue based pricing)
cost-basis	String (Enum)	"CPM", "CPC", "CPD", or "FIXED"	Required where billable. Typically you'll want to constrain the child products to abide by the parent package's cost-basis as declared here.
units	Number	123	Conditionally required (ie. billable, contracted, with pricing-disabled)

Relationships

Name	Type	Notes
owner	User
products	Array(Product)

Additional Filters

Filter	Description	Param Example
active	by active	`filter[active]=true`
archived	by archived	`filter[archived]=false`

Products

Example product (abbreviated for clarity):

{
  "data": {
    "id": "2",
    "type": "products",
    "links": {
      "self": "https://api.placements.io/v1/products/2"
    },
    "attributes": {
      "name": "test product",
      ...
    }
  }
}

Base: https://api.placements.io/v1/products

Data "type" is "products", identified by "id".

Attributes

Name	Type	Sample Value	Notes
active	Boolean	true	Deprecated - use 'status' instead
status	String (Enum)	"active", "inactive", "inprogress"	New added
archived	Boolean	false
name	String	"line item 1"	required
description	String	""
ad-server	String (Enum)	"app_nexus", "dfp", or "offline"	required
ad-server-network-code	Number	88650439
currency-code	String	"USD"	required
cost-basis	String (Enum)	"CPA", "CPC", "CPD", "CPE", "CPM", "CPU", "CPVM" or "FIXED"	required
cost-of-goods-sold	Array (Cost Of Goods Sold)	(see Cost Of Goods Sold)	read-only
cost-per-unit	Number	0.02
priority	Number	14
item-type	String	"STANDARD"	required
goal	Number	70
environment-type	String (Enum)	"BROWSER", "NATIVE", or "VIDEO_PLAYER"
video-max-duration	Number	10
roadblocking-type	String (Enum)	"ALL_ROADBLOCK", "CREATIVE_SET", "AS_MANY_AS_POSSIBLE", "EXACT", "NONE", "NORMAL", "ONE_OR_MORE", "ONLY_ONE" or "PARTIAL"	Display Creatives
companion-delivery-option	String (Enum)	"OPTIONAL", "AT_LEAST_ONE", "ALL"	GAM Display Companions
default-content-targeting-id	String	"2bb0a402-55ec-4eed-9121-80588f32406d"
custom-fields	Key value pairs	(see Custom Fields (Attributes) section)
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
creative-sizes	Array(Creative Sizes)	(see Creative Sizes section)
frequency-caps	Object (Frequency Caps)	(see Frequency Caps section)
geo-targeting	Object (Geo Targeting)	(see Geo Targeting section)
inventory-targeting	Object (Inventory Targeting)	(see Inventory Targeting section)
content-targeting	Object (Content Targeting)	(see Content Targeting section)
device-category-targeting	Object (Device Category Targeting)	(see Device Category Targeting section)
day-part-targeting	Object (Day Part Targeting)	(see Day Part Targeting section)
segment-targeting	Object (Segment Targeting)	(see Segment Targeting section)
custom-targeting	Object (Custom Targeting)	(see Custom Targeting section)
sales-limit	Number	21	sales-limit and sales-limit-interval should always be set together. To disable sales limits on the product, set sales-limit-interval as blank value.
sales-limit-interval	String (Enum)	"DAY", "MON_WEEK", "MONTH", "QUARTER" or "YEAR"	sales-limit and sales-limit-interval should always be set together. To disable sales limits on the product, set sales-limit-interval as blank value.
commissions-enabled	Boolean	false	AKA Sales Commissions (On/Off)
categories	String
wda-budget	Number	50.0	read-only
ad-slot-position-targeting	Object (Ad Slot Position Targeting)	(see Ad Slot Position Targeting section)
player-targeting	Object (Player Targeting)	(see Player Targeting section)
min_minutes_per_imp	Integer	AKA Xandr Recency Caps: The minimum number of minutes between impressions per person. This field may not be set to 0. See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#frequency
roadblocking_slot_type	String	The Xandr roadblock slot-type ie. "INTRO_BUMPER", "OUTRO_BUMPER", "AD_POD_FIRST", "AD_POD_LAST". Also see https://learn.microsoft.com/en-us/xandr/digital-platform-api/line-item-service#roadblock

Relationships

Name	Type	Notes
owner	User

Additional Filters

Filter	Description	Param Example
ad-server	by ad server	`filter[ad-server]=offline`
ad-server-network-code	by ad server network code	`filter[ad-server-network-code]=321`
active	by active	`filter[active]=true`
archived	by archived	`filter[archived]=false`

Product Rates

Example product rate (abbreviated for clarity):

{
  "data": {
    "id": "2",
    "type": "product-rates",
    "links": {
      "self": "https://api.placements.io/v1/product_rates/2"
    },
    "attributes": {
      "cost-per-unit": "1.00",
      ...
    },
    "relationships": {
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "rate-card": {
        "data": {
          "type": "rate-cards",
          "id": "1"
        }
      }
    }
  }
}

Base: https://api.placements.io/v1/product_rates

Data "type" is "product-rates", identified by "id".

Attributes

Name	Type	Sample Value	Notes
cost-per-unit	Number	0.02
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Relationships

Name	Type	Notes
rate-card	Rate Card	Required
product	Product	Required

Rate Cards

Example rate card (abbreviated for clarity):

{
  "data": {
    "id": "1",
    "type": "rate-cards",
    "links": {
      "self": "https://api.placements.io/v1/rate_cards/1"
    },
    "attributes": {
      "last-modified": "2020-01-08T22:41:04.403Z",
      "active": true,
      "name": "Minnesota bees - b960",
      "description": "Cumque esse sed aut id.",
      "global-discount-percent": 22.02,
      "global-discount-apply-to-targeting": true
    },
    "relationships": {
      "product-rates": {
        ...
      }
    }
  }
}

Base: https://api.placements.io/v1/rate_cards

Data "type" is "rate-cards", identified by "id".

Attributes

Name	Type	Sample Value
active	Boolean	true
name	String	"rate card 1"
description	String	"something"
global-discount-percent	Number	5
global-discount-apply-to-targeting	Boolean	true
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Relationships

Name	Type	Notes
product-rates	Array(Product Rate)

Reports (BETA)

To run a report, first POST create with its definition:

{
  "data": {
    "type": "reports",
    "attributes": {
      "definition": {
        "start-date": "2020-08-10",
        "end-date": "2020-08-20",
        "columns": ["first_party_impressions"]
      }
    }
  }
}

Then when you query, you can get its status. As an example (abbreviated for clarity):

{
  "data": {
    "id": "4",
    "type": "reports",
    "attributes": {
      "last-modified": "2020-09-18T21:48:00.760Z",
      "definition": {
        ...
      },
      "status": "completed",
      "error-message": null,
      "download-url": "https://..."
    }
  }
}

Base: https://api.placements.io/v1/reports

Data "type" is "reports", identified by "id".

A report allows you to query daily delivery data on the line item level. To run a report, follow the steps below:

"Create" a report by POST request, using your desired definition.
the response you get back contains the report id.
poll the report by "Get" request with the report id, until its status is "completed".
now you can get the report csv with its "download-url". Note: the url is valid for 10 minutes, after that you have to "Get" again for a new download url.

Attributes

Name	Type	Sample Value	Notes
definition	Object	(see Report Definition section)	required
status	String (enum)	"pending", "in_progress", "completed", "failed"	read-only
error-message	String	"something"	read-only
download-url	String	"https://..."	read-only
last-modified	DateTime	"2018-08-22T22:54:09.023Z"

Users

Example user (abbreviated for clarity):

{
  "data": {
    "id": "2",
    "type": "users",
    "links": {
      "self": "https://api.placements.io/v1/users/2"
    },
    "attributes": {
      "active": true,
      ...
    }
  }
}

Base: https://api.placements.io/v1/users

Data "type" is "users", identified by "id".

Attributes

Name	Type	Sample Value	Notes
active	Boolean	true
city	String	""
country	String	""
currency-code	String	"USD"
department	String	""
email	String	""	required
fax	String	""
first-name	String	""
last-name	String	""
mobile	String	""
phone	String	""
state	String	""
street	String	""
time-zone	String	"Pacific Time (US & Canada)"
title	String	""
zip	String	""
last-modified	DateTime	"2018-08-22T22:54:09.023Z"
uid	String	"e0864c2afd9ce9"

Additional Filters

Filter	Description	Param Example
email	by email	`filter[email][email protected]`

Custom Fields (Attributes)

Assuming that for a resource, four custom fields are setup: "cf1" of type "Text", "cf2" of type "Number", "cf3" of type "Dropdown", and "cf4" of type "Multi-Select". Below is an example of "custom-fields" value:

"custom-fields": {
   "cf1": "abcd",
   "cf2": "100",
   "cf3": "value",
   "cf4": ["value1", "value2"]
}

For some resources, org admin can setup custom fields to hold arbitrary attributes. A custom field can be of type "Text", "Number", "Dropdown", "Multi-Select" (with a pre-defined list of valid values). Please contact your org admin on how to set it up.

For example, to preserve existing custom field values:

https://api.placements.io/v1/campaigns/1001?skip_missing_custom_fields=true

Note that when updating, all custom fields' values will be overwritten by default. If you want to retain any existing custom field values, please include them in the update payload. Alternatively, you can add a query parameter skip_missing_custom_fields=true to preserve those custom fields values you omitted in the payload.

For example, to use an alternative format (custom field id as key):

https://api.placements.io/v1/campaigns/1001?custom_fields_use_id=true

"custom-fields": {
   "2": "abcd",
   "5": "100",
   "6": "value",
   "90": ["value1", "value2"]
}

By default, the keys of the custom-fields value structure will be the name of the custom fields. But you can add a query parameter custom_fields_use_id=true to switch to an alternative format that uses the id of the custom fields.

Creative Sizes

Example creative sizes:

"creative-sizes": [
  {
    "name": "622x690"
  },
  {
    "name": "1300x900v",
    "companions": [
      {
        "name": "100x200v"
      }
    ]
  }
]

Name	Type	Sample Value	Notes
name	String	"100x200"	required
companions	Array(Creative Sizes)

Frequency Caps

Frequency Caps Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "freewheel", "madhive", "octillion"	required
data	format dependent	(see Frequency Caps Formats section)	required

Frequency Caps Formats

app_nexus

Example app_nexus formatted frequency caps:

{
  "frequency-caps": {
    "format": "app_nexus",
    "data": {
      "max-hour-imps": 5,
      "max-day-imps": 7
    }
  }
}

Attributes

Name	Type	Notes
max-session-imps	Integer	[0, 255]
max-page-imps	Integer
max-hour-imps	Integer	[0, 255]
max-day-imps	Integer	[0, 255]
max-week-imps	Integer	[0, 255]
max-month-imps	Integer	[0, 255]
max-lifetime-imps	Integer	[0, 255]

dfp

Example dfp formatted frequency caps:

{
  "frequency-caps": {
    "format": "dfp",
    "data": [
      {
        "max-impressions": 5,
        "num-time-units": 1,
        "time-unit": "HOUR"
      },
      {
        "max-impressions": 7,
        "num-time-units": 1,
        "time-unit": "DAY"
      }
    ]
  }
}

Attributes

Name	Type	Notes
max-impressions	Integer	required
num-time-units	Integer	required
time-unit	String (Enum)	required (see Time Unit)

Time Unit

Allowed values for time-unit:

MINUTE
HOUR
DAY
WEEK
MONTH
LIFETIME
POD
STREAM

freewheel

Example freewheel formatted frequency caps:

{
  "frequency-caps": {
    "format": "freewheel",
    "data": [
      {
        "type": "IMPRESSION",
        "period": 720,
        "value": 10
      },
      {
        "type": "IMPRESSION",
        "period": "CAMPAIGN",
        "value": 1
      }
    ]
  }
}

Attributes

Name	Type	Notes
type	String (Enum)	must equal "IMPRESSION"
period	String (Enum) or Integer	required, one of "TEN_MIN", "HOUR", "DAY", "WEEK", "30DAYS", "STREAM", "ASSET", "SITE_SECTION", "CAMPAIGN". Integer unit is minutes
value	Integer	required

madhive

Example madhive formatted frequency caps:

{
  "frequency-caps": {
    "format": "madhive",
    "data": {
      "freq-cap-month": 4,
      "freq-cap-week": 3,
      "freq-cap-day": 2,
    }
  }
}

Attributes

Name	Type	Notes
freq-cap-month	Integer	# of ads per month
freq-cap-week	Integer	# of ads per week
freq-cap-day	Integer	# of ads per day

octillion

Example octillion formatted frequency caps:

{
"frequency-caps": {
    "format": "octillion",
    "data": [
        {
            "impressions": 1,
            "freq-value": 1,
            "freq-type": "DAY"
        },
        {
            "impressions": 5,
            "freq-value": 5,
            "freq-type": "MINUTE"
        }
    ]
 }
}

Attributes

Name	Type	Notes
impressions	Integer
freq-value	Integer
freq-type	String (Enum)	'MINUTE', 'HOUR', 'DAY', 'WEEK'

Cost Of Goods Sold

Example cost of goods sold:

{
  "cost-of-goods-sold": [
    {
      "name": "PIO COGS",
      "type": "percent",
      "tiered": "UNIT_BASE_MODE",
      "amount": 10.0,
      "total-cogs": 100.0,
    }
  ]
}

Name	Type	Sample Value	Notes
name	String
type	String(Enum)	"percent", "cpu", "fixed"
tiered	String	"UNIT_BASED_MODE", "REVENUE_BASED_MODE"	null if not a tiered cogs
amount	Number	10.0
total-cogs	Number	100.0

Geo Targeting

Geo Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "freewheel", "megaphone", "madhive", "octillion"	required
data	format dependant	(see Geo Targeting Formats)	required

Geo Targeting Formats

app_nexus

Example app_nexus formatted geo targeting:

{
  "geo-targeting": {
    "format": "app_nexus",
    "data": {
      "city-action": "include",
      "city-targets": [{ "id": 200942 }],
      "dma-action": "exclude",
      "dma-targets": [{ "dma": 612 }],
      "region-action": "include",
      "region-targets": [{ "id": 3950 }],
      "country-action": "exclude",
      "country-targets": [{ "id": 233 }],
      "postal-code-action": "include",
      "postal-code-targets": [{ "id": "135" }]
    }
  }
}

Attributes

Name	Type	Notes
city-action	String (Enum)	"include" or "exclude", defaults to "exclude"
city-targets	Array (Object)	each object contains single key of "id" with city id
dma-action	String (Enum)	"include" or "exclude", defaults to "exclude"
dma-targets	Array (Object)	each object contains single key of "dma" with dma id
region-action	String (Enum)	"include" or "exclude", defaults to "exclude"
region-targets	Array (Object)	each object contains single key of "id" with region id
country-action	String (Enum)	"include" or "exclude", defaults to "exclude"
country-targets	Array (Object)	each object contains single key of "id" with country id
postal-code-action	String (Enum)	"include"
postal-code-targets	Array (Object)	each object contains single key of "id" with postal code id

dfp

Example dfp formatted geo targeting:

{
  "geo-targeting": {
    "format": "dfp",
    "data": {
      "targeted-locations": [
        {
          "id": 543
        },
        {
          "id": 234564
        }
      ],
      "excluded-locations": []
    }
  }
}

Attributes

Name	Type	Notes
targeted-locations	Array (Object)	each object contains a single key of "id" with integer value
excluded-locations	Array (Object)	each object contains a single key of "id" with integer value

freewheel

Example freewheel formatted geo targeting:

{
  "geo-targeting": {
    "format": "freewheel",
    "data": {
      "include": {
        "country": [432, 654],
        "state": [123]
      },
      "exclude": {}
    }
  }
}

Attributes

Name	Type	Notes
include	Object (Locations)	See Locations
exclude	Object (Locations)	See Locations

Locations

Name	Type	Notes
country	Array (Integer)
state	Array (Integer)
dma	Array (Integer)
city	Array (Integer)
postal-code	Array (Integer)
region	Array (Integer)

madhive

Example madhive formatted geo targeting:

{
  "geo-targeting": {
    "format": "madhive",
    "data": {
      "country": "US",
      "states": ["WA", "CA"],
      "zips": null,
      "dmas": null
    }
  }
}

Attributes

Name	Type	Notes
country	String	currently US only supported
states	Array (String)	US state abbreviations
dmas	Array (Integer)	DMA region codes
zips	Array (Integer)	US zip codes

megaphone

Example megaphone formatted geo targeting:

{
  "geo-targeting": {
    "format": "megaphone",
    "data": {
      "include": ["US"],
      "exclude": ["BE", "BJ"]
    }
  }
}

Attributes

Name	Type	Notes
include	Array (String)
exclude	Array (String)

octillion

Example octillion formatted geo targeting:

{
"geo-targeting": {
  "format": "octillion",
  "data": {
      "all": {
          "country": {
              "any": [
                  {
                      "value": "CAN"
                  }
              ]
          },
          "region": {
              "any": [
                  {
                      "value": "USA/VA"
                  },
                  {
                      "value": "USA/TX"
                  }
              ]
          },
          "city": {
              "any": [
                  {
                      "value": "4099753"
                  }
              ]
          },
          "zip-code-list": {
              "any": [
                  {
                      "value": "9482"
                  }
              ]
          }
      },
      "none": {
          "city": {
              "any": [
                  {
                      "value": "4221799"
                  },
                  {
                      "value": "4942975"
                  },
                  {
                      "value": "5334320"
                  }
              ]
          },
          "custom-zip-codes": {
              "any": [
                  {
                      "value": "96201"
                  },
                  {
                      "value": "93201"
                  },
                  {
                      "value": "92019"
                  }
              ]
          }
      }
  }
}

Attributes

Name	Type	Notes
all	Object	included geos. See geos
none	Object	excluded geos. See geos

geos

Name	Type	Notes
country	{any: [{ value: string}]}
metro	{any: [{ value: string}]}
region	{any: [{ value: string}]}
city	{any: [{ value: string}]}
custom_zip_codes	{any: [{ value: string}]}
zip_code_list	{any: [{ value: string}]}

Inventory Targeting

Inventory Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "freewheel"	required
data	format dependant	(see Inventory Targeting Formats)	required

Inventory Targeting Formats

app_nexus

Example app_nexus formatted inventory targeting:

{
    "inventory-targeting": {
        "format": "app_nexus",
        "data": {
            "publisher-targets": [{
                "id": 543,
                "action": "include"
            }, {
                "id": 234,
                "action": "exclude"
            }],
            "site-targets": [],
            "placement-targets": [],
            "content-category-targets": {
                "content-categories": [{
                    "id": 321,
                    "action": "include"
                }]
            }
        }
    }
}

Attributes

Name	Type	Notes
publisher-targets	Array (Target)
site-targets	Array (Target)
placement-targets	Array (Target)
content-category-targets	Object (Content Category Targets)

Target

Name	Type	Notes
id	Integer	required
action	String (Enum)	"include" or "exclude", defaults to "exclude"

Content Category Targets

Name	Type	Notes
content-categories	Array (Target)	`action` attribute of Target must be "include"

dfp

Example dfp formatted inventory targeting:

{
    "inventory-targeting": {
        "format": "dfp",
        "data": {
            "targeted-ad-units": [{ "ad-unit-id": 543 }, { "ad-unit-id": 234 }],
            "excluded-ad-units": [],
            "targeted-placement-ids": [ 123 ]
        }
    }
}

Attributes

Name	Type	Notes
targeted-ad-units	Array (Object)	each object contains single key of "ad-unit-id" and an integer value
excluded-ad-units	Array (Object)	each object contains single key of "ad-unit-id" and an integer value
targeted-placement-ids	Array (Integer)

freewheel

Example freewheel formatted inventory targeting:

{
    "inventory-targeting": {
        "format": "freewheel",
        "data": {
            "ad-unit-package-id": [ 543 ],
            "ad-unit-node": [{ "ad-unit-id": 234 }]
        }
    }
}

Attributes

Name	Type	Notes
ad-unit-package-id	Array (Integer)
ad-unit-node	Array (Object)	each object contains single key "ad-unit-id" and an integer value

Content Targeting

Content Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "freewheel", "megaphone", "linear", "octillion"	required
data	format dependant	(see Content Targeting Formats)	required

Content Targeting Formats

dfp

Example dfp formatted content targeting:

{
    "content-targeting": {
        "format": "dfp",
        "data": {
            "targeted-content-ids": [ 543, 234 ],
            "excluded-video-content-bundle-ids": [ ]
        }
    }
}

Attributes

Name	Type	Notes
targeted-content-ids	Array (Integer)
targeted-video-content-bundle-ids	Array (Integer)
excluded-content-ids	Array (Integer)
excluded-video-content-bundle-ids	Array (Integer)

freewheel

Example freewheel formatted content targeting:

{
    "content-targeting": {
        "format": "freewheel",
        "data": {
            "include": {
                "set": [
                    {
                        "video-group": [ 876 ],
                        "relation-in-set": "OR"
                    }
                ],
                "relation-between-sets": "AND",
                "remaining-items": {}
            },
            "exclude": {
                "video": [ 234, 543 ],
                "site-group": [ ]
            }
        }
    }
}

Attributes

Name	Type	Notes
include	Object (Media or Advanced Content Targeting)
exclude	Object (Media)

Media

Name	Type	Notes
video	Array (Integer)
series	Array (Integer)
video-group	Array (Integer)
site-section	Array (Integer)
site	Array (Integer)
site-group	Array (Integer)
relation-in-set	String (Enum)	"AND" or "OR", only for Advanced Content Targeting

Advanced Content Targeting

Name	Type	Notes
set	Array (Media)	maximum length of 3 supported
relation-between-sets	String (Enum)	"AND" or "OR"
remaining-items	Object (Media)

megaphone

Example megaphone formatted content targeting:

{
    "content-targeting": {
        "format": "megaphone",
        "data": [
            {
                "type": "podcast",
                "id": "b9609254-9ef4-11ec-9895-4bfe74c42012"
            },
            {
                "type": "podcast",
                "id": "5f2cabee-10b8-11ec-b464-5f2184ca8d16"
            },
        ]
    }
}

Attributes

Name	Type	Notes
type	String (Enum)	"podcast", "episode"
id	String

octillion

Example octillion formatted content targeting:

"content-targeting": {
    "format": "octillion",
    "data": {
        "all": {
            "language": {
                "any": [
                    {
                        "value": "ab"
                    },
                    {
                        "value": "zh"
                    }
                ]
            },
            "genre": {
                "any": [
                    {
                        "value": 2
                    },
                    {
                        "value": 3
                    }
                ]
            }
        },
        "none": {
            "content-rating": {
                "any": [
                    {
                        "value": 2
                    },
                    {
                        "value": 3
                    }
                ]
            },
            "content-category": {
                "any": [
                    {
                        "value": "IAB10"
                    },
                    {
                        "value": "IAB10_1"
                    }
                ]
            },
            "genre": {
                "any": [
                    {
                        "value": 1
                    },
                    {
                        "value": 8
                    }
                ]
            }
        }
    }
}

Attributes

Name	Type	Notes
all	Object	included contents. See content
none	Object	excluded contents. See content

content

Name	Type	Notes
language	{any: [{ value: string}]}	Lauguage ID
genre	{any: [{ value: integer}]}	Genre ID
content-rating	{any: [{ value: integer}]}	Content-rating ID
content-category	{any: [{ value: string}]}	Content-catgory ID

Custom Targeting

Custom Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp"	required
data	format dependant	(see Custom Targeting Formats)	required

Custom Targeting Formats

app_nexus

Example app_nexus formatted custom targeting

{
    "custom-targeting": {
        "format": "app_nexus",
        "data": {
            "key-value-targets": {
                "kv-expression": {
                    "exp": {
                        "key": "fruit",
                        "typ": "in",
                        "vsa": ["apple", "orange"],
                        "vtp": "sta"
                    },
                    "header": {
                        "an-version": "1.0",
                        "client-version": "1.0"
                    }
                }
            }
        }
    }
}

Attributes

Name	Type	Notes
key-value-targets	Object (Key Value Targets)	required

Key Value Targets

Name	Type	Notes
kv-expression	Object (Kv Expression)	required

Kv Expression

Name	Type	Notes
exp	Object (Kv Exp)	required
header	Object (Kv Header)	required

Kv Exp

Name	Type	Notes
typ	String (Enum)	"and", "or", "not", "in", "eq", "gt", "lt", "gte", "lte" or "neq"
sbe	Object (Kv Subexpression)
key	String
vtp	String (Enum)	"num", "str", "nma" or "sta"
vnm	Number
vst	String
vna	Array (Number)
vsa	Array (String)

Kv subexpression

Name	Type	Notes
exp	Object (Kv Exp)	required

Kv Header

Name	Type	Notes
an-version	String	"1.0"
client-version	String	"1.0"

dfp

Example freewheel formatted Custom targeting:

{
    "custom-targeting": {
        "format": "dfp",
        "data": {
            "logical-operator": "OR",
            "children": [{
                "logical-operator": "AND",
                "xsi-type": "CustomCriteriaSet",
                "children": [{
                    "key-id": 555555,
                    "operator": "IS",
                    "value-ids": [111111],
                    "xsi-type": "CustomCriteria"
                }]
            }]
        }
    }
}

Attributes

Name	Type	Notes
logical-operator	String (Enum)	"OR"
children	Array (Custom Criteria Set)

Custom Criteria Set

Name	Type	Notes
logical-operator	String (Enum)	"AND"
xsi-type	String	"CustomCriteriaSet"
children	Array (Custom Criteria)

Custom Criteria

Name	Type	Notes
key-id	Integer
operator	String (Enum)	"IS" OR "IS_NOT"
value-ids	Array (Integer)
xsi-type	String	"CustomCriteria"

Device Category Targeting

Device Category Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "octillion"	required
data	format dependant	(see Device Category Targeting Formats)	required

Device Category Targeting Formats

app_nexus

example app_nexus formatted device category targeting

{
    "device-category-targeting": {
        "format": "app_nexus",
        "data": {
            "device-type-action": "include",
            "device-type-targets": [
                "phone",
                "tablet"
            ],
            "supply-type-action": "include",
            "supply-type-targets": [
                "mobile_app"
            ]
        }
    }
}

Attributes

Name	Type	Notes
device-type-action	String (Enum)	"include" or "exclude", defaults to "exclude"
device-type-targets	Array (String)	"phone", "tablet", "pc", "tv", "gameconsole", "stb", "mediaplayer"
supply-type-action	String (Enum)	"include" or "exclude", defaults to "exclude"
supply-type-targets	Array (String)	"web", "mobile_web", "mobile_app"

dfp

example dfp formatted device category targeting

{
    "device-category-targeting": {
        "format": "dfp",
        "data": {
            "targeted-device-categories": [{ "id": 543 }, { "id": 234 }],
            "excluded-device-categories": [{ "id": 789 }]
        }
    }
}

Attributes

Name	Type	Notes
targeted-device-categories	Array (Object)	each object contains single key of "id" and an integer value
excluded-device-categories	Array (Object)	each object contains single key of "id" and an integer value

madhive

example madhive formatted device category targeting

{
    "device-category-targeting": {
        "format": "madhive",
        "data": {
            "desktop": 1000,
            "tv": 4000,
            "mobile": 5000,
            "tablet": 5000
        }
    }
}

Attributes

Name	Type	Notes
desktop	Integer	allocation percentage * 100
tv	Integer	allocation percentage * 100
mobile	Integer	allocation percentage * 100
tablet	Integer	allocation percentage * 100

octillion

example octilliion formatted device category targeting

{
"device-category-targeting": {
    "format": "octillion",
    "data": {
        "all": {
            "device-type": {
                "any": [
                    {
                        "value": 4
                    },
                    {
                        "value": 5
                    }
                ]
            }
        },
        "none": {
            "device-type": {
                "any": [
                    {
                        "value": -1
                    },
                    {
                        "value": 2
                    }
                ]
            }
        }
    }
}
}

Attributes

Name	Type	Notes
all	Object	included device types. device type
none	Object	excluded device types device type

device-type

Name	Type	Notes
device-type	{any: [{ value: integer}]}	device type ID

Browser Targeting

Browser Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Browser Targeting Formats)	required

Browser Targeting Formats

app_nexus

Example app_nexus formatted browser targeting:

{
    "browser-targeting": {
        "format": "app_nexus",
        "data": {
            "browser-action": "exclude",
            "browser-targets": [
                {
                    "id": 14
                },
                {
                    "id": 20
                },
                {
                    "id": 23
                }
            ]
        }
    }
}

Attributes

Name	Type	Notes
browser-action	String (Enum)	"include" or "exclude"
browser-targets	Array (Object)	each object contains single key of "id" with browser ID

Mobile Carrier Targeting

Mobile Carrier Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Mobile Carrier Targeting Formats)	required

Mobile Carrier Targeting Formats

app_nexus

Example app_nexus formatted mobile carrier targeting:

{
    "mobile-carrier-targeting": {
        "format": "app_nexus",
        "data": {
            "carrier-action": "include",
            "carrier-targets": [
                {
                    "id": 252
                },
                {
                    "id": 649
                },
                {
                    "id": 733
                }
            ]
        }
    }
}

Attributes

Name	Type	Notes
carrier-action	String (Enum)	"include" or "exclude"
carrier-targets	Array (Object)	each object contains single key of "id" with carrier ID

Browser Language Targeting

Browser Language Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Browser Language Targeting Formats)	required

Browser Language Targeting Formats

app_nexus

Example app_nexus formatted browser language targeting:

{
    "browser-language-targeting": {
        "format": "app_nexus",
        "data": {
            "language-action": "include",
            "language-targets": [
                {
                    "id": 7
                },
                {
                    "id": 29
                },
                {
                    "id": 30
                }
            ]
        }
    },
}

Attributes

Name	Type	Notes
language-action	String (Enum)	"include" or "exclude"
language-targets	Array (Object)	each object contains single key of "id" with language ID

Mobile Device Language Targeting

Mobile Device Language Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Mobile Deviceser Language Targeting Formats)	required

Mobile Device Language Targeting Formats

app_nexus

Example app_nexus formatted mobile device language targeting:

{
    "mobile-device-targeting": {
        "format": "app_nexus",
        "data": {
            "device-model-action": "include",
            "device-model-targets": [
                {
                    "id": 106526
                },
                {
                    "id": 106968
                },
                {
                    "id": 107173
                }
            ]
        }
    },
}

Attributes

Name	Type	Notes
device-model-action	String (Enum)	"include" or "exclude"
device-model-targets	Array (Object)	each object contains single key of "id" with device model ID

Operating System Targeting

Operating System Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Operating System Targeting Formats)	required

Operating System Targeting Formats

app_nexus

Example app_nexus formatted operating system targeting:

{
    "operating-system-targeting": {
        "format": "app_nexus",
        "data": {
            "operating-system-family-action": "include",
            "operating-system-family-targets": [
                {
                    "id": 2
                },
                {
                    "id": 3
                }
            ]
        }
    },
}

Attributes

Name	Type	Notes
operating-system-family-action	String (Enum)	"include" or "exclude"
operating-system-family-targets	Array (Object)	each object contains single key of "id" with operating system family ID

Operating System Version Targeting

Operating System Version Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Operating System Version Targeting Formats)	required

Operating System Version Targeting Formats

app_nexus

Example app_nexus formatted operating system version targeting:

{
    "operating-system-version-targeting": {
        "format": "app_nexus",
        "data": {
            "use-operating-system-extended-targeting": true,
            "operating-system-extended-targets": [
                {
                    "id": 88,
                    "action": "include"
                },
                {
                    "id": 288,
                    "action": "include"
                }
            ]
        }
    },
}

Attributes

Name	Type	Notes
operating-system-extended-targets	Array (Object)	each object contains single key of "id" with operating system extended ID and action ("include" or "exclude")
use-operating-system-extended-targeting	Boolean	true, Read-only

Query String Targeting

Query String Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Query String Targeting Formats)	required

Query String Targeting Formats

app_nexus

Example app_nexus formatted query string targeting:

{
    "query-string-targeting": {
        "format": "app_nexus",
        "data": {
            "querystring-boolean-operator": "or",
            "querystring-action": "exclude",
            "querystring-targets": [
                {
                    "qsparam": "222"
                }
            ]
        }
    },
}

Attributes

Name	Type	Notes
querystring-boolean-operator	String (Enum)	"and" or "or"
querystring-action	String (Enum)	"include" or "exclude"
querystring-targets	Array (Object)	each object contains single key of "qsparam"

Tag Position Targeting

Tag Position Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Tag Position Targeting Formats)	required

Tag Position Targeting Formats

app_nexus

Example app_nexus formatted tag position targeting:

{
    "tag-position-targeting": {
        "format": "app_nexus",
        "data": {
            "position-targets": {
                "allow-unknown": true,
                "positions": [
                    {
                        "position": "above"
                    }
                ]
            }
        }
    },
}

Attributes

Name	Type	Notes
position-targets	Array (Object)	`allow-unknown`: boolean; `positions`: each object contains single key of "position" with value "above" or "below "

Day Part Targeting

Day Part Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "dfp", "freewheel", "madhive", "octillion"	required
data	format dependant	(see Day Part Targeting Formats)	required

Day Part Targeting Formats

app_nexus

Example app_nexus formatted day part targeting (12 am - 9 pm, Monday and Tuesday):

{
    "day-part-targeting": {
        "format": "app_nexus",
        "data": [
            {
                "day": "monday",
                "start-hour": 0,
                "end-hour": 20
            },
            {
                "day": "tuesday",
                "start-hour": 0,
                "end-hour": 20
            }
        ]
    }
}

Attributes

Name	Type	Notes
day	String (Enum)	"sunday", "monday", "tuesday", "wednesday", "thursday", "friday", or "saturday"
start-hour	Integer	0 - 23 inclusive
end-hour	Integer	0 - 23 inclusive

dfp

Example dfp formatted day part targeting (12 am - 9 pm, Monday and Tuesday):

{
    "day-part-targeting": {
        "format": "dfp",
        "data": {
            "day-parts": [
                {
                    "day-of-week": "MONDAY",
                    "start-time": {
                        "hour": 0,
                        "minute": "ZERO"
                    },
                    "end-time": {
                        "hour": 21,
                        "minute": "ZERO"
                    }
                },
                {
                    "day-of-week": "TUESDAY",
                    "start-time": {
                        "hour": 0,
                        "minute": "ZERO"
                    },
                    "end-time": {
                        "hour": 21,
                        "minute": "ZERO"
                    }
                }
            ],
            "time-zone": "PUBLISHER"
        }
    }
}

Attributes

Name	Type	Notes
day-parts	Array (Day Part)	See Day Part
time-zone	String (Enum)	"PUBLISHER" or "BROWSER", defaults to "PUBLISHER"

Day Part

Name	Type	Notes
day-of-week	String (Enum)	"MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", or "SUNDAY"
start-time	Object (Time of Day)	See Time of Day
end-time	Object (Time of Day)	See Time of Day

Time of Day

Name	Type	Notes
hour	Integer	0 - 24 inclusive
minute	String (Enum)	"ZERO", "FIFTEEN", "THIRTY", or "FORTY_FIVE"

freewheel

Example freewheel formatted day part targeting (12 am - 9 pm, Monday and Tuesday):

{
    "day-part-targeting": {
        "format": "freewheel",
        "data": {
            "part": [
                {
                    "start-day": "MONDAY",
                    "end-day": "MONDAY",
                    "start-day": "12 MIDNIGHT",
                    "end-day": "09:00PM"
                },
                {
                    "start-day": "TUESDAY",
                    "end-day": "TUESDAY",
                    "start-day": "12 MIDNIGHT",
                    "end-day": "09:00PM"
                }
            ],
            "time-zone": "UTC"
        }
    }
}

Attributes

Name	Type	Notes
part	Array (FW Day Part)	See FW Day Part
time-zone	String (Enum)	ignored, will default to LIC tz value instead.

FW Day Part

madhive

Example madhive formatted day part targeting (12 am - 9 pm, Monday and Tuesday):

{
    "day-part-targeting": {
        "format": "madhive",
        "data": {
          "included" : false,
          "dayparts" : [
                {
                    "day": "Monday",
                    "hours" : [0, 1, 2, 3, 4, 5, 6, 7, 8]
                },
                {
                    "day": "Tuesday",
                    "hours" : [0, 1, 2, 3, 4, 5, 6, 7, 8]
                }
            ]
          }
        }
    }
}

Attributes

Name	Type	Notes
day	String (Enum)	"Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", or "Sunday"
hours	Array (Integer)	0 - 24 inclusive

octillion

Example octillion formatted day part targeting

{
"day-part-targeting": {
    "format": "octillion",
    "data": {
        "none": {
            "user-time-of-week": {
                "any": [
                    {
                        "value": [
                            3300,
                            3359
                        ]
                    },
                    {
                        "value": [
                            10020,
                            10079
                        ]
                    },
                    {
                        "value": [
                            3420,
                            3479
                        ]
                    },
                    {
                        "value": [
                            4800,
                            4859
                        ]
                    },
                    {
                        "value": [
                            0,
                            59
                        ]
                    }
                ]
            }
        }
    }
}
}

Attributes

Name	Type	Notes
all	Object	included time slot. time slot
none	Object	excluded time slot time slot

time-slot

Name	Type	Notes
user-time-of-week	{any: [{ value: [`minute`, `minute + 59`]}]}	`minutes` is the minute from 0(12:00 AM on Sunday) to 10020(11:00 AM on Saturday)

Segment Targeting

Segment Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus", "freewheel", "madhive", "octillion"	required
data	format dependant	(see Segment Targeting Formats)	required

Segment Targeting Formats

app_nexus

Example app_nexus formatted segment targeting

{
    "segment-targeting": {
        "format": "app_nexus",
        "data": {
            "segment-boolean-operator": "or",
            "segment-group-targets": [
                {
                    "boolean-operator": "and",
                    "segments": [
                        {
                            "id": 123,
                            "action": "include"
                        },
                        {
                            "id": 456,
                            "action": "exclude"
                        }
                    ]
                },
                {
                    "boolean-operator": "and",
                    "segments": [
                        {
                            "id": 789,
                            "action": "include"
                        }
                    ]
                }
            ]
        }
    }
}

Attributes

Name	Type	Notes
segment-boolean-operator	String (Enum)	"and" or "or"
segment-group-targets	Array (Segment Group)	required

Segment Group

Name	Type	Notes
boolean-operator	String (Enum)	"and" or "or"
segments	Array (Segment)	required

Segment

Name	Type	Notes
id	Integer	required
action	String (Enum)	"include" or "exclude"
code	String
name	String

freewheel

Example freewheel formatted segment targeting:

{
    "segment-targeting": {
        "format": "freewheel",
        "data": {
            "include": {
                "set": [
                    {
                        "audience-item": [ 123, 456 ],
                        "relation-in-set": "OR"
                    }
                ],
                "relation-between-sets": "AND",
                "remaining-items": {}
            },
            "exclude": {
                "audience-item": [ 789 ]
            }
        }
    }
}

Attributes

Name	Type	Notes
include	Object (Audience Items or Advanced Audience Targeting)
exclude	Object (Audience Items

Audience Items

Name	Type	Notes
audience-item	Array (Integer)
relation-in-set	String (Enum)	"AND" or "OR", only for Advanced Audience Targeting

Advanced Audience Targeting

Name	Type	Notes
set	Array (Audience Items)	maximum length of 3 supported
relation-between-sets	String (Enum)	"AND" or "OR"
remaining-items	Object(Audience Items)

madhive

Example madhive formatted segment targeting:

{
    "segment-targeting": {
        "format": "madhive",
        "data": ["W8359GSSE5873", "TW3495239SDGDG"]
    }
}

Attributes

Name	Type	Notes
data	Array (String)	madhive segment ids

octillion

Example octillion formatted segment targeting:

"segment-targeting": {
    "format": "octillion",
    "data": {
        "all": {
            "segment": {
                "any": [
                    {
                        "value": "cadenttv-100004",
                        "value-name": "Cadent_MattressShoppers"
                    },
                    {
                        "value": "cadenttv-100013",
                        "value-name": "Cadent_Alliant_MattressBuyers"
                    },
                    {
                        "value": "cadenttv-100030",
                        "value-name": "Cadent_Speedeon_New Movers"
                    }
                ]
            }
        },
        "none": {
            "segment": {
                "any": [
                    {
                        "value": "cadenttv-100012",
                        "value-name": "Cadent_Alliant_InMarketUsedAuto"
                    },
                    {
                        "value": "cadenttv-100011",
                        "value-name": "Cadent_Alliant_InMarketAuto"
                    }
                ]
            }
        }
    }
}

Attributes

Name	Type	Notes
all	Object	included user segments user segment
none	Object	excluded user segments user segment

user-segment

Name	Type	Notes
user-segment	{any: [{ value: string, value-name: string}]}	device type ID

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Ad Slot Position Targeting Formats)	required

app_nexus

Example app_nexus formatted ad slot position targeting (First, Last):

{
    "ad-slot-position-targeting": {
        "format": "app_nexus",
        "data": {
            "ad-slot-position-action-include": true,
            "ad-slot-position-targets": [0, -1],
            "ad-slot-intro-bumper-action-include": false,
            "ad-slot-outro-bumper-action-include": false,
        }
    }
}

Example app_nexus formatted ad slot position targeting (Intro Bumper, Outro Bumper):

{
    "ad-slot-position-targeting": {
        "format": "app_nexus",
        "data": {
          "ad-slot-position-action-include": true,
          "ad-slot-position-targets": null,
          "ad-slot-intro-bumper-action-include": true,
          "ad-slot-outro-bumper-action-include": true,
        }
    }
}

Attributes

Name	Type	Notes
ad-slot-position-action-include	Boolean	Intent to target specific slots in an ad pod. Note that you can target ad slots or ad bumpers, but not both.
ad-slot-position-targets	Array (Integer)	The ad slot positions a buyer wants to serve on. -1 represents the last position, 0 represents the first.
ad-slot-intro-bumper-action-include	Boolean	Note: You can target ad slots or ad bumpers, but not both.
ad-slot-outro-bumper-action-include	Boolean	Note: You can target ad slots or ad bumpers, but not both.

Player Targeting

Player Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	format dependant	(see Player Targeting Formats)	required

Player Targeting Formats

app_nexus

Example app_nexus formatted player targeting (AKA Video targets with "Position Pre-Roll", "Position Mid-Roll", "No playback method provided", and a "Large" playback width):

{
    "ad-slot-position-targeting": {
        "format": "app_nexus",
        "data": {
            "allow-unknown-playback-method": true,
            "allow-unknown-context": false,
            "allow-unknown-player-size": false,
            "contexts": [
                {
                    "id": 1
                },
                {
                    "id": 2
                }
            ],
            "playback-methods": [

            ],
            "player-sizes": [
                {
                    "id": 3
                }
            ],
            "video-frameworks": [

            ],
            "deal-creative-duration": null
        }
    }
}

Attributes

See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#video-targets

Name	Type	Notes
allow-unknown-playback-method	Boolean	Use this field to target inventory where the playback method is unknown.
allow-unknown-context	Boolean	Use this field to target inventory where the context is unknown.
allow-unknown-player-size	Boolean	Use this field to target inventory where the player size is unknown.
contexts	Array ({ id: number })	1: position-pre-roll, 2: position-mid-roll, 3: position-post-roll, 4: outstream See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#video-frameworks
playback-methods	Array ({ id: number })	1: playback-method-auto-play-sound-on, 2: playback-method-auto-play-sound-off, 3: playback-method-click-to-play, 4: playback-method-mouse-over, 5: playback-method-auto-play-sound-unknown See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#video-frameworks
player-sizes	Array ({ id: number })	1: player-size-sm, 2: player-size-med, 3: player-size-lg See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#video-frameworks
video-frameworks	Array ({ id: number })	See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#video-frameworks
deal-creative-duration	Integer	The duration of the video creative in seconds. See https://learn.microsoft.com/en-us/xandr/digital-platform-api/profile-service#creative-duration

Split Targeting

Split Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"app_nexus"	required
data	Array (Split Object)	(see Split Targeting Formats)	required

Split Targeting Formats

app_nexus

Example app_nexus formatted split targeting:

{
  "split-targeting": {
    "format": "app_nexus",
    "data": [
      {
        "name": "Split 1",
        "bid-modifier": 3,
        "priority": 1,
        "spend-allocation": 50,
        "allocation-strategy": "unconstrained",
        "deal": {
          "field": "deal_id",
          "operator": "in",
          "value": [1616897]
        },
        "deal-list": {
          "field": "deal_list",
          "operator": "not_in",
          "value": [13193]
        }
      },
      {
        "name": "Split 2",
        "bid-modifier": 2,
        "priority": 2,
        "spend-allocation": 50,
        "allocation-strategy": "unconstrained",
        "geography": [
          {
            "field": "country",
            "operator": "not_in",
            "value": [4]
          }
        ],
        "segment-group": {
          "field": "segment_group",
          "operator": "and",
          "value": [
            [
              {
                "segment-id": 1,
                "action": "exclude"
              }
            ]
          ]
        }
      }
    ]
  }
}

Attributes of Split object

Name	Type	Notes
name	String	The split name
bid-modifier	Number	The number used to modify the bid for this split
priority	Number	The priority of this split
spend-allocation	Number	The percentage of the line item budget assigned to this split
allocation-strategy	String	"unconstrained" or "constrained"
geography	Object	(see Split Geography Formats)
deal	Object	(see Split Deal Formats)
deal-list	Object	(see Split Deal List Formats)
segment-group	Object	(see Split Segment Group Formats)
inventory-url-list	Object	(see Split Inventory URL list Formats)
key-group	Object	(see Split Key Group Formats)
video-genre	Object	(see Split Video Genre Formats)
seller-member	Object	(see Split Seller Member Formats)

Split Geography Formats

Name	Type	Notes
field	String (Enum)	"city", "country", "region", "dma", "postal-code"
operator	String (Enum)	"in", "not_in"
value	Array(Number)	The ID of geography item

Split Deal Formats

Name	Type	Notes
field	String (Enum)	"deal"
operator	String (Enum)	"in", "not_in"
value	Array(Number)	The ID of deal item

Split Deal List Formats

Name	Type	Notes
field	String (Enum)	"deal_list"
operator	String (Enum)	"in", "not_in"
value	Array(Number)	The ID of deal list item

Split Segment Group Formats

Name	Type	Notes
field	String (Enum)	"segment_group"
operator	String (Enum)	"and", "or"
value	Array(Array(Object))	{segment-id: The ID of segment item, action: "include" or "exclude"}

Split Inventory URL List Formats

Name	Type	Notes
field	String (Enum)	"inventory_url_list"
operator	String (Enum)	"and", "not_in"
value	Array(Number)	The ID of inventroy URL list item

Split Key Group Formats

Name	Type	Notes
field	String (Enum)	"key_group"
operator	String (Enum)	"and", "or"
value	Array(Object)	The Array of key group Item (see Key Group Formats)

Key Group Formats

Name	Type	Notes
key-id	Number	The ID of key
action	String (Enum)	"include", "exclude"
value-equals	Array(Number)	Array of value ID

Split Video Genre Formats

Name	Type	Notes
field	String (Enum)	"video_genre"
operator	String (Enum)	"in", "not_in"
value	Array(Number)	The ID of video genre

Split Seller Member Formats

Name	Type	Notes
field	String (Enum)	"seller_member_id"
operator	String (Enum)	"in", "not_in"
value	Array(Number)	The ID of seller member

Video Position Targeting

Video Position Targeting Attributes

Name	Type	Sample Value	Notes
format	String (Enum)	"dfp"	required
data	format dependant	see Video Position Targeting Formats	required

Video Position Targeting Formats

dfp

Example dfp formatted tag position targeting:

{
    "video-position-targeting": {
        "format": "dfp",
        "data": {
            "targeted-positions": [
                {
                    "video-position": {
                        "position-type": "PREROLL",
                        "midroll-index": 0
                    }
                },
                {
                    "video-position": {
                        "position-type": "MIDROLL",
                        "midroll-index": 2
                    },
                    "video-position-within-pod": {
                        "index": 2
                    }
                },
                {
                    "video-position": {
                        "position-type": "POSTROLL",
                        "midroll-index": 0
                    },
                    "video-position-within-pod": {
                        "index": 1
                    }
                },
                {
                    "video-position": {
                        "position-type": "POSTROLL",
                        "midroll-index": 0
                    },
                    "video-position-within-pod": {
                        "index": 100
                    }
                },
                {
                    "video-position": {
                        "position-type": "POSTROLL",
                        "midroll-index": 0
                    },
                    "video-position-within-pod": {
                        "index": 2
                    }
                }
            ]
        }
    }
}

Attributes

Name	Type	Sample Value	Notes
targeted-positions	Array (Object)	See Example	An array of objects, each representing a targeted video position.

Targeted Positions

See GAM VideoPositionTarget

Name	Type	Sample Value	Notes
video-position	Object	see Video Position	Contains the position type and midroll index.
video-position-within-pod	Object	see Video Position Within Pod	(Optional) Contains the index within the pod for the video position.

Video Position

Name	Type	Sample Value	Notes
position-type	String	"PREROLL", "MIDROLL", "POSTROLL"	The type of video position (pre-roll, mid-roll, or post-roll).
midroll-index	Integer	0-3	The index of the mid-roll to target. Only valid if the position-type is "MIDROLL".

Video Position Within Pod

Name	Type	Sample Value	Notes
index	Integer	1-100	The specific index of the pod. 1 = first, 2 = second, ..., 100 = last. Positions over 100 are not supported.

Secondary Ad Server Data

Secondary Ad Server Data Attributes

Example secondary ad server targeting for a dfp network:

{
    "ad-server" : "dfp",
    "ad-server-network-code" : "88650439",
    "geo-targeting": {
        "targeted-locations": [{
           "id": 543
          }, {
            "id": 234564
          }],
        "excluded-locations": []
    },
    "day-part-targeting" : {
        "day-parts": [
          {
            "day-of-week": "MONDAY",
            "start-time": {
              "hour": 0,
              "minute": "ZERO"
            },
            "end-time": {
              "hour": 21,
              "minute": "ZERO"
            }
          }
        ],
        "time-zone": "PUBLISHER"
    },
    "frequency-caps" : [
      {
        "max-impressions": 5,
        "num-time-units": 1,
        "time-unit": "HOUR"
      },
      {
        "max-impressions": 7,
        "num-time-units": 1,
        "time-unit": "DAY"
      }
    ]
}

Name	Type	Sample Value	Notes
ad-server	String (Enum)	"app_nexus", "dfp", "freewheel"	required
ad-server-network-code	String	"88650439"	required if multiple networks of same type
geo-targeting	ad-server dependant	(see the data attribute in Geo Targeting Formats)
day-part-targeting	ad-server dependant	(see the data attribute in Day part Targeting Formats)
frequency-caps	ad-server dependant	(see the data attribute in Frequency Caps Formats)

Report Definition

Example report definition:

{
  "definition": {
    "start-date": "2020-08-10",
    "end-date": "2020-08-20",
    "columns": [
      "ad_server",
      "ad_server_id",
      "first_party_impressions",
      "first_party_clicks",
      "first_party_ctr",
      "first_party_delivered_amount",
      "third_party_impressions",
      "third_party_clicks",
      "third_party_ctr",
      "third_party_delivered_amount",
      "reconciled_units",
      "reconciled_amount",
      "billed_units",
      "billed_amount"
    ],
    "filters": {
      "ad-server": ["dfp", "offline"],
      "advertiser-id": [42, 43],
      "agency-id": [101],
      "approval-status": ["approved"],
      "include-archived": "true"
    }
  },
}

Name	Type	Sample Value	Notes
start-date	String (Date)	"2020-08-10"	required
end-date	String (Date)	"2020-08-10"	required
columns	Array(String (Enum))	"ad_server", "ad_server_id", "first_party_impressions", "first_party_clicks", "first_party_ctr", "first_party_delivered_amount", "third_party_impressions", "third_party_clicks", "third_party_ctr", "third_party_delivered_amount", "reconciled_units", "reconciled_amount", "billed_units", "billed_amount"	required
filters	Object	see Report Filters

Report filters

Name	Type	Sample Value
ad-server	Array(String (Enum))	"dfp", "offline", "app_nexus"
advertiser-id	Array(Integer)	[42]
agency-id	Array(Integer)	[101]
approval-status	Array(String (Enum))	"draft", "pending_review", "approved", "rejected"
include-archived	Boolean	true

Rate Limiting

API requests are rate limited to 60 requests per minute, per user. After the rate limit is exceeded, clients will receive HTTP 429 response ("Too Many Requests") until the rate limit is reset.

"Create Report" requests is additionally limited to 5 requests per 10 minutes, since too many such requests can negatively impact our systems performance.

Errors

An example error response body:

{
  "errors": [
    {
      "title": "...",
      "detail": "...",
      ...
      "status": "422"
    }
  ]
}

Sometimes things do not go according to plan and we will return an error response.

In addition, we also return with regular HTTP status code. Below is a partial list:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API access token is missing or wrong.
403	Forbidden -- You don't have the permission for the operation.
404	Not Found -- The specified resource can not be found.
422	Unprocessable Entity -- The request is well-formed but semantically invalid.
429	Too Many Requests -- You're issuing too many requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later or contact support.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Support

Please contact our customer support for general questions or requesting permissions.

For detailed technical questions, suggestions, bug reports, etc. Forum might be a better channel.

Introduction

Base Endpoint

Authentication

Personal Access Token

OAuth2

Common API Actions

List

List with Pagination

List with Select Attributes (aka Sparse Fieldsets)

List with Filter Results

Get

Get with Related Resource(s)

Create

Update

Delete

Resources

Accounts

Attributes

Relationships

Additional Filters

Campaigns

Attributes

Relationships

Additional Filters

Contacts

Attributes

Relationships

Additional Filters

Creatives (BETA)

Attributes

Relationships

Additional Filters

Custom Fields

Attributes

External Users (BETA)

Attributes

Additional Filters

Groups

Attributes

Relationships

Additional Filters

Advanced

Line Items

Attributes

Relationships

Additional Filters

Line Item Creative Associations (BETA)

Attributes

Relationships

Opportunities

Attributes

Relationships

Additional Filters

Opportunity Line Items

Attributes

Relationships

Additional Filters

Packages

Attributes

Relationships

Additional Filters

Products

Attributes

Relationships

Additional Filters

Product Rates

Attributes

Relationships

Rate Cards

Attributes

Relationships

Reports (BETA)

Attributes

Users

Attributes

Additional Filters

Custom Fields (Attributes)

Creative Sizes

Frequency Caps

Frequency Caps Attributes