NAV
shell

Introduction

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

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_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:

After successful registration, we will give you back:

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:

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'

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

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.

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"
        }
      ],
      ...
    }
  }
}

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 ""
email String ""
salesforce-id String "00781000000DdL2588"
custom-fields Key value pairs (see Custom Fields section)
ad-server-info Array(Object) (see example) read-only
netsuite-id String ""
payment-terms String "Net 30"
last-modified DateTime "2018-08-22T22:54:09.023Z"

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
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 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"

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)

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
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 ""
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 section)
last-modified DateTime "2018-04-20T16:20:12.345Z"

Relationships

Name Type Notes
account Account required

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"
approval-status String (Enum) "draft", "pending_review", "approved", 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 section)
delivery-stats Object (see example) (see below)
line-item-number Number 42 read-only
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)

Relationships

Name Type Notes
campaign Campaign required on create, read-only on update
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

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 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
last-modified DateTime "2018-08-22T22:54:09.023Z"

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 section)
last-modified DateTime "2018-08-22T22:54:09.023Z"
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",
      ...
    }
  }
}

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 section)
last-modified DateTime "2018-08-22T22:54:09.023Z"
currency-code String "USD" required

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
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 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)

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:

  1. "Create" a report by POST request, using your desired definition.
  2. the response you get back contains the report id.
  3. poll the report by "Get" request with the report id, until its status is "completed".
  4. 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"

Custom Fields

Assuming that for a resource, two custom fields are setup: "cf1" of type "Text", and "cf2" of type "Number". Below is an example of "custom-fields" value:

"custom-fields": {
   "cf1": "abcd",
   "cf2": "100"
}

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

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:

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": 10
    }
}

Attributes

Name Type Notes
data Integer # of ads per day

Geo Targeting

Geo Targeting Attributes

Name Type Sample Value Notes
format String (Enum) "app_nexus", "dfp", "freewheel" 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-targets": [{ "id": "00135" }]
        }
    }
}

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-targets Array (Object) each object contains single key of "id" with postal code id as string

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"],
         }
    }
}

Attributes

Name Type Notes
include 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) "dfp", "freewheel" 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)

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", "sbt"
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

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.

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.