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.
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_URLandYOUR_AUTH_CODEwith 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_IDandYOUR_REDIRECT_URLwith 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 forcurl):
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 forcurl):
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
[,]andare URL encoded forcurl):
# 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.
Get with Related Resource(s)
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.
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.
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",
...
}
}
}
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", "PARTNER", "BRAND" 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 | "" | |
| 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) |
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 |
| 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 |
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 | |
| 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 |
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 | "" | |
| 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" | |
| uid | String | "e0864c2afd9ce9" |
Relationships
| Name | Type | Notes |
|---|---|---|
| account | Account | required |
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" |
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" | |
| 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-per-unit | Number | 0.02 | required |
| contracted-units | Number | 100 | |
| 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" | |
| 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 |
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 |
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 |
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" | |
| 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-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" | |
| 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 |
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 | Notes |
|---|---|---|---|
| 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 | "" | |
| 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 |
|---|---|---|
| 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" | 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 |
Geo Targeting
Geo Targeting Attributes
| Name | Type | Sample Value | Notes |
|---|---|---|---|
| format | String (Enum) | "app_nexus", "dfp", "freewheel", "megaphone" | 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) |
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" | 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 |
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" | 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 |
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" | 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
| Name | Type | Notes |
|---|---|---|
| start-day | String (Enum) | "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", or "SUNDAY" |
| end-day | String (Enum) | "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", or "SUNDAY"; For simplicity, keep it the same as start-day. |
| start-time | String (Enum) | "12 MIDNIGHT", "01:00AM", "02:00AM", "03:00AM", "04:00AM", "05:00AM", "06:00AM", "07:00AM", "08:00AM", "09:00AM", "10:00AM", "11:00AM", "12 NOON", "01:00PM", "02:00PM", "03:00PM", "04:00PM", "05:00PM", "06:00PM", "07:00PM", "08:00PM", "09:00PM", "10:00PM", "11:00PM", or "11:59PM" |
| end-time | String (Enum) | "12 MIDNIGHT", "01:00AM", "02:00AM", "03:00AM", "04:00AM", "05:00AM", "06:00AM", "07:00AM", "08:00AM", "09:00AM", "10:00AM", "11:00AM", "12 NOON", "01:00PM", "02:00PM", "03:00PM", "04:00PM", "05:00PM", "06:00PM", "07:00PM", "08:00PM", "09:00PM", "10:00PM", "11:00PM", or "11:59PM" |
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 |
Segment Targeting
Segment Targeting Attributes
| Name | Type | Sample Value | Notes |
|---|---|---|---|
| format | String (Enum) | "app_nexus", "freewheel" | 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 |
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 | Notes |
|---|---|---|---|
| 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.
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" |
| operator | String (Enum) | "in", "not_in" |
| value | Array(Number) | The ID of seller member |
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.