Outbrain DSP API
API Endpoint
https://oneapi.zemanta.comThis document describes the Outbrain DSP REST Campaign Management API.
The API enables Outbrain DSP clients to programmatically create and manage campaigns, ad groups and ads using RESTful objects. Custom performance reports are also available as part of the API.
In order to use Outbrain DSP REST API, please contact your sales representative.
If you want to be notified of new features and maintenance windows, please join the Outbrain DSP API Announcements Mailing List.
Try our API by using our Swagger UI to make calls and get a response. Note that this is a live production API and calls will affect your account(s)
Who should read this document?
This document is intended for programmers who are developing an integration with the Outbrain DSP system. A prerequisite for working with Outbrain DSP REST API is an understanding of HTTP and JSON.
Technical Overview ¶
Entities
The diagram and the table below describe the objects this API deals with and the relationships between them.
Entity | Description | Functionality |
---|---|---|
Account | Outbrain DSP client account | / |
Credit Item | Signed credit available for spending | Read |
Budget Item | Part of a credit assigned to a campaign as its budget | Read, Create, Update |
Campaign | A collection of Ad Groups | Read, Create, Update |
Campaign Goal | Campaign optimization goal | Read, Create, Update, Delete |
Ad Group | A collection of Ads | Read, Create, Update |
Ad | Connection between Creative and Ad Group | Read, Create, Update |
Creative | A single piece of promoted content | Read, Create, Update |
HTTP Requests
As per the REST convention, the type of action performed is determined by the HTTP method of the request.
HTTP Method | Action |
---|---|
GET | Retrieve an entity or a list of entities |
POST | Create a new entity |
PUT | Update an entity |
Requests that include a JSON formatted body must include the following header in the request:
Content-type: application/json
We recommend adding Api-Policy: strict
header to the request in order to tell the server to check
for any unknown fields inside the JSON formatted body. If any unknown fields are found, the server will
reject the request with a status code 400 (Bad Request) and list all the unknown fields in the error message.
HTTP Response Status Codes
Status Code | Meaning | Description |
---|---|---|
200 | OK | The request was successful |
201 | Created | Entity successfully created |
400 | Bad Request | Invalid or missing required parameters |
401 | Unauthorized | Authentication failed, check your access token |
403 | Forbidden | Not enough permissions for desired action |
500 | Server Error | Server error, please contact us |
JSON Payload Format
Entities are represented by JSON objects. Multiple entities are represented as a JSON array of objects.
Request
For POST
or PUT
requests, the payload is a JSON object or a JSON array of objects, as applicable to the endpoint:
{
"id": "123",
"name": "My Campaign"
}
or in the case of a list of entities:
[
{
"id": "123",
"name": "My Campaign"
},
{
"id": "124",
"name": "My Campaign 2"
}
]
Response
The server will return an entity or a list of entities in the response payload’s data
field:
{
"data": {
"id": "123",
"name": "My Campaign"
}
}
or in the case of a list of entities:
{
"data": [
{
"id": "123",
"name": "My Campaign"
},
{
"id": "124",
"name": "My Campaign 2"
}
]
}
Partial Updates
The API supports partial updates, which means that for all PUT
actions, if you’re updating a hypothetical entity
{
"name": "MyEntity",
"value": "123"
}
you can send only updated fields as the payload:
{
"value": "789"
}
which will result in the following entity:
{
"name": "MyEntity",
"value": "789"
}
Errors
In case of an error, the server will return a response with the appropriate status code and the payload describing the error:
{
"errorCode": "ValidationError",
"details": "Name is required"
}
Pagination
Outbrain DSP API paginates list views using marker offset pagination by default.
By specifying the offset
URL query parameter it is possible to use a simple limit offset pagination which might lead to slow responses with large lists.
Marker Offset Pagination
The format for marker offset pagination URL is:
/rest/v1/{resourceListPath}/{?marker,limit}
Navigation through pages is done by two URL parameters:
-
marker
: the primary key of the last element in the previous page (the first page hasmarker=0
) -
limit
: maximum number of entries to return, up to1000
, defaults to100
The response has the following content:
{
"count": 1000,
"next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?marker=200&limit=100",
"data": []
}
Limit Offset Pagination
The format for limit offset pagination URL is:
/rest/v1/{resourceListPath}/?offset{,limit}
Navigation through pages is done by two URL parameters:
-
offset
: the offset of starting element of the page in the list -
limit
: maximum number of entries to return, up to1000
, defaults to100
The response has the following content:
{
"count": 1000,
"next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=200&limit=100",
"previous": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=100&limit=100",
"data": []
}
Rate Limiting
Each Outbrain DSP user can perform a maximum of 20 requests per second to the Outbrain DSP API. In case that limit is crossed, the API will start responding with HTTP status 429 (Too Many Requests). We suggest the implementation of client side request rate limiting and graceful handling of HTTP status 429 responses.
Authentication
Outbrain DSP REST API uses two-legged OAuth2 authentication using client credentials. The client credentials are used to acquire an access token, which must then be passed to all REST API calls as the header
Authorization: Bearer <access_token>
Access tokens are valid for 10 hours, after which a new access token must be obtained using the client credentials. Please cache and reuse access tokens for the duration of their validity.
Create client credentials
To create client credentials, first make sure you are logged in to Outbrain DSP. Then go to https://dsp.outbrain.com/o/applications/ and click the New Application button. Enter a name for your application, as shown in the image, and click the “Save” button.
After you click the “Save” button, you will see the details of your newly created application credentials. The provided Client ID and Client Secret are used for API authentication.
Acquire a new authentication token ¶
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WkNTeDJXanhIeHhWNnJLWkMzaGRiNmVqTzhHTHdjZFV0bHRtcHQ5Sjp1N3BsRWQwNG1IYzExQ2NrUzlkb2poWWl3YVd6TnFlQjF3OUtnTXh3ZTVya1c2U3M3bVRSSXg2UGQ4dDdZdmRZYzdiQzEwMjVINzRzOThFMmVxaEljQmx2QmxIc2M1dkFwOVRKTVAyZTh5Nmt5SktRVVdrcFVpckZSbDNPczJmQw==
Body
grant_type=client_credentials
Headers
Content-Type: application/json
Body
{
"access_token": "UUjXNkJDyLVjDzswOjdVm0ySIBYfp7",
"token_type": "Bearer",
"expires_in": 36000,
"scope": "read write"
}
Account Management ¶
Accounts ¶
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the account’s id | N/A | read only |
agencyId | string | the agency’s id | required | read only |
name | string | the name of the account | required | optional |
archived | bool | Is the account archived? Set to true to archive an account and to false to restore it. |
optional | optional |
targeting | targeting | account targeting settings | optional | optional |
currency | Currency | the account’s currency (default is USD) | optional | N\A |
frequencyCapping | number | The maximum number of times ads from the account can be shown to a unique user in one day. | optional | optional |
defaultIconUrl | string | URL of a brand logo which will be placed in all creatives and served with ads where this is required by the publisher. Setting the brand logo for a specific creative can be done on the ad creative level. The minimum required size is 128x128 pixels and the required format is square (1:1). | required | optional |
defaultBrandName | string | Name of a brand which will be placed in all creatives and served with ads where this is required by the publisher. Setting the brand name for a specific creative can be done on the ad creative level. | required | optional |
deliveryStatus | deliveryStatus | Delivery status of the account. Set includeDeliveryStatus flag to true to get this information. |
N/A | read only |
inventoryAccessLevel | inventoryAccessLevel | Inventory access level of the account (default is EXPANDED ). |
required | required |
deals | array[deals] | Deals connected to this account. | optional | optional |
Account Targeting Settings
Targeting | Property | Property | Type | Description |
---|---|---|---|---|
publisherGroups | ||||
included | array[publisherGroupId] | included publisher group IDs | ||
excluded | array[publisherGroupId] | excluded publisher group IDs | ||
keywordLists | ||||
excluded | array[keywordTargetingListId] | excluded keyword targeting list IDs |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"slug": "outbrainrtb",
"name": "Outbrain RTB",
"auditors": [
"OUTBRAIN"
]
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
]
}
Headers
Content-Type: application/json
Body
{
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"agencyId": "1"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Account Credit ¶
After your Insertion Order for media spend has been executed Outbrain DSP’s Customer Success team will assign a credit line to your account. With credit added to your account you have the ability to create budget items and associate them with the campaigns you’re planning.
Property | Type | Description |
---|---|---|
id | string | the credit item’s id |
startDate | date | start date of the credit |
endDate | date | end date of the credit |
total | money | total credit amount |
allocated | money | amount already allocated to campaign budgets |
available | money | amount still available for allocation |
currency | Currency | the credit’s currency |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "861",
"startDate": "2016-01-01",
"endDate": "2016-11-05",
"createdOn": "2014-06-04",
"total": "1000.0000",
"allocated": "400.0000",
"available": "600.0000",
"currency": "EUR"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "861",
"startDate": "2016-01-01",
"endDate": "2016-11-05",
"createdOn": "2014-06-04",
"total": "1000.0000",
"allocated": "400.0000",
"available": "600.0000",
"currency": "EUR"
}
]
}
Pixels DEPRECATED ¶
Note: the use of img pixels has been deprecated - please use measurement services instead.
Outbrain DSP’s pixels allow you to report conversions, build audiences and get insights about how people use your website. Pixels need to be properly placed in order to measure goals effectively. We recommend placing your pixel on the confirmation page which is shown to a person after the desired action is performed.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the pixel | N/A | read only |
accountId | string | ID of the account | read only | read only |
name | string | name of the pixel | required | read only |
archived | bool | Is the pixel archived? Set to true to archive a pixel and to false to restore it. |
optional | optional |
audienceEnabled (deprecated) | bool | Is the pixel used for building custom audiences? Set to true to enable it. Can not be disabled once enabled. Only one pixel can be used for building custom audiences. |
read only | read only |
url | string | URL of the pixel | read only | read only |
notes | string | a note describing where the pixel is placed on your website and what it tracks | optional | optional |
lastTriggered | date | date of when the pixel was last triggered | read only | read only |
impressions | number | number of times the pixel was triggered yesterday | read only | read only |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"accountId": "186",
"name": "audience_pixel",
"archived": false,
"audienceEnabled": true,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
}
Headers
Content-Type: application/json
Body
{
"archived": false,
"audienceEnabled": true,
"notes": "pixel used for audience testing"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"accountId": "186",
"name": "audience_pixel",
"archived": false,
"audienceEnabled": true,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for audience testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "123",
"accountId": "186",
"name": "test_pixel",
"archived": false,
"audienceEnabled": true,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
]
}
Headers
Content-Type: application/json
Body
{
"name": "test_pixel",
"archived": false,
"audienceEnabled": true,
"notes": "pixel used for testing"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "124",
"accountId": "186",
"name": "test_pixel",
"archived": false,
"audienceEnabled": true,
"url": "https://p1.zemanta.com/p/186/124/",
"notes": "pixel used for testing",
"lastTriggered": null,
"impressions": 0
}
}
Audiences DEPRECATED ¶
Note: this way of using audiences has been deprecated - please use measurement audiences instead.
Custom audiences allow you to target your ads to a specific set of people with whom you have already established a relationship. Audiences can be defined by a combination of rules used to identify users who took specific actions on your website.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the audience | N/A | read only |
pixelId | string | ID of the pixel that is the source of this traffic | required | read only |
name | string | name of the audience | required | optional |
archived | bool | Is the audience archived? Set to true to archive an audience and to false to restore it. |
optional | optional |
ttl | number | The number of days people will remain in your audience after they’ve visited your website. People will be removed from your audience after the set time period unless they visit your website again. | required | read only |
rules | audience rule | Include traffic that meets the specified conditions. | required | read only |
createdDt | date | audience creation date | read only | read only |
Audience Rules
Choose how you want to add people to your audience. Include all of your website visitors or create rules that only add people visiting specific parts of your website. Audience can have multiple rules set. CONTAINS
and STARTS_WITH
rules can match multiple values separated by a comma. STARTS_WITH
values need to be valid URLs.
Property | Type | Description | Create | Create (VISIT ) |
Update |
---|---|---|---|---|---|
type | enum | rule type | required | required | read only |
value | string | rule value | required | N/A | read only |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "234",
"pixelId": "123",
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}
Headers
Content-Type: application/json
Body
{
"name": "new_audience",
"archived": false
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "234",
"pixelId": "123",
"name": "new_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "234",
"pixelId": "123",
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "STARTS_WITH",
"value": "http://test.com,https://urls.com"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
]
}
Headers
Content-Type: application/json
Body
{
"pixelId": 123,
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "VISIT"
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "234",
"pixelId": "123",
"name": "new_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "VISIT",
"value": ""
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}
Campaign Management ¶
Campaigns ¶
A Campaign is a collection of Ad Groups. It holds common settings for all Ad Groups and also has budgets and goals associated.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the campaign’s id | N/A | read only |
accountId | string | id of the account this campaign belongs to | required | read only |
name | string | the name of the campaign | required | optional |
type | Campaign Type | The type of the campaign (the default is NATIVE ) |
optional | read only |
iabCategory | IAB category | IAB category of the campaign | optional | optional |
language | Language | Language of the ads in the campaign | optional | read only |
archived | bool | Is the Campaign archived? Set to true to archive a Campaign and to false to restore it. |
optional | optional |
autopilot | bool | Autopilot Budget optimization. | optional | optional |
tracking | tracking | tracking settings | optional | optional |
targeting | targeting | campaign targeting settings | optional | optional |
frequencyCapping | number | The maximum number of times ads from the campaign can be shown to a unique user in one day. | optional | optional |
deliveryStatus | deliveryStatus | Delivery status of the campaign. Set includeDeliveryStatus flag to true to get this information. |
N/A | read only |
campaignManager | string | email of the user who manages this campaign | optional | optional |
deals | array[deals] | Deals connected to this campaign. | optional | optional |
Tracking Settings
Postclick tracking integration can be set up for Google Analytics and Adobe Analytics.
Please note Google Analytics 4 is replacing Google Analytics Universal on July 1, 2023. Switch your account connection to GA4 to ensure we can continue to ingest your analytics data. Learn more here. If you are using Google Analytics 360, no change is required.
Tracking | Property | Type | Description |
---|---|---|---|
ga4 | |||
enabled | boolean | Google Analytics 4 integration enabled | |
webPropertyId | integer | Google Analytics 4 Web Property ID | |
ga | |||
enabled | boolean | Google Analytics integration enabled | |
type | GA Tracking Type | Google Analytics tracking type | |
webPropertyId | string | Google Analytics Web Property ID | |
adobe | |||
enabled | boolean | Adobe Analytics integration enabled | |
trackingParameter | string | Adobe Analytics tracking parameter |
Campaign Targeting Settings
Targeting | Property | Property | Type | Description |
---|---|---|---|---|
environments (deprecated) | array[environment] | A list of default environments that will be set on newly created ad groups. | ||
os (deprecated) | array[operatingSystem] | A list of default operating systems and operating system versions that will be set on newly created ad groups. | ||
publisherGroups | ||||
included | array[publisherGroupId] | included publisher group IDs | ||
excluded | array[publisherGroupId] | excluded publisher group IDs | ||
keywordLists | ||||
excluded | array[keywordTargetingListId] | excluded keyword targeting list IDs |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Get campaign details ¶GET/rest/v1/campaigns/{campaignId}{?includeDeliveryStatus}
- campaignId
string
(required) Example: 608- includeDeliveryStatus
bool
(optional) Default: false Example: true- includeGoals
bool
(optional) Default: false Example: false- includeBudgets
bool
(optional) Default: false Example: false
Headers
Content-Type: application/json
Body
{
"data": {
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE",
"goals": [
{
"id": 1238,
"type": "TIME_ON_SITE",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"name": "My conversion goal",
"conversionDefinitionId": 123
}
}
],
"budgets": [
{
"id": 1910,
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
]
}
}
Get campaign details w/ goals and budgets ¶GET/rest/v1/campaigns/{campaignId}{?includeDeliveryStatus,includeGoals,includeBudgets}
- campaignId
string
(required) Example: 608- includeDeliveryStatus
bool
(optional) Default: false Example: true- includeGoals
bool
(optional) Default: false Example: true- includeBudgets
bool
(optional) Default: false Example: true
Headers
Content-Type: application/json
Body
{
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
]
}
List campaigns ¶GET/rest/v1/campaigns/{?includeArchived,includeGoals,includeBudgets,includeDeliveryStatus,accountId,excludeInactive}
- includeArchived
bool
(optional) Default: falseSet to true to retrieve archived campaigns.
- includeGoals
bool
(optional) Default: false Example: false- includeBudgets
bool
(optional) Default: false Example: false- includeDeliveryStatus
bool
(optional) Default: false Example: true- accountId
number
(optional) Example: 186Optional account ID.
- excludeInactive
bool
(optional) Default: false Example: trueSet to true to retrieve IDs of only active campaigns. A campaign is active if it has at least one active ad group and an available budget. An ad group is active if the status is set to enabled.
Headers
Content-Type: application/json
Body
{
"data": [
{
"data": {
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE",
"goals": [
{
"id": 1238,
"type": "TIME_ON_SITE",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"name": "My conversion goal",
"conversionDefinitionId": 123
}
}
],
"budgets": [
{
"id": 1910,
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
]
}
}
]
}
List campaigns w/ goals and budgets ¶GET/rest/v1/campaigns/{?includeArchived,includeGoals,includeBudgets,accountId,excludeInactive}
- includeArchived
bool
(optional) Default: falseSet to true to retrieve archived campaigns.
- includeGoals
bool
(optional) Default: false Example: true- includeBudgets
bool
(optional) Default: false Example: true- accountId
number
(optional) Example: 186Optional account ID.
- excludeInactive
bool
(optional) Default: false Example: trueSet to true to retrieve IDs of only active campaigns. A campaign is active if it has at least one active ad group and an available budget. An ad group is active if the status is set to enabled.
Headers
Content-Type: application/json
Body
{
"data": [
1834152,
1942877,
2488992
]
}
Get campaigns IDs ¶GET/rest/v1/campaigns/ids/{?includeArchived,accountId,excludeInactive}
- includeArchived
bool
(optional) Default: false Example: falseSet to true to include IDs of archived campaigns.
- accountId
number
(optional) Example: 186Optional account ID.
- excludeInactive
bool
(optional) Default: false Example: trueSet to true to retrieve IDs of only active campaigns. A campaign is active if it has at least one active ad group and an available budget. An ad group is active if the status is set to enabled.
Headers
Content-Type: application/json
Body
{
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"accountId": "186"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "608",
"accountId": "186",
"campaignManager": "[email protected]",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga4": {
"enabled": true,
"webPropertyId": 123456789
},
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"totalCost": "2240.56",
"impressions": 4146083,
"clicks": 14621,
"cpc": "0.130"
}
}
Get campaign performance ¶GET/rest/v1/campaigns/{campaignId}/stats/{?from,to}
This endpoint allows you to quickly view the performance of the campaign in a time span.
For more detailed reports, please use the Reporting endpoints.
- campaignId
string
(required) Example: 608- from
string
(required) Example: 2016-11-18- to
string
(required) Example: 2016-11-18
Campaign Budgets ¶
Each budget item is part of a Credit Item and allows a campaign to spend a portion of the credit.
A campaign needs at least one active budget associated with it before its Ad Groups can be started.
More info available here.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the budget’s id | N/A | read only |
creditId | string | id of the credit this budget is part of | required | read only |
amount | money | total amount allocated by the budget | required | optional |
margin | string (decimal) | margin percentage fraction (e.g. 0.1) | optional | optional |
comment | string | free-form text field | optional | optional |
startDate | date | budget start date, must be in the future | required | optional |
endDate | date | budget end date, must end before the credit ends | required | optional |
state | string | budget state, ACTIVE / PENDING / INACTIVE / DEPLETED | N/A | read only |
spend | money | the amount of the budget already spent | N/A | read only |
available | money | the amount of the budget still available | N/A | read only |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "1910",
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
]
}
Headers
Content-Type: application/json
Body
{
"creditId": "861",
"amount": "600",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1911",
"amount": "600",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "600.0000"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1910",
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
}
Headers
Content-Type: application/json
Body
{
"amount": "800"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1911",
"creditId": "861",
"amount": "800",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "800.0000"
}
}
Campaign goals ¶
Campaign goals give Outbrain DSP’s intelligent campaign automation feature Autopilot data to help optimize your campaign for optimal results.
A campaign needs at least one goal associated with it before any of its Ad Groups can be started.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the campaign goal’s id | N/A | read only |
type | enum | type of the goal | required | read only |
value | string (decimal) | value to optimize for | required | optional |
primary | boolean | Is this goal primary? There can only be one primary goal per campaign. If a primary goal already exists and you create a new primary goal, the old goal will no longer be primary. | required | optional |
conversionGoal | conversion goal | conversion goal | optional | optional |
Conversion Goals
Property | Type | Description | Create | Create pixel goal | Update |
---|---|---|---|---|---|
type | enum | conversion goal type | required | required | read only |
name | string | name of the conversion goal | required | N/A | read only |
goalId | string | goal id | N/A | N/A | read only |
conversionDefinitionId | string | conversion definition id | N/A | required | read only |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "1238",
"type": "TIME_ON_SITE",
"primary": true,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal",
"goalId": "mygoal0"
}
}
]
}
Headers
Content-Type: application/json
Body
{
"type": "CPA",
"value": "30.0",
"primary": false,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"goalId": "mygoal"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1239",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"goalId": "mygoal"
}
}
}
Headers
Content-Type: application/json
Body
{
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"conversionDefinitionId": "223"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1234",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"name": "My pixel",
"conversionDefinitionId": "223"
}
}
}
Add a campaign goal ¶POST/rest/v1/campaigns/{campaignId}/goals/
When creating a pixel goal the goalId
field should contain the ID of the pixel you want to use.
The pixel ID can be found on your Account Pixels page (https://dsp.outbrain.com/v2/pixels/account/<accountId>
) by clicking the Copy Tag button.
Inside the tag you will find a URL of form https://p1.zemanta.com/p/<accountId>/<pixelId>/
.
Use the pixelId
number when creating a new pixel (see example 2).
- campaignId
string
(required) Example: 608
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1239",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"goalId": "mygoal"
}
}
}
Headers
Content-Type: application/json
Body
{
"primary": false
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1239",
"type": "CPA",
"value": "30.0",
"primary": false,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"goalId": "mygoal"
}
}
}
Ad Group Management ¶
Ad Groups ¶
An Ad Group is a collection of Ads that has specific targeting settings.
Before any Ad Groups in the campaign can be activated, a campaign must have at least one active Budget and at least one Goal associated.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the ad group’s id | N/A | read only |
campaignId | string | id of the campaign this ad group belongs to | required | read only |
name | string | the name of the ad group | required | optional |
state | ACTIVE / INACTIVE |
Ad group state. Set to ACTIVE to activate the Ad Group and to INACTIVE to deactivate it. |
optional | optional |
archived | bool | Is the Ad Group archived? Set to true to archive an Ad Group and to false to restore it. |
optional | optional |
startDate | string | start date of the ad group | optional | optional |
endDate | string | End date of the ad group. Omit to leave it running until state is manually set to INACTIVE . |
optional | optional |
biddingType | CPC / CPM / CPA / CPA_SUPPLY |
Bidding type. Set to CPC to focus on the clicks that your ad receives, CPM to focus on impressions, CPA to focus on conversions or CPA_SUPPLY to focus on optimizing for site engagement. Please note: CPA and CPA_SUPPLY can be used only with autopilot mode enabled. |
optional | optional |
bid | money | When using CPC or CPM bidding type this field acts as bid value. When ad group bid property is updated, source bid values are calculated using the existing source bid modifiers. When CPA is selected as bidding strategy, field may be blank or populated to act as Max Average CPA limit. Cannot be used with CPA_SUPPLY bidding type. |
required (optional in autopilot mode) | required (optional in autopilot mode) |
maxBidCpc | money | Allows to set max average CPC for CPA or CPA_SUPPLY bidding type. |
optional | optional |
cpaConversionDefinitions | array[conversionDefinitionId] | Conversion definition IDs for CPA bidding type. |
optional (required for CPA bidding type) |
optional (required for CPA bidding type) |
dailyBudget | money | Daily budget for this ad group. | required | required |
targeting | targeting | targeting settings | required | required |
dayparting | dayparting | dayparting settings | optional | optional |
trackingCode | string | tracking codes appended to all ads URLs (more) | optional | optional |
autopilot | autopilot | Outbrain DSP Autopilot settings | optional | optional |
deliveryType | delivery | Delivery Type. Set to STANDARD to deliver ads throughout the day and to ACCELERATED to deliver ads as soon as possible. |
optional | optional |
frequencyCapping | number | The maximum number of times ads from the ad group can be shown to a unique user in one day. | optional | optional |
clickCappingDailyAdGroupMaxClicks | number | Limit number of clicks you want to reach daily within the ad group. Once Outbrain DSP hits the maximum number of clicks you set it will stop spending for the rest of the day. | optional | optional |
deliveryStatus | deliveryStatus | Delivery status of the ad group. Set includeDeliveryStatus flag to true to get this information. |
N/A | read only |
fpoEnabled | bool | Set to true to enable predictive clearing optimization and to false to disable it. |
optional (default: true ) |
optional |
autoAddNewSources | bool | Set to true to automatically add new media sources as soon as they become available. |
optional (default: true ) |
optional |
deals | array[deals] | Deals connected to this ad group. | optional | optional |
Ad Group Targeting Settings
Targeting | Property | Property | Type | Description |
---|---|---|---|---|
devices | array[device] | A list of device types to target. If none specified, content is served to all device types. | ||
environments | array[environment] | A list of environments to target. If none specified, content is served to all environments. | ||
os | array[operatingSystem] | A list of operating systems and their versions to target. If none specified, content is served to any operating system or version. | ||
geo | ||||
included | At least one included or excluded location must be set. | |||
countries | array[country] | countries to target | ||
regions | array[region] | regions to target | ||
dma | array[DMA] | DMA IDs to target | ||
cities | array[City] | cities to target | ||
postalCodes | array[PostalCode] | postal codes to target | ||
excluded | ||||
countries | array[country] | countries to target | ||
regions | array[region] | regions to target | ||
dma | array[DMA] | DMA IDs to target | ||
cities | array[City] | cities to target | ||
postalCodes | array[PostalCode] | postal codes to target | ||
interest (deprecated) | ||||
included | array[interestCategory] | interest categories to target | ||
excluded | array[interestCategory] | interest categories to avoid | ||
publisherGroups | ||||
included | array[publisherGroupId] | included publisher group IDs | ||
excluded | array[publisherGroupId] | excluded publisher group IDs | ||
audience | audienceTargetingExpression | audience targeting expression | ||
customAudiences | ||||
included | array[customAudienceId] | IDs of custom audiences to target | ||
excluded | array[customAudienceId] | IDs of custom audiences to avoid | ||
retargetingAdGroups | ||||
included | array[adGroupId] | IDs of ad groups to retarget | ||
excluded | array[adGroupId] | IDs of ad groups to avoid | ||
browsers | ||||
included | array[browserFamily] | A list of browsers to target. If none specified, content is served to all browsers. | ||
excluded | array[browserFamily] | A list of browsers to target. If none specified, content is served to all browsers. | ||
connectionTypes | array[connectionType] | A list of connection types to target. If none specified, content is served to all connection types. | ||
channels | array[channel] | A list of channels to target. If none specified, content is served to all available channels. | ||
contentCategories | ||||
included | array[categoryId] | IDs of IAB content categories to target | ||
excluded | array[categoryId] | IDs of IAB content categories to avoid | ||
video | video | Video-specific targeting options (video campaigns only). | ||
positions | array[adTargetPosition] | Enable specific targeted positions on the website. | ||
placementTypes | array[adTargetPlacementType] | Enable specific targeted ad placements. | ||
sizes | array[displayAdSize] | Enable specific targeted ad placement sizes. | ||
keywordLists | ||||
excluded | array[keywordTargetingListId] | excluded keyword targeting list IDs | ||
language | ||||
matchingEnabled | boolean | match the language of the ad and the content on the website |
Operating System Targeting Settings
Property | Property | Type | Description |
---|---|---|---|
name | os | Operating system. | |
version | Operating system version. If none specified all versions are targeted. | ||
min | osv | Minimum version. If none specified, any version that is lower than maximum version is targeted. | |
max | osv | Maximum version. If none specified, any version that is greater than minimum version is targeted. |
Video Targeting Settings
Property | Property | Type | Description |
---|---|---|---|
protocols | array[adTargetVideoProtocol] | Select one or more specific video protocols set by IAB. | |
apiFrameworks | array[adTargetVideoAPIFramework] | Select one or more API Frameworks for the structure or format of the video ad. | |
skippability | videoSkippability | Require or block the video skippability option. | |
delays | array[adTargetVideoDelay] | Select specific viewability option on instream: pre-roll, mid-roll and/or post-roll. |
Dayparting
Dayparting structure is defined as a dictionary of days which point to a list of hours that are enabled in that day, eg. “monday” -> [0, 1, 2, 5]. This means that on monday bidding is enabled from 00:00 to 02:59 and from 5:00 to 5:59. The other value is “timezone” that defines in which timezone the hours are evaluated, eg. “timezone” -> “America/New_York”. This value must be formatted according to the tz database (see https://en.wikipedia.org/wiki/Tz_database). If timezone isn’t specified then user’s timezone is used to resolve the hours.
Property | Type | Description |
---|---|---|
sunday | array[integer] | active hours |
monday | array[integer] | active hours |
tuesday | array[integer] | active hours |
wednesday | array[integer] | active hours |
thursday | array[integer] | active hours |
friday | array[integer] | active hours |
saturday | array[integer] | active hours |
timezone | TZ timezone | Timezone in which the hours are evaluated. If not specified, the timezone of the user being shown the ad is used. |
Audience Targeting
An Audience Targeting expression is an object containing a single property. The name of the property represents the operator, while its value is an array representing the subexpression(s). A subexpression can be either a nested Audience Targeting expression or a Category object.
Valid operators are AND
, OR
and NOT
. NOT
has to have exactly one nested subexpression in the child array.
Example Audience Targeting expression:
{
"AND": [
{
"OR": [
{
"category": "ob-eyeota:839868"
},
{
"category": "ob-eyeota:763921"
}
]
},
{
"NOT": [
{
"category": "ob-eyeota:839918"
}
]
}
]
}
Audience Targeting Category
Audience targeting subexpressions can either be a nested audience targeting expressions or a leaf category node.
Property | Type | Description |
---|---|---|
category | string | Composed of two parts - the data provider and category id separated by : . (E.g. ob-eyeota:671901 , ob-eyeota:93179 , ob-nielsen:192356 ) |
Currently the supported providers are obi
,obd
,ob-sentiments
,ob-eyeota
and ob-nielsen
. See DMP Categories API for a list of all available categories. The categoryId
field is the internal Zementa’s representation and needs to be used in the targeting expressions.
Outbrain DSP Autopilot Settings
Get more information about Outbrain DSP Autopilot in our knowledge base.
Property | Type | Description |
---|---|---|
state | autopilot state | autopilot state |
Browser Targeting Settings
Property | Type | Description |
---|---|---|
family | browser | Browser family |
Channel Targeting Settings
Campaign Type | Required channel | Optional channel |
---|---|---|
NATIVE |
NATIVE |
DISPLAY (native-to-display), VIDEO (native-to-video) |
DISPLAY |
DISPLAY |
N/A |
VIDEO |
VIDEO |
N/A |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"biddingType": "CPM",
"bid": "0.25",
"dailyBudget": "100.00",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"environments": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6",
"max": "ANDROID_7"
}
}
],
"geo": {
"included": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
},
"excluded": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
}
},
"interest": {
"included": [
"WOMEN",
"FASHION"
],
"excluded": [
"POLITICS"
]
},
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
},
"audience": {
"AND": [
{
"category": "ob-eyeota:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
},
"browsers": {
"included": [
{
"family": "CHROME"
}
],
"excluded": []
},
"connectionTypes": [
"WIFI",
"CELLULAR"
]
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"biddingType": "CPM",
"bid": "0.25",
"dailyBudget": "100.00",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"environments": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6",
"max": "ANDROID_7"
}
}
],
"geo": {
"included": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
},
"excluded": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
}
},
"interest": {
"included": [
"WOMEN",
"FASHION"
],
"excluded": [
"POLITICS"
]
},
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
},
"audience": {
"AND": [
{
"category": "ob-eyeota:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
},
"browsers": {
"included": [
{
"family": "CHROME"
}
],
"excluded": []
},
"connectionTypes": [
"WIFI",
"CELLULAR"
]
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"biddingType": "CPM",
"bid": "0.25",
"dailyBudget": "100.00",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"environments": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6",
"max": "ANDROID_7"
}
}
],
"geo": {
"included": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
},
"excluded": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
}
},
"interest": {
"included": [
"WOMEN",
"FASHION"
],
"excluded": [
"POLITICS"
]
},
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
},
"audience": {
"AND": [
{
"category": "ob-eyeota:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
},
"browsers": {
"included": [
{
"family": "CHROME"
}
],
"excluded": []
},
"connectionTypes": [
"WIFI",
"CELLULAR"
]
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"biddingType": "CPM",
"bid": "0.25",
"dailyBudget": "100.00",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"environments": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6",
"max": "ANDROID_7"
}
}
],
"geo": {
"included": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
},
"excluded": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
}
},
"interest": {
"included": [
"WOMEN",
"FASHION"
],
"excluded": [
"POLITICS"
]
},
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
},
"audience": {
"AND": [
{
"category": "ob-eyeota:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
},
"browsers": {
"included": [
{
"family": "CHROME"
}
],
"excluded": []
},
"connectionTypes": [
"WIFI",
"CELLULAR"
]
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10,
"deliveryStatus": "ACTIVE"
}
]
}
List ad groups ¶GET/rest/v1/adgroups/{?campaignId,accountId,includeArchived,includeDeliveryStatus,onlyRecentlyAffected}
- accountId
number
(optional) Example: 186Optional account ID.
- campaignId
number
(optional) Example: 608Optional campaign ID.
- includeArchived
bool
(optional) Default: falseSet to true to retrieve archived ad groups.
- includeDeliveryStatus
bool
(optional) Default: false Example: true- onlyRecentlyAffected
bool
(optional) Default: false Example: trueSet to true to only retrieve ad groups which were changed or had changes on related objects in the last 60 minutes.
Headers
Content-Type: application/json
Body
{
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"biddingType": "CPM",
"bid": "0.25",
"dailyBudget": "100.00",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"environments": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6",
"max": "ANDROID_7"
}
}
],
"geo": {
"included": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
},
"excluded": {
"countries": [
"CA"
],
"regions": [
"US-NY"
],
"dma": [
"693"
],
"cities": [
"123456"
],
"postalCodes": [
"US:10001"
]
}
},
"interest": {
"included": [
"WOMEN",
"FASHION"
],
"excluded": [
"POLITICS"
]
},
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
},
"audience": {
"AND": [
{
"category": "ob-eyeota:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
},
"browsers": {
"included": [
{
"family": "CHROME"
}
],
"excluded": []
},
"connectionTypes": [
"WIFI",
"CELLULAR"
]
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
Headers
Content-Type: application/json
Body
<a name="ad-group-sources"></a>
Ad Group Sources ¶
Each Ad Group has specific configurable settings for each media source. You can control whether the ad group is promoted on a given source, the CPC you are willing to pay on that source and the daily budget you wish to spend on that source.
Property | Type | Description |
---|---|---|
source | string | source identifier |
state | ACTIVE /INACTIVE |
is ad group being promoted on the given source |
Headers
Content-Type: application/json
Body
{
"data": [
{
"source": "yahoo",
"state": "ACTIVE"
},
{
"source": "gumgum",
"state": "ACTIVE"
},
{
"source": "triplelift",
"state": "ACTIVE"
}
]
}
Headers
Content-Type: application/json
Body
[
{
"source": "gumgum",
"state": "INACTIVE"
},
{
"source": "triplelift",
"state": "INACTIVE"
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"source": "yahoo",
"state": "ACTIVE"
},
{
"source": "gumgum",
"state": "INACTIVE"
},
{
"source": "triplelift",
"state": "INACTIVE"
}
]
}
Headers
Content-Type: application/json
Body
{
"source": "adiant",
"state": "ACTIVE"
}
Headers
Content-Type: application/json
Body
{
"data": {
"source": "adiant",
"state": "ACTIVE"
}
}
Connect creatives to Ad Groups ¶
After successfully created creatives via Creative Management you can start connecting them to existing Ad Groups. A creative connection to an Ad Group is called an Ad.
Headers
Content-Type: application/json
Body
[
{
"adGroupId": "2040",
"creative": {
"id": "16805"
}
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "16806",
"adGroupId": "2040",
"state": "ACTIVE",
"archived": false,
"label": "",
"creative": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage?w=300&h=250",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My updated description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
]
}
Headers
Content-Type: application/json
Body
{
"adGroupId": "2040",
"creative": {
"accountId": "186",
"type": "NATIVE",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16806",
"adGroupId": "2040",
"state": "ACTIVE",
"archived": false,
"label": "",
"creative": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage?w=300&h=250",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
}
Create an ad from a non-existing creative ¶POST/rest/v1/ads/
Note: if you want create an Ad from a non-existing Creative, you need to provide all required Creative’s fields
in the creative
part of the request payload without the id
field.
Manage ads ¶
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "16806",
"adGroupId": "2040",
"state": "ACTIVE",
"archived": false,
"label": "My label",
"creative": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My updated description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
],
"audits": [
{
"auditor": "OUTBRAIN",
"status": "APPROVED",
"errors": null
},
{
"auditor": "APPNEXUS",
"status": "APPROVED",
"errors": null
},
{
"auditor": "GOOGLEADX",
"status": "APPROVED",
"errors": null
},
{
"auditor": "TRIPLELIFT",
"status": "REJECTED",
"errors": "Headline Inaccurate Misleading"
}
],
"sources": [
{
"name": "GumGum",
"slug": "gumgum",
"auditors": [
"OUTBRAIN"
],
"blocks": [
"Blocked by third-party safeguards.",
"The brand of the creative is blocked on this Media Source."
]
}
]
}
}
]
}
List Ads connected to Ad Group ¶GET/rest/v1/ads/{?adGroupId,includeAudits,includeSources,includeArchived}
- adGroupId
number
(required) Example: 2040Ad group ID
- includeAudits
boolean
(optional) Default: false Example: trueInclude Audits
- includeSources
boolean
(optional) Default: false Example: trueInclude Sources
- includeArchived
boolean
(optional) Default: false Example: trueSet to true to retrieve archived ads.
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16805",
"adGroupId": "2040",
"state": "ACTIVE",
"archived": false,
"label": "My label",
"creative": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage?w=300&h=250",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My updated description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
],
"audits": [
{
"auditor": "OUTBRAIN",
"status": "APPROVED",
"errors": null
},
{
"auditor": "APPNEXUS",
"status": "APPROVED",
"errors": null
},
{
"auditor": "GOOGLEADX",
"status": "APPROVED",
"errors": null
},
{
"auditor": "TRIPLELIFT",
"status": "REJECTED",
"errors": "Headline Inaccurate Misleading"
}
],
"sources": [
{
"name": "GumGum",
"slug": "gumgum",
"auditors": [
"OUTBRAIN"
],
"blocks": [
"Blocked by third-party safeguards.",
"The brand of the creative is blocked on this Media Source."
]
}
]
}
}
}
Get Ad details ¶GET/rest/v1/ads/{adId}{?imageWidth,imageHeight,includeAudits,includeSources}
- adId
string
(required) Example: 16805- imageWidth
integer
(optional) Example: 300The width of the ad image.
- imageHeight
integer
(optional) Example: 250The height of the ad image.
- includeAudits
boolean
(optional) Default: false Example: trueInclude Audits
- includeSources
boolean
(optional) Default: false Example: trueInclude Sources
Headers
Content-Type: application/json
Body
{
"state": "INACTIVE",
"label": "My updated label",
"creative": {
"id": "16805",
"description": "My updated description"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16805",
"adGroupId": "2040",
"state": "INACTIVE",
"archived": false,
"label": "My updated label",
"creative": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage?w=300&h=250",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My updated description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
}
Upload Ads in batch ¶
Ads are uploaded in batches. First, you create an upload batch with the Ads you want to upload. Then, you pull the status of the batch and the validation status of the individual Ads. If any of the Ads in the batch fail the validation process, none of the Ads in the batch will be accepted into the system.
If and when all the Ads in the batch pass the validation process, they are accepted into the system.
Ad
Property | Type | Description | Create |
---|---|---|---|
id | string | The Ad’s ID. | read only |
adGroupId | string | The ID of the Ad group this Ad belongs to. | required |
state | ACTIVE /INACTIVE |
The state of the Ad. | optional (default:INACTIVE ) |
label | string | Free-form text label | optional |
archived | string | Is the Ad archived? Set to true to archive the Ad and to false to restore it. |
optional (default:false ) |
creative | creative | Creative. | required |
Upload Batch
Property | Type | Description |
---|---|---|
id | string | ID of the upload batch. |
status | ad batch status | Status of the upload batch. |
validationStatus | array[validation status] | An array of validation statuses for each Ad uploaded in this batch. The statuses are in the same order as the ads were uploaded. |
approvedAds | array[Ad] | An array that contains the uploaded Ads if/when all the ads pass the validation process. The Ads are in the same order as they were uploaded, but with added Outbrain DSP IDs. |
Headers
Content-Type: application/json
Body
[
{
"state": "ACTIVE",
"adGroupId": "2040",
"creative": {
"label": "My label",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
]
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1302",
"status": "IN_PROGRESS",
"validationStatus": [
{
"__all__": "Ad still processing."
}
],
"approvedAds": []
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1302",
"status": "DONE",
"validationStatus": [],
"approvedAds": [
{
"adGroupId": "2040",
"state": "ACTIVE",
"archived": false,
"label": "",
"creative": {
"type": "NATIVE",
"id": "16805",
"agencyId": "1",
"accountId": null,
"url": "http://testurl.com",
"title": "Test Article unicode Čžš",
"displayUrl": "example.com",
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"fallbackUrl": "",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
],
"brandName": "Example",
"description": "My updated description",
"callToAction": "Call to action",
"imageCrop": "OPTIMIZED",
"imageUrl": "https://zem.outbrainimg.com/123456789.jpg?w=200&h=300&fit=crop&crop=center",
"iconUrl": "https://zem.outbrainimg.com/234567890.jpg?w=200&h=200&fit=crop&crop=center",
"videoAssetId": null,
"imageWidth": 200,
"imageHeight": 300,
"adTagWidth": null,
"adTagHeight": null,
"adTag": ""
},
"id": "16806"
}
]
}
}
Bid Modifiers ¶
Bid modifiers enable modifying the bidding price for an ad group according to the desired parameters. The modified CPC or CPM bid value is calculated in the following way: modifiedBidValue = bidValue * modifier
. A bid request can match multiple bid modifiers with different types (for example DEVICE
, OPERATING_SYSTEM
and COUNTRY
). In that case the modified bid value is calculated by multiplying all matching bid modifier values: modifiedBidValue = bidValue * modifier1 * modifier2 * modifier3
. The allowed modifier
values are limited to the interval between 0.01
and 11.0
.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the id of bid modifier | N/A | read only |
type | string | the type of bid modifier | required | optional |
sourceSlug | string | this value is always an empty string, except for the PUBLISHER and PLACEMENT type bid modifiers where it contains the source slug of the source it targets (for a given publisher) |
optional | optional |
target | string | a string representing the target of bid modifier | required | optional |
modifier | number | a floating point factor for bidding price calculation | required | required |
Bid Modifier Types
The following bid modifier types are supported:
Type | Description | Allowed Values |
---|---|---|
AD | Modifies the bidding price for a specific ad. | the ID of the ad as a string |
PUBLISHER | Modifies the bidding price for a specific source at a specific publisher. | the domain name of the publisher |
PLACEMENT | Modifies the bidding price for a specific placement at a specific publisher and source combination. | a string of the form <publisher domain name>__<source id>__<placement id> |
SOURCE | Modifies the bidding price for a specific source. | the source slug |
DEVICE | Modifies the bidding price for a specific device type. | see Device targeting |
OPERATING_SYSTEM | Modifies the bidding price for a specific operating system. | see Operating system targeting |
ENVIRONMENT | Modifies the bidding price for a specific add environment. | see Environment targeting |
COUNTRY | Modifies the bidding price for a specific country. | see Country |
STATE | Modifies the bidding price for a specific state or region. | see State / Region |
DMA | Modifies the bidding price for a specific DMA. | see DMA |
DAY_HOUR | Modifies the bidding price for a specific day and hour combination. | see DAY HOUR |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "1234",
"type": "PUBLISHER",
"sourceSlug": "triplelift",
"target": "www.slader.com",
"modifier": 1.01
},
{
"id": "1235",
"type": "DEVICE",
"sourceSlug": "",
"target": "MOBILE",
"modifier": 0.99
},
{
"id": "1236",
"type": "AD",
"sourceSlug": "",
"target": "16805",
"modifier": 1.2
},
{
"id": "1237",
"type": "PLACEMENT",
"sourceSlug": "outbrainrtb",
"target": "www.orange.fr__85__00000000-0049-c63d-0000-000000000069",
"modifier": 1.02
}
]
}
Get bid modifiers for an ad group ¶GET/rest/v1/adgroups/{adGroupId}/bidmodifiers/{?type}
- adGroupId
string
(required) Example: 2040- type
string
(optional)- filter results by bid modifier type
Headers
Content-Type: application/json
Body
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1245",
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
}
}
Headers
Content-Type: application/json
Body
[
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
},
{
"type": "DEVICE",
"sourceSlug": "",
"target": "TABLET",
"modifier": 1.6
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
},
{
"type": "DEVICE",
"sourceSlug": "",
"target": "TABLET",
"modifier": 1.6
}
]
}
Headers
Content-Type: application/json
Body
[
{
"id": 1240
},
{
"id": 1241
}
]
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1235",
"type": "DEVICE",
"sourceSlug": "",
"target": "MOBILE",
"modifier": 0.99
}
}
Headers
Content-Type: application/json
Body
{
"modifier": 0.98
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1235",
"type": "DEVICE",
"sourceSlug": "",
"target": "MOBILE",
"modifier": 0.98
}
}
Update a bid modifier for an ad group ¶PUT/rest/v1/adgroups/{adGroupId}/bidmodifiers/{bidModifierId}
Only the modifier
value can be changed for an existing Bid Modifier. It is not allowed to change the type
, sourceSlug
and target
of an existing Bid Modifier, instead one can delete the existing Bid Modifier and create a new one with the desired values for these three attributes. However if type
, sourceSlug
and target
values did not change, they can be provided along with the modified modifier
value and will not cause a validation error.
- adGroupId
string
(required) Example: 2040- bidModifierId
string
(required) Example: 1235
Real-time Statistics ¶
The real-time statistics endpoint shows the spend and clicks on a particular adgroup for the current day. It is important to note that while the data here is updated in real-time, the data in the rest of the dashboard (including reporting) is refreshed with about 4 hours of delay.
Property | Type | Description |
---|---|---|
spend | money | the amount of the budget already spent |
clicks | number |
Headers
Content-Type: application/json
Body
{
"data": {
"spend": "1234.0000",
"clicks": 4321
}
}
Creative Management ¶
Upload Creatives in batch ¶
Creatives can be uploaded in batches. First, you create a creative batch with the Creatives you want to upload. Then, you poll the status of the batch and the validation status of the individual Creative. If any of the Creatives in the batch fail the validation process, none of the Creatives in the batch will be accepted into the system.
If and when all the Creatives in the batch pass the validation process, they are accepted into the system.
Creative
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | the creative’s id | N/A | read only |
agencyId | string | the agency id | N/A | read only |
accountId | string | the account id (set in order to use the creative on the specified account and all campaigns and ad groups) | optional | optional |
type | creative type | the creative’s type | required | optional |
url | string | landing url | required | optional |
skipUrlValidation | boolean | Set to true if you are experiencing validation issues with the landing page, but you are confident the URL is correct. Choosing this option bypasses the validation process but keep in mind that uploading an invalid URL might affect spending. |
optional | optional |
title | string | title of the Creative | required | read only |
displayUrl | string | the URL displayed with the Creative | required | optional |
brandName | string | the brand name of the Creative (required on native creatives) | optional | optional |
description | string | the description of the Creative (required on native creatives) | optional | optional |
callToAction | string | call to action, most commonly Read more (required on native creatives) |
optional | optional |
imageCrop | image crop | what strategy to use when cropping (most commonly CENTER or FACES , more info) (required on native creatives) |
optional | optional |
imageUrl | string | URL of the Creative’s image (required on native creatives, video creatives and display banner creatives) | optional | read only |
iconUrl | string | URL of a brand logo which will be served where this is required by the publisher. The minimum required size is 128x128 pixels and the required format is square (1:1). | optional | read only |
videoAssetId | string | ID of the uploaded video asset (required on video creatives) | optional | read only |
adTag | string | the HTML or JS code of the Creative (required on display ad tag creatives) | optional | optional |
adTagWidth | integer | the width of Creative’s ad tag (required on display ad tag creatives) | optional | optional |
adTagHeight | integer | the height of Creative’s ad tag (required on display ad tag creatives) | optional | optional |
trackers | array[trackers] | 3rd party image pixel or javascript trackers. Maximum of 3 trackers is allowed. | optional | optional |
tags | array[string] | the Creative’s tags | optional | optional |
audits | array[audits] | the Creative’s audits | N/A | read only |
language | Language | The language detected on the landing page of the creative. | N/A | read only |
sources | array[sources] | the Creative’s sources | N/A | read only |
Creative Batch
Property | Type | Description |
---|---|---|
id | string | id of the creative batch |
status | creative batch status | status of the batch |
validationStatus | array[validation status] | An array of validation statuses for each Creative uploaded in this batch. The statuses are in the same order as the creatives were uploaded. |
creatives | array[Creative] | An array that contains the uploaded Content Creatives if/when all the Creatives pass the validation process. The Creatives are in the same order as they were uploaded, but with added Outbrain DSP IDs. |
Trackers
Property | Type | Description | Create/Update |
---|---|---|---|
eventType | trackerEventType | Tracker event type. VIEWABILITY type is available only with IMG method | required |
method | trackerMethod | Tracker method | required |
url | string | URL of the tracker | required |
fallbackUrl | string | URL of a fallback image pixel tracker (only for JS method) | optional |
trackerOptional | bool | Allow Outbrain DSP to purchase traffic where 3rd party tracking is not supported | optional |
Audits
Property | Type | Description | Create/Update |
---|---|---|---|
auditor | auditor | Auditor | read only |
status | auditStatus | Audit status | read only |
errors | string | Rejection reasons | read only |
Sources
Property | Type | Description | Create/Update |
---|---|---|---|
name | string | Source name | read only |
slug | string | Source slug | read only |
auditors | array[auditor] | Auditors that review the source | read only |
blocks | array[string] | List of block reasons of the source | read only |
Headers
Content-Type: application/json
Body
[
{
"accountId": "186",
"type": "NATIVE",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
]
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1302",
"status": "IN_PROGRESS",
"validationStatus": [],
"creatives": []
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "1302",
"status": "DONE",
"validationStatus": [],
"creatives": [
{
"id": "16805",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
]
}
}
Manage creatives ¶
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
],
"audits": [
{
"auditor": "OUTBRAIN",
"status": "APPROVED",
"errors": null
},
{
"auditor": "APPNEXUS",
"status": "APPROVED",
"errors": null
},
{
"auditor": "GOOGLEADX",
"status": "APPROVED",
"errors": null
},
{
"auditor": "TRIPLELIFT",
"status": "REJECTED",
"errors": "Headline Inaccurate Misleading"
}
],
"sources": [
{
"name": "GumGum",
"slug": "gumgum",
"auditors": [
"OUTBRAIN"
],
"blocks": [
"Blocked by third-party safeguards.",
"The brand of the creative is blocked on this Media Source."
]
}
]
}
]
}
List creatives ¶GET/rest/v1/creatives/{?agencyId,accountId,includeAudits,includeSources}
- agencyId
number
(optional)Agency ID
- accountId
number
(optional) Example: 186Account ID
- includeAudits
boolean
(optional) Default: false Example: trueInclude Audits
- includeSources
boolean
(optional) Default: false Example: trueInclude Sources
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "2040",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage?w=300&h=250",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
],
"audits": [
{
"auditor": "OUTBRAIN",
"status": "APPROVED",
"errors": null
},
{
"auditor": "APPNEXUS",
"status": "APPROVED",
"errors": null
},
{
"auditor": "GOOGLEADX",
"status": "APPROVED",
"errors": null
},
{
"auditor": "TRIPLELIFT",
"status": "REJECTED",
"errors": "Headline Inaccurate Misleading"
}
],
"sources": [
{
"name": "GumGum",
"slug": "gumgum",
"auditors": [
"OUTBRAIN"
],
"blocks": [
"Blocked by third-party safeguards.",
"The brand of the creative is blocked on this Media Source."
]
}
]
}
}
Headers
Content-Type: application/json
Body
{
"description": "My updated description"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My updated description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
Headers
Content-Type: application/json
Body
{
"accountId": "186",
"type": "NATIVE",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "16805",
"type": "NATIVE",
"agencyId": null,
"accountId": "186",
"url": "http://example.com/myblog",
"title": "My title",
"imageUrl": "http://example.com/myimage",
"imageCrop": "FACES",
"displayUrl": "http://example.com/mycompany",
"brandName": "My Company",
"description": "My description",
"callToAction": "Read more",
"iconUrl": null,
"videoAssetId": null,
"imageWidth": null,
"imageHeight": null,
"adTagWidth": null,
"adTagHeight": null,
"adTag": null,
"tags": [],
"trackers": [
{
"eventType": "VIEWABILITY",
"method": "IMG",
"url": "https://example.com/t1",
"trackerOptional": true
},
{
"eventType": "IMPRESSION",
"method": "JS",
"url": "https://example.com/t2",
"fallbackUrl": "https://example.com/fallback",
"trackerOptional": true
}
]
}
}
Video Asset Management ¶
Upload Video Assets ¶
Video assets are uploaded separately from the creatives that will later use them. First you create a new video asset with a chosen method of upload. You can upload a video file or a VAST directly or you can provide a URL from which the VAST will be downloaded.
When uploading a video file directly, you need to upload it to the provided upload URL and then poll
for the status as the video is processed asynchronously. Should any errors occur, the upload URL can be reused.
When the status changes to READY_FOR_USE
, the id
of the video asset can be used as a videoAssetId
when creating ads for a video campaign.
When uploading a VAST, the processing will trigger only when the first ad using this
videoAssetId
is uploaded.
When uploading a VAST using VAST_URL
, the VAST will be downloaded, processed and ready for use immediately.
Video Asset
Property | Type | Description | DIRECT_UPLOAD CREATE | VAST_UPLOAD CREATE | VAST_URL CREATE |
---|---|---|---|---|---|
name | string | full name of the video file | required | N/A | N/A |
status | upload status | status of the uploaded video file | read only | read only | read only |
vastUrl | string | URL of the VAST XML | N/A | N/A | required |
upload | upload | upload settings | required | required | required |
agencyId | string | video asset scope (agency) | optional | optional | optional |
accountId | string | video asset scope (account) | optional | optional | optional |
Video upload settings
Property | Type | Description | DIRECT_UPLOAD CREATE | VAST_UPLOAD CREATE | VAST_URL CREATE |
---|---|---|---|---|---|
type | upload type | Video upload type. The required fields and steps may differ depending on the selected type. | required | required | required |
url | string | URL where the video (DIRECT_UPLOAD ) or VAST (VAST_UPLOAD ) should be uploaded. |
read only | read only | N/A |
Headers
Content-Type: application/json
Body
{
"name": "test_video.mp4",
"accountId": "186",
"upload": {
"type": "DIRECT_UPLOAD"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "DIRECT_UPLOAD",
"status": "NOT_UPLOADED",
"statusMessage": "Video is not uploaded yet",
"errorCode": null,
"errorMessage": null,
"name": "test_video.mp4",
"upload": {
"type": "DIRECT_UPLOAD",
"url": "http://upload.com"
},
"previewUrl": null,
"vastUrl": null
}
}
Headers
Content-Type: application/json
Body
{
"accountId": "186",
"upload": {
"type": "VAST_UPLOAD"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "VAST_UPLOAD",
"status": "NOT_UPLOADED",
"statusMessage": "Video is not uploaded yet",
"errorCode": null,
"errorMessage": null,
"name": "",
"upload": {
"type": "VAST_UPLOAD",
"url": "http://upload.com"
},
"previewUrl": null,
"vastUrl": null
}
}
Headers
Content-Type: application/json
Body
{
"accountId": "186",
"upload": {
"type": "VAST_URL"
},
"vastUrl": "http://upload.com/vast.xml"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "VAST_URL",
"status": "READY_FOR_USE",
"statusMessage": "Video is ready for use in creating ads",
"errorCode": null,
"errorMessage": null,
"name": "",
"previewUrl": "http://preview.com/",
"vastUrl": "http://upload.com/vast.xml"
}
}
Step 1: Create a new video asset ¶POST/rest/v1/videoassets/
When uploading a video (DIRECT_UPLOAD
) or a VAST (VAST_UPLOAD
), the response will return a URL to which the video file (see example 1) or VAST (see example 2) has to be uploaded in the next step.
When using the VAST_URL
option, the VAST will be downloaded, processed and ready for use immediately (see example 3).
Step 2: Upload the video file or VAST using the provided upload URL ¶GET/rest/v1/videoassets/{videoAssetId}
curl -X PUT -H "Content-Type: application/octet-stream" -T "test_video.mp4" "http://upload.com"
curl -X PUT -H "Content-Type: text/xml" -d @vast.xml "http://upload.com"
- videoAssetId
string
(required) Example: video_asset_id
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "DIRECT_UPLOAD",
"status": "READY_FOR_USE",
"statusMessage": "Video is ready for use in creating ads",
"errorCode": null,
"errorMessage": null,
"name": "test_video.mp4",
"previewUrl": "http://preview.com/",
"vastUrl": null
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "VAST_UPLOAD",
"status": "NOT_UPLOADED",
"statusMessage": "Video is not uploaded yet",
"errorCode": null,
"errorMessage": null,
"name": "",
"previewUrl": null,
"vastUrl": null
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "video_asset_id",
"agencyId": null,
"accountId": "186",
"type": "VAST_UPLOAD",
"status": "READY_FOR_USE",
"statusMessage": "Video is ready for use in creating ads",
"errorCode": null,
"errorMessage": null,
"name": "",
"previewUrl": "http://preview.com/",
"vastUrl": "http://upload.com/vast/1234"
}
}
Step 3: Check the video asset upload status ¶GET/rest/v1/videoassets/{videoAssetId}
When uploading a video using DIRECT_UPLOAD
, the video will be processed automatically and the above URL can be used to poll for the status of the video (see example 1).
When using the VAST_UPLOAD
option, the VAST will not be processed (see example 2) until the first ad using it is uploaded (see example 3).
- videoAssetId
string
(required) Example: video_asset_id
Measurement Management ¶
Measurement Service ¶
In order to start tracking, attributing and reporting on conversions, you need to add a Outbrain DSP Universal Pixel as the measurement service. This JavaScript pixel is also useful for building audience pools for retargeting. Outbrain DSP pixel needs to be implemented in the header of your website (each page or template). The table below lists and describes properties needed to be considered when creating a Outbrain DSP Universal Pixel.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the measurement service | N/A | read only |
name | string | Name of the measurement service | required | optional |
serviceType | measurement service type | type of the measurement service | required | read only |
archived | bool | Set to true to archive a measurement service and to false to restore it. |
optional (default: false ) |
optional |
notes | string | A note describing the measurement service | optional | optional |
agencyId | string | The agency id (set in order to use the measurement service on the specified agency and all accounts, campaigns and ad groups) | optional (default: null ) |
read only |
accountId | string | The account id (set in order to use the measurement service on the specified account and all campaigns and ad groups) | optional (default: null ) |
read only |
lastTriggered | date | The UTC timestamp of the last event | read only | read only |
recentTraffic | string | The number of events in the last 24 hours | read only | read only |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"name": "Measurement service name",
"agencyId": null,
"accountId": "186",
"serviceType": "JS_TAG",
"archived": false,
"notes": "notes describing measurement service",
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "679"
}
}
Headers
Content-Type: application/json
Body
{
"name": "Updated measurement service name"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"name": "Updated measurement service name",
"agencyId": null,
"accountId": "186",
"serviceType": "JS_TAG",
"archived": false,
"notes": "notes describing measurement service",
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "679"
}
}
Headers
Content-Type: application/json
Body
{
"name": "New measurement service",
"agencyId": null,
"accountId": "186",
"serviceType": "JS_TAG",
"notes": "notes describing measurement service"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "124",
"name": "New measurement service",
"agencyId": null,
"accountId": "186",
"serviceType": "JS_TAG",
"archived": false,
"notes": "notes describing measurement service",
"lastTriggered": null,
"recentTraffic": "0"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "124",
"name": "New measurement service",
"agencyId": null,
"accountId": "186",
"serviceType": "JS_TAG",
"archived": false,
"notes": "notes describing measurement service",
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "0"
}
]
}
List measurement services ¶GET/rest/v1/measurement/services/{?agencyId,accountId,keyword,serviceType,offset,limit}
- agencyId
number
(optional)Agency ID
- accountId
number
(optional) Example: 186Account ID
- keyword
string
(optional) Example: new- serviceType
string
(optional) Example: JS_TAG- offset
int
(optional) Default: 0 Example: 0based starting index
- limit
int
(optional) Default: 10 Example: 50Maximum number of entries to return, up to
50
Conversion definition ¶
After creating and implementing a Outbrain DSP Universal Pixel JavaScript code snippet, you need to create a conversion definition for each event that will be tracked and attributed as a conversion on your website when an online user is exposed to a Outbrain DSP ad. Define which conditions will trigger the conversion definition: “URL Rule”, “Event”, or “S2S” postback call. In the case of the “Event” condition, you need to implement an additional event snippet code on the landing web page.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the conversion definition | N/A | read only |
name | string | Name of the conversion definition | required | optional |
conversionType | conversion type | Conversion type | required | read only |
archived | bool | Set to true to archive a conversion definition and to false to restore it. |
optional (default: false ) |
optional |
notes | string | A note describing the conversion definition | optional | optional |
eventName | string | Custom event name value for triggering conversion | optional (default: PAGE_VIEW ) |
read only |
isPureS2s | boolean | Set to true if the events sent via S2S are already attributed on your or on a 3rd party side and you do not want Outbrain DSP to attribute any on its side. |
optional (default: false ) |
read only |
attributionModelType attribution model type | attribution model type | optional | read only | |
attributionModelCount attribution model count | attribution model count | optional | read only | |
clickConversionWindow | integer | The period after a click which will be used to attribute a conversion | optional | read only |
viewConversionWindow | integer | The period after an impression which will be used to attribute a conversion | optional | read only |
conversionTriggerType conversion trigger type | conversion trigger type | required | read only | |
measurementMatchingRules | measurement matching rule | Include traffic that meets the specified conditions | optional | read only |
measurementServiceId | string | ID of the measurement service | required | read only |
agencyId | string | the agency id (set in order to use the conversion definition on the specified agency and all accounts, campaigns and ad groups) | optional (default: null ) |
read only |
accountId | string | the account id (set in order to use the conversion definition on the specified account and all campaigns and ad groups) | optional (default: null ) |
read only |
lastTriggered | date | The UTC timestamp of the last event | read only | read only |
recentTraffic | string | The number of events in the last 24 hours. | read only | read only |
Measurement Matching Rules
When choosing a URL rule based conversion trigger, the Measurement Matching Rule with its properties targetType (“Page URL”), actionType (“Contains” or “Starts With”), and a custom string value to match a keyword in the landing URL needs to be defined.
Property | Type | Description | Create | Update |
---|---|---|---|---|
targetType | target type | target type | required | read only |
actionType | action type | action type | required | read only |
value | string | rule value | required | read only |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "223",
"name": "Conversion definition name",
"measurementServiceId": "123",
"accountId": "186",
"conversionType": "OTHER",
"archived": false,
"notes": "Notes describing conversion definition",
"eventName": "CUSTOM_EVENT_NAME",
"isPureS2s": "false",
"attributionModelType": "FIRST",
"attributionModelCount": "EVERY",
"clickConversionWindow": 7,
"viewConversionWindow": 1,
"conversionTriggerType": "CODE",
"measurementMatchingRules": [],
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "679"
}
}
Headers
Content-Type: application/json
Body
{
"name": "Updated conversion definition name",
"accountId": "186"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "223",
"name": "Updated conversion definition name",
"measurementServiceId": "123",
"accountId": "186",
"conversionType": "OTHER",
"archived": false,
"notes": "Notes describing conversion definition",
"eventName": "CUSTOM_EVENT_NAME",
"isPureS2s": "false",
"attributionModelType": "FIRST",
"attributionModelCount": "EVERY",
"clickConversionWindow": 7,
"viewConversionWindow": 1,
"conversionTriggerType": "CODE",
"measurementMatchingRules": [],
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "679"
}
}
Headers
Content-Type: application/json
Body
{
"name": "New conversion definition name",
"measurementServiceId": "123",
"accountId": "186",
"conversionType": "OTHER",
"archived": false,
"notes": "Notes describing conversion definition",
"eventName": "CUSTOM_EVENT_NAME",
"isPureS2s": "false",
"attributionModelType": "FIRST",
"attributionModelCount": "EVERY",
"clickConversionWindow": 7,
"viewConversionWindow": 1,
"conversionTriggerType": "CODE",
"measurementMatchingRules": []
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "224",
"name": "New conversion definition name",
"measurementServiceId": "123",
"accountId": "186",
"conversionType": "OTHER",
"archived": false,
"notes": "Notes describing conversion definition",
"eventName": "CUSTOM_EVENT_NAME",
"isPureS2s": "false",
"attributionModelType": "FIRST",
"attributionModelCount": "EVERY",
"clickConversionWindow": 7,
"viewConversionWindow": 1,
"conversionTriggerType": "CODE",
"measurementMatchingRules": [],
"lastTriggered": null,
"recentTraffic": "0"
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "224",
"name": "New conversion definition name",
"measurementServiceId": "123",
"accountId": "186",
"conversionType": "OTHER",
"archived": false,
"notes": "Notes describing conversion definition",
"eventName": "CUSTOM_EVENT_NAME",
"isPureS2s": "false",
"attributionModelType": "FIRST",
"attributionModelCount": "EVERY",
"clickConversionWindow": 7,
"viewConversionWindow": 1,
"conversionTriggerType": "CODE",
"measurementMatchingRules": [],
"lastTriggered": "2021-11-18T11:54:44.217697",
"recentTraffic": "679"
}
]
}
List conversion definitions ¶GET/rest/v1/measurement/conversiondefinitions/{?agencyId,accountId,keyword,offset,limit}
- agencyId
number
(optional)Agency ID
- accountId
number
(optional) Example: 186Account ID
- keyword
string
(optional) Example: new- offset
int
(optional) Default: 0 Example: 0based starting index
- limit
int
(optional) Default: 10 Example: 50Maximum number of entries to return, up to
50
Audiences ¶
Custom audiences allow you to target your ads to a specific set of people with whom you have already established a relationship. Audiences can be defined by a combination of rules used to identify users who took specific actions on your website.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the audience | N/A | read only |
name | string | Name of the audience | required | optional |
notes | string | Notes describing the audience | optional | optional |
eventName | string | Custom event name | optional (default: PAGE_VIEW ) |
read only |
measurementServiceId | string | ID of the measurement service | required | read only |
agencyId | string | the agency id (set in order to use the audience on the specified agency and all accounts, campaigns and ad groups) | optional (default: null ) |
read only |
accountId | string | the account id (set in order to use the audience on the specified account and all campaigns and ad groups) | optional (default: null ) |
read only |
archived | bool | Is the audience archived? Set to true to archive an audience and to false to restore it. |
optional (default: false ) |
optional |
ttl | number | The number of days people will remain in your audience after they’ve visited your website. People will be removed from your audience after the set time period unless they visit your website again. | required | read only |
rules | audience rule | Include traffic that meets the specified conditions. | required | read only |
createdDt | date | Audience creation date | read only | read only |
size | integer | Size | read only | read only |
addedYesterday | date | Added yesterday | read only | read only |
Audience Rules
Choose how you want to add people to your audience. Include all of your website visitors or create rules that only add people visiting specific parts of your website. Audience can have multiple rules set. CONTAINS
and STARTS_WITH
rules can match multiple values separated by a comma. STARTS_WITH
values need to be valid URLs.
Property | Type | Description | Create | Create (VISIT ) |
Update |
---|---|---|---|---|---|
type | enum | rule type | required | required | read only |
value | string | rule value | required | N/A | read only |
Headers
Content-Type: application/json
Body
{
"data": {
"id": "234",
"name": "new_audience",
"notes": "",
"measurementServiceId": "123",
"eventName": "",
"agencyId": null,
"accountId": "186",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "test,tags"
},
{
"type": "CONTAINS",
"value": "these,are,all"
}
],
"size": 0,
"addedYesterday": 0
}
}
Headers
Content-Type: application/json
Body
{
"name": "updated_audience"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "234",
"measurementServiceId": "123",
"agencyId": null,
"accountId": "186",
"name": "updated_audience",
"archived": false,
"eventName": "",
"notes": "",
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
]
}
}
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "234",
"measurementServiceId": "123",
"agencyId": null,
"accountId": "186",
"name": "updated_audience",
"archived": false,
"notes": "",
"ttl": 7,
"eventName": "",
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
]
}
]
}
List audiences ¶GET/rest/v1/measurement/audiences/{?agencyId,accountId,keyword,limit,offset}
- agencyId
number
(optional)Agency ID
- accountId
number
(optional) Example: 186Account ID
- keyword
string
(optional) Example: updated- offset
int
(optional) Default: 0 Example: 0based starting index
- limit
int
(optional) Default: 10 Example: 50Maximum number of entries to return, up to
50
Headers
Content-Type: application/json
Body
{
"measurementServiceId": "123",
"agencyId": null,
"accountId": "186",
"name": "new_audience",
"archived": false,
"notes": "",
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "236",
"name": "new_audience",
"notes": "",
"measurementServiceId": "123",
"eventName": "PAGE_VIEW",
"agencyId": null,
"accountId": "186",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "test,tags"
},
{
"type": "CONTAINS",
"value": "these,are,all"
}
]
}
}
Publishers Management ¶
Publisher Groups ¶
Publisher Groups are named collections of publishers that can be referenced in Ad Group’s publisherGroups
targeting section as include or exclude lists.
Publishers are represented as publisher domain (or name) and source pairs in the same manner as in publisher reports and exclude list management.
Property | Type | Description |
---|---|---|
id | string | ID of the publisher group |
name | string | name of the publisher group |
accountId | string | ID of the account this publisher group belongs to |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "111",
"accountId": "186",
"name": "Default include list"
}
]
}
Headers
Content-Type: application/json
Body
{
"name": "Secondary include list"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "153",
"accountId": "186",
"name": "Secondary include list"
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "153",
"accountId": "186",
"name": "Secondary include list"
}
}
Headers
Content-Type: application/json
Body
{
"name": "Mobile campaigns exclude list"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "153",
"accountId": "186",
"name": "Mobile campaigns exclude list"
}
}
Publisher Groups Entries ¶
Property | Type | Description | Create |
---|---|---|---|
id | string | id of the entry | N/A |
publisherGroupId | string | id of the publisher group | required |
publisher | string | publisher’s domain (or name), strict matching | required |
placement | string | The placement identifier string. If not set, it refers to all placements. | optional |
source | string | Source identifier. If not set, it refers to all sources. | optional |
includeSubdomains | boolean | if true, the publisher’s subdomains will also be included in the group | optional, defaults to true |
Headers
Content-Type: application/json
Body
{
"count": 2,
"next": "https://oneapi.zemanta.com/rest/v1/publishergroups/154/entries/?offset=2&limit=5",
"data": [
{
"id": "652",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "gumgum"
},
{
"id": "655",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "gumgum"
}
]
}
List publisher group entries ¶GET/rest/v1/publishergroups/{publisherGroupId}/entries/{?offset,limit}
- publisherGroupId
string
(required) Example: 157- offset
int
(optional) Example: 00-based starting index
- limit
int
(required) Default: 100 Example: 100Maximum number of entries to return, up to
1000
Headers
Content-Type: application/json
Body
[
{
"publisherGroupId": "157",
"publisher": "example.com",
"source": "triplelift"
},
{
"publisherGroupId": "157",
"publisher": "example.com",
"source": "yahoo"
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "650",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "triplelift"
},
{
"id": "625",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "yahoo"
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "625",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "yahoo"
}
}
Headers
Content-Type: application/json
Body
{
"publisher": "example.com",
"source": "yahoo"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "625",
"publisherGroupId": "157",
"publisher": "example.com",
"source": "yahoo"
}
}
Blacklisting ¶
This endpoint allows you to manage publisher status on different levels.
Optionally, you can assign a bid modifier to a publisher and source combination to modify the bidding price. Publisher bid modifiers are currently only supported on ADGROUP
level. In case modifier
is specified, the source
has to be specified as well or a validation error will be returned. Note: this way of setting bid modifiers on publishers has been deprecated - please use bid modifiers API instead.
Property | Type | Description | Update |
---|---|---|---|
name | string | publisher’s domain (or name), strict matching | required |
placement | string | The placement identifier string. If not set, it refers to all placements. | optional |
source | string | Source identifier. If not set, it refers to all sources. | optional |
status | publisher status | status of the publisher | required |
level | publisher level | level on which the publisher is managed | required |
Headers
Content-Type: application/json
Body
{
"data": [
{
"name": "example.com/publisher1",
"placement": "placement_1234",
"source": "gumgum",
"status": "ENABLED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher2",
"placement": null,
"source": "gumgum",
"status": "ENABLED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher3",
"placement": null,
"source": null,
"status": "BLACKLISTED",
"level": "ADGROUP"
}
]
}
Headers
Content-Type: application/json
Body
[
{
"name": "example.com/publisher1",
"source": "gumgum",
"status": "BLACKLISTED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher2",
"placement": "placement_1234",
"source": "gumgum",
"status": "BLACKLISTED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher3",
"placement": null,
"source": "gumgum",
"status": "ENABLED",
"level": "ADGROUP"
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"name": "example.com/publisher1",
"placement": null,
"source": "gumgum",
"status": "BLACKLISTED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher2",
"placement": "placement_1234",
"source": "gumgum",
"status": "BLACKLISTED",
"level": "ADGROUP"
},
{
"name": "example.com/publisher3",
"placement": null,
"source": "gumgum",
"status": "ENABLED",
"level": "ADGROUP"
}
]
}
Deals Management ¶
Deals ¶
Deals enable more customized and targeted advertising by segmenting specific supply negotiated with a publisher or a supply source. Deals in Outbrain DSP represent a unique combination of an ID and media source, and can be used as targeted inventory inclusions in account, campaign or ad group level. Deals are by default set to exclusive, meaning that we will only respond to requests on the selected media sources that have this deal. If you want all traffic to only run on this deal then you also have to pause all other media sources.
Property | Type | Description | Create | Update |
---|---|---|---|---|
id | string | ID of the deal | N/A | read only |
dealId | string | ID of the deal as defined by publisher/media source | required | optional |
agencyId | string | ID of the agency this deal belongs to | optional | optional |
accountId | string | ID of the account this deal belongs to | optional | optional |
name | string | Name of the deal | required | optional |
source | string | Media source this deal ID is connected to | required | optional |
floorPrice | decimal | Floor price as defined by publisher/media source | optional | optional |
validFromDate | date | Start date of the deal as defined by publisher/media source | optional | optional |
validToDate | date | End date of the deal as defined by publisher/media source | optional | optional |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "123",
"dealId": "123456789",
"name": "Account deal 123",
"accountId": "186",
"accountName": "My account",
"agencyId": null,
"agencyName": null,
"description": "",
"source": "gumgum",
"floorPrice": null,
"validFromDate": null,
"validToDate": null,
"createdDt": "2024-07-10T00:00:00",
"modifiedDt": "2024-07-10T00:00:00",
"createdBy": "[email protected]"
},
{
"id": "124",
"dealId": "1011121314",
"name": "Account deal 124",
"accountId": "186",
"accountName": "My account",
"agencyId": null,
"agencyName": null,
"description": "",
"source": "gumgum",
"floorPrice": null,
"validFromDate": null,
"validToDate": null,
"createdDt": "2024-07-10T00:00:00",
"modifiedDt": "2024-07-10T00:00:00",
"createdBy": "[email protected]"
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"dealId": "123456789",
"name": "Account deal 123",
"accountId": "186",
"agencyId": null,
"description": "My description",
"source": "gumgum",
"floorPrice": null,
"validFromDate": null,
"validToDate": null,
"createdDt": "2024-07-10T00:00:00",
"modifiedDt": "2024-07-10T00:00:00",
"createdBy": "[email protected]"
}
}
Headers
Content-Type: application/json
Body
{
"accountId": "186",
"description": "My updated description"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"dealId": "123456789",
"name": "Account deal 123",
"accountId": "186",
"agencyId": null,
"description": "My updated description",
"source": "gumgum",
"floorPrice": null,
"validFromDate": null,
"validToDate": null,
"createdDt": "2024-07-10T00:00:00",
"modifiedDt": "2024-07-10T00:00:00",
"createdBy": "[email protected]"
}
}
Headers
Content-Type: application/json
Body
{
"dealId": "77766X123",
"name": "Deal with ID 77766X123",
"accountId": "186",
"source": "gumgum"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "125",
"dealId": "77766X123",
"name": "Deal with ID 77766X123",
"accountId": "186",
"agencyId": null,
"description": "",
"source": "gumgum",
"floorPrice": null,
"validFromDate": null,
"validToDate": null,
"createdDt": "2024-07-10 12:00:00",
"modifiedDt": "2024-07-10 12:01:00",
"createdBy": "[email protected]"
}
}
Deal connections ¶
Deal connections are references to the entities (Agencies, Accounts, Campaigns and Ad groups) where a specific deal is used. This API supports listing and deleting deal connections. New connections can be added using the APIs of the entities, see the following:
All fields of a connection are readonly.
Property | Type | Description |
---|---|---|
id | string | ID of connection |
account | Deal entity | Account this connection connects to |
campaign | Deal entity | Campaign this connection connects to |
adgroup | Deal entity | Ad group this connection connects to |
Property | Type | Description |
---|---|---|
id | string | ID of the connected entity |
name | string | Name of the connected entity |
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "224",
"agency": {},
"account": {},
"campaign": {},
"adgroup": {
"id": "2040",
"name": "My ad group 1"
}
},
{
"id": "223",
"agency": {},
"account": {
"id": "186",
"name": "My Account 1"
},
"campaign": {},
"adgroup": {}
}
]
}
Keyword Lists ¶
Keyword Lists ¶
Keyword lists are named collections of keywords that can be referenced in an Ad Group’s Keyword targeting section as exclude lists.
Property | Type | Description |
---|---|---|
id | string | ID of the keyword list (readonly) |
name | string | Name of the keyword list |
accountId | string | ID of the account this keyword list belongs to |
accountName | string | Name of the account this keyword list belongs to (readonly) |
agencyId | string | ID of the agency this keyword list belongs to |
agencyName | string | Name of the agency this keyword list belongs to (readonly) |
size | number | Number of keywords in the list (readonly) |
modifiedDt | date | Keyword list modification date (readonly) |
createdDt | date | Keyword list creation date (readonly) |
Headers
Content-Type: application/json
Body
{
"name": "An agency-scoped keyword list",
"agencyId": "1"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "126",
"name": "An agency-scoped keyword list",
"accountId": null,
"agencyId": "1",
"agencyName": "Alfa&Omega",
"modifiedDt": "2022-03-24T09:40:29.874740",
"createdDt": "2022-03-24T09:40:22.590528"
}
}
Headers
Content-Type: application/json
Body
{
"name": "An agency-scoped keyword list",
"agencyId": "1"
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "123",
"name": "An agency-scoped keyword list",
"accountId": null,
"agencyId": "1",
"agencyName": "Alfa&Omega",
"modifiedDt": "2022-03-24T09:40:29.874740",
"createdDt": "2022-03-24T09:40:22.590528"
}
}
Keyword List Entries ¶
Each keyword list entry represents a single keyword in the list.
Property | Type | Description |
---|---|---|
id | string | ID of the keyword list entry (readonly) |
keyword | string | The keyword |
modifiedDt | date | Keyword list modification date (readonly) |
createdDt | date | Keyword list creation date (readonly) |
Headers
Content-Type: application/json
Body
[
{
"keyword": "Cat"
},
{
"keyword": "Dog"
},
{
"keyword": "Llama"
}
]
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "983421",
"keyword": "Cat",
"createdDt": "2022-03-24T09:40:22.590528"
},
{
"id": "983422",
"keyword": "Dog",
"createdDt": "2022-03-24T09:40:22.590528"
},
{
"id": "983423",
"keyword": "Llama",
"createdDt": "2022-03-24T09:40:22.590528"
}
]
}
Keyword List Connections ¶
Keyword list connections are references to the entities (Agencies, Accounts, Campaigns and Ad groups) where this keyword list is used. This API supports listing and deleting connections. New connections can be added using the APIs of the entities, see the following:
All fields of a connection are readonly. Connections are in the form of Entity-list connection
Entity-list connection
Property | Type | Description |
---|---|---|
id | string | ID of the connection |
connectionType | targetingListConnectionType | Type of the connection |
agencyId | string | ID of the agency this connection connects to |
accountId | string | ID of the account this connection connects to |
campaignId | string | ID of the campaign this connection connects to |
adGroupId | string | ID of the ad group this connection connects to |
keywordTargetingListId | string | ID of the keyword list this connection connects to |
modifiedDt | date | Connection modification date |
createdDt | date | Connection creation date |
Headers
Content-Type: application/json
Body
{
"count": 3,
"next": null,
"data": [
{
"id": "769731",
"connectionType": "exclude",
"agencyId": "1",
"accountId": "null",
"campaignId": "null",
"adGroupId": "null",
"keywordTargetingListId": "123"
},
{
"id": "769732",
"connectionType": "exclude",
"agencyId": "null",
"accountId": "186",
"campaignId": "null",
"adGroupId": "null",
"keywordTargetingListId": "123"
},
{
"id": "769733",
"connectionType": "exclude",
"agencyId": "null",
"accountId": "null",
"campaignId": "608",
"adGroupId": "null",
"keywordTargetingListId": "123"
},
{
"id": "769734",
"connectionType": "exclude",
"agencyId": "null",
"accountId": "null",
"campaignId": "null",
"adGroupId": "2040",
"keywordTargetingListId": "123"
}
]
}
Reporting ¶
Getting a report is performed asynchronously. First, you create a report job, then you poll its status and finally, when its status is DONE, you receive a link to a CSV file in the result field.
We advise the implementation of an exponential backoff retrying mechanism in order to gap occasional service issues.
Filters
Time Filter
{
"field": "Date",
"operator": "between",
"from": "2016-10-01",
"to": "2016-10-31"
}
Equal Filter
Supported fields: Account Id, Campaign Id, Ad Group Id, Media Source Id
{
"field": "Ad Group Id",
"operator": "=",
"value": "2040"
}
In Filter
Supported fields: Account Id, Campaign Id, Ad Group Id, Content Ad Id, Media Source Id
{
"field": "Ad Group Id",
"operator": "IN",
"values": ["2040", "2041"]
}
Options
Property | Type | Default | Description |
---|---|---|---|
showArchived | bool | false | Set to true to include the data from the archived entities. |
showBlacklistedPublishers | bool | false | Set to true to include the data from the excluded publishers and placements. |
includeTotals | bool | false | Set to true to include the totals in the last row. |
includeItemsWithNoSpend | bool | false | Set to true to include the data of the entities (and/or delivery) with no spend. |
allAccountsInLocalCurrency | bool | false | Show all the money data in the currency of the parent account. |
showStatusDate | bool | false | Add the current date to the status column name. |
recipients | array[string] | [] | When the report is ready, the link to it will be sent to all the emails in the list. |
order | string | -Media Spend | The field by which the report rows will be ordered. A - can be optionally added in front, denoting the descending order. |
csvSeparator | string | , |
The character that separates the csv columns. |
csvDecimalSeparator | string | . |
The character that separates the integer and the fractional parts in decimal values. |
Fields
Breakdown Fields
When breakdown fields are specified, the report will be broken down by that field.
Entity breakdown:
-
Account, Account Id
-
Campaign, Campaign Id
-
Ad Group, Ad Group Id
-
Content Ad, Content Ad Id
Delivery breakdown:
-
Media Source, Media Source Id
-
Publisher
-
Placement
-
Environment
-
Device
-
Operating System
-
Country
-
State / Region
-
DMA
Time breakdown:
-
Day (e.g. 2017-03-30)
-
Date Hour (e.g. 2017-03-30 20:00:00)
-
Hour of Day (e.g. 03:00:00)
-
Week (e.g. Week 2017-03-27 - 2017-04-02)
-
Month (e.g. Month 3/2017)
Audience breakdown:
Because of the nature of the data, a user or a page can be categorised into multiple segments. To ensure accurate data representation, you will see some impressions counted in multiple categories. That is why the totals column will have a different value than in other breakdowns and should not be used as a reference for final cost calculations.
-
Interest
-
Age
-
Gender
Entity Specific Fields
-
Content Ad:
- URL
- Display URL
- Brand Name
- Description
- Image Hash
- Image URL
- Call to action
- Label
- Uploaded
- Batch Name
-
Media Source:
- Media Source Slug
-
Placement:
- Placement Type
Common Fields
Any fields that can be viewed in the dashboard can be requested in a report.
-
Impressions
-
Clicks
-
CTR
-
Avg. CPC
-
Avg. CPM
-
Yesterday Spend
-
Media Spend
-
Data Cost
-
License Fee
-
Total Spend
-
Margin
-
Total Spend + Margin
-
Visits
-
Unique Users
-
New Users
-
Returning Users
-
% New Users
-
Pageviews
-
Pageviews per Visit
-
Bounced Visits
-
Non-Bounced Visits
-
Bounce Rate
-
Total Seconds
-
Time on Site
-
Avg. Cost per Visit
-
Avg. Cost per New Visitor
-
Avg. Cost per Pageview
-
Avg. Cost per Non-Bounced Visit
-
Avg. Cost per Minute
-
Avg. Cost per Unique User
-
Account Status
-
Campaign Status
-
Ad Group Status
-
Content Ad Status
-
Media Source Status
-
Publisher Status
-
Video Start
-
Video First Quartile
-
Video Midpoint
-
Video Third Quartile
-
Video Complete
-
Video Progress 3s
-
Avg. CPV
-
Avg. CPCV
-
Measurable Impressions
-
Viewable Impressions
-
Not-Measurable Impressions
-
Not-Viewable Impressions
-
% Measurable Impressions
-
% Viewable Impressions
-
Impression Distribution (Viewable)
-
Impression Distribution (Not-Measurable)
-
Impression Distribution (Not-Viewable)
-
Avg. VCPM
-
Predictive Clearing Value-add
-
Predictive Clearing Potential Value-add
Conversion Fields
To get conversion data in the report, generate the column name by combining KPI, conversion definition name and attribution type values in this order, separated by a space.
To get the data for KPI other than conversion, the rest of the field needs to be in brackets (example below).
For example, if your conversion definition’s name is “MyConversionDefinition”, the valid column names would be:
-
to get conversion for click attribution:
MyConversionDefinition - Click attr.
-
to get CPA for view attribution:
CPA (MyConversionDefinition - View attr.)
Possible values:
-
KPI:
- omitted value - conversion
CPA
- CPAROAS
- ROAS
-
Conversion definition name
-
Attribution type:
- Click attr.
- click attribution- View attr.
- view attribution
Report jobs ¶
Headers
Content-Type: application/json
Body
{
"fields": [
{
"field": "Content Ad Id"
},
{
"field": "Content Ad"
},
{
"field": "Label"
},
{
"field": "Total Spend"
},
{
"field": "Impressions"
},
{
"field": "Clicks"
},
{
"field": "Avg. CPC"
}
],
"options": {
"showArchived": true
},
"filters": [
{
"field": "Date",
"operator": "between",
"from": "2016-10-01",
"to": "2016-10-31"
},
{
"field": "Ad Group Id",
"operator": "=",
"value": "2040"
}
]
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "27",
"status": "IN_PROGRESS",
"result": null
}
}
Headers
Content-Type: application/json
Body
{
"data": {
"id": "27",
"status": "DONE",
"result": "https://z1-rest-reports.s3.amazonaws.com/KgrK55qCMO85v9JhHwCIv8kso2quYwEGV2MLpiVUgDVRDJm3HiGk1lWrOGfxJ7k2.csv"
}
}
Books closed ¶
Headers
Content-Type: application/json
Body
{
"data": {
"trafficData": {
"latestCompleteDate": "2020-11-16"
}
}
}
Real-time Reporting ¶
Real-time Reporting ¶
Headers
Content-Type: application/json
Body
{
"count": 1,
"next": null,
"data": [
{
"campaignId": 1234,
"spend": "1234.0000",
"impressions": 12341,
"clicks": 4321,
"ctr": "0.05",
"cpc": "0.29",
"cpm": "0.01"
}
]
}
Get real-time stats ¶GET/rest/v1/realtimestats/{?breakdown,marker,limit,accountId,campaignId,adGroupId,contentAdId}
The request is required to have at least one of the accountId
, campaignId
, adGroupId
or contentAdId
parameters set.
Example request: /rest/v1/realtimestats/?accountId=168&breakdown=adGroupId
- breakdown
string
(required) Example: campaignIdValid choices are
campaignId
,adGroupId
,contentAdId
- marker
integer
(optional) Example: 0the primary key of the last element in the previous page (the first page has
marker=0
)- limit
integer
(optional) Default: 100 Example: 100Maximum number of entries to return, up to
1000
- accountId
integer
(optional) Example: 186Optional account ID
- campaignId
integer
(optional)Optional campaign ID
- adGroupId
integer
(optional)Optional ad group ID
- contentAdId
integer
(optional)Optional content ad ID
Utilities ¶
Geolocations ¶
Headers
Content-Type: application/json
Body
{
"data": [
{
"key": "US",
"type": "COUNTRY",
"name": "United States"
},
{
"key": "US-HI",
"type": "REGION",
"name": "Hawaii, United States"
}
]
}
List geolocations ¶GET/rest/v1/geolocations/{?keys,types,nameContains,limit,offset}
- keys
string
(optional) Example: US,US-HIComma-separated list of location keys
- types
string
(optional) Example: COUNTRY,REGIONComma-separated list of location types
- nameContains
string
(optional) Example: UnitedSearch query
- limit
int
(optional) Default: 10 Example: 10Maximum number of locations to return, up to
50
- offset
int
(optional) Example: 00-based starting index
DMP Categories ¶
The categoryId
field is the internal Zementa’s representation and needs to be used in the targeting expressions.
The externalCategoryId
field represents the 3rd party ID numbering of the respective DMPs.
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "5623",
"categoryId": "671901",
"externalCategoryId": "845724",
"dmpType": "obi",
"name": "Parent category name",
"price": "1.0",
"childNodes": [
{
"id": "5624",
"categoryId": "671902",
"externalCategoryId": "845725",
"dmpType": "obi",
"name": "Child category name",
"price": "1.0",
"childNodes": []
}
]
}
]
}
Sources ¶
Headers
Content-Type: application/json
Body
{
"slug": "outbrainrtb",
"name": "Outbrain RTB",
"auditors": [
"OUTBRAIN"
]
}
Additional Types ¶
Money
A string representing a decimal number. Example: "15.48"
Constants reference ¶
Account / Currency
-
USD
- US Dollar -
EUR
- Euro -
GBP
- British Pound -
AUD
- Australian Dollar -
SGD
- Singapore Dollar -
BRL
- Brazilian Real -
MYR
- Malaysian Ringgit -
CHF
- Swiss Franc -
ZAR
- South African Rand -
ILS
- Israeli New Shekel -
INR
- Indian Rupee -
JPY
- Japanese Yen -
CAD
- Canadian Dollar -
NZD
- New Zealand Dollar -
TRY
- Turkish Lira -
MXN
- Mexican Peso
Audience rule type
Include traffic that meets the following conditions:
People who visited specific web pages
-
STARTS_WITH
- URL starts with specified value -
CONTAINS
- URL contains specified value
Anyone who visited your website
VISIT
Ad group / Ad State
-
ACTIVE
-
INACTIVE
Autopilot State
-
ACTIVE
- Minimal Bid Bidding Strategy -
INACTIVE
- Target Bid Bidding Strategy
Campaign type
-
NATIVE
- Native -
DISPLAY
- Display -
VIDEO
- Video -
CONTENT
- Native Ad Campaign (deprecated on March 30th 2021) -
CONVERSION
- Native Conversion Marketing (deprecated) -
MOBILE
- Native Mobile App Advertising (deprecated)
Delivery Status
-
ACTIVE
- Active -
INACTIVE
- Inactive -
STOPPED
- Stopped -
DISABLED
- Disabled - Contact Zemanta CSM
Inventory access level
-
EXPANDED
- Serve your campaigns on most of the available inventory - excludes globally blocked and fraudulent traffic. -
STANDARD
- Serve your campaigns on inventory appropriate for most advertisers. Excludes same es Expanded, but limits buying to apps and websites not yet approved or categorized. -
LIMITED
- Serve your campaigns on a limited list of manually curated publishers.
Language
-
ARABIC
- Arabic -
GERMAN
- German -
GREEK
- Greek -
ENGLISH
- English -
SPANISH
- Spanish -
FRENCH
- French -
INDONESIAN
- Indonesian -
ITALIAN
- Italian -
JAPANESE
- Japanese -
MALAY
- Malay -
DUTCH
- Dutch -
DANISH
- Danish -
FINNISH
- Finnish -
NORWEGIAN
- Norwegian -
PORTUGUESE
- Portuguese -
ROMANIAN
- Romanian -
RUSSIAN
- Russian -
SWEDISH
- Swedish -
TURKISH
- Turkish -
VIETNAMESE
- Vietnamese -
SIMPLIFIED_CHINESE
- Simplified Chinese -
TRADITIONAL_CHINESE
- Traditional Chinese -
KOREAN
- Korean -
OTHER
- Other
IAB Category
-
IAB1_1
- Books & Literature -
IAB1_2
- Celebrity Fan/Gossip -
IAB1_3
- Fine Art -
IAB1_4
- Humor -
IAB1_5
- Movies -
IAB1_6
- Music -
IAB1_7
- Television -
IAB2_1
- Auto Parts -
IAB2_2
- Auto Repair -
IAB2_3
- Buying/Selling Cars -
IAB2_4
- Car Culture -
IAB2_5
- Certified Pre-Owned -
IAB2_6
- Convertible -
IAB2_7
- Coupe -
IAB2_8
- Crossover -
IAB2_9
- Diesel -
IAB2_10
- Electric Vehicle -
IAB2_11
- Hatchback -
IAB2_12
- Hybrid -
IAB2_13
- Luxury -
IAB2_14
- MiniVan -
IAB2_15
- Motorcycles -
IAB2_16
- Off-Road Vehicles -
IAB2_17
- Performance Vehicles -
IAB2_18
- Pickup -
IAB2_19
- Road-Side Assistance -
IAB2_20
- Sedan -
IAB2_21
- Trucks & Accessories -
IAB2_22
- Vintage Cars -
IAB2_23
- Wagon -
IAB3_1
- Advertising -
IAB3_2
- Agriculture -
IAB3_3
- Biotech/Biomedical -
IAB3_4
- Business Software -
IAB3_5
- Construction -
IAB3_6
- Forestry -
IAB3_7
- Government -
IAB3_8
- Green Solutions -
IAB3_9
- Human Resources -
IAB3_10
- Logistics -
IAB3_11
- Marketing -
IAB3_12
- Metals -
IAB4_1
- Career Planning -
IAB4_2
- College -
IAB4_3
- Financial Aid -
IAB4_4
- Job Fairs -
IAB4_5
- Job Search -
IAB4_6
- Resume Writing/Advice -
IAB4_7
- Nursing -
IAB4_8
- Scholarships -
IAB4_9
- Telecommuting -
IAB4_10
- U.S. Military -
IAB4_11
- Career Advice -
IAB5_1
- 7-12 Education -
IAB5_2
- Adult Education -
IAB5_3
- Art History -
IAB5_4
- College Administration -
IAB5_5
- College Life -
IAB5_6
- Distance Learning -
IAB5_7
- English as a 2nd Language -
IAB5_8
- Language Learning -
IAB5_9
- Graduate School -
IAB5_10
- Homeschooling -
IAB5_11
- Homework/Study Tips -
IAB5_12
- K-6 Educators -
IAB5_13
- Private School -
IAB5_14
- Special Education -
IAB5_15
- Studying Business -
IAB6_1
- Adoption -
IAB6_2
- Babies & Toddlers -
IAB6_3
- Daycare/Preschool -
IAB6_4
- Family Internet -
IAB6_5
- Parenting - K-6 Kids -
IAB6_6
- Parenting teens -
IAB6_7
- Pregnancy -
IAB6_8
- Special Needs Kids -
IAB6_9
- Eldercare -
IAB7_1
- Exercise -
IAB7_2
- A.D.D. -
IAB7_3
- AIDS/HIV -
IAB7_4
- Allergies -
IAB7_5
- Alternative Medicine -
IAB7_6
- Arthritis -
IAB7_7
- Asthma -
IAB7_8
- Autism/PDD -
IAB7_9
- Bipolar Disorder -
IAB7_10
- Brain Tumor -
IAB7_11
- Cancer -
IAB7_12
- Cholesterol -
IAB7_13
- Chronic Fatigue Syndrome -
IAB7_14
- Chronic Pain -
IAB7_15
- Cold & Flu -
IAB7_16
- Deafness -
IAB7_17
- Dental Care -
IAB7_18
- Depression -
IAB7_19
- Dermatology -
IAB7_20
- Diabetes -
IAB7_21
- Epilepsy -
IAB7_22
- GERD/Acid Reflux -
IAB7_23
- Headaches/Migraines -
IAB7_24
- Heart Disease -
IAB7_25
- Herbs for Health -
IAB7_26
- Holistic Healing -
IAB7_27
- IBS/Crohn’s Disease -
IAB7_28
- Incest/Abuse Support -
IAB7_29
- Incontinence -
IAB7_30
- Infertility -
IAB7_31
- Men’s Health -
IAB7_32
- Nutrition -
IAB7_33
- Orthopedics -
IAB7_34
- Panic/Anxiety Disorders -
IAB7_35
- Pediatrics -
IAB7_36
- Physical Therapy -
IAB7_37
- Psychology/Psychiatry -
IAB7_38
- Senior Health -
IAB7_39
- Sexuality -
IAB7_40
- Sleep Disorders -
IAB7_41
- Smoking Cessation -
IAB7_42
- Substance Abuse -
IAB7_43
- Thyroid Disease -
IAB7_44
- Weight Loss -
IAB7_45
- Women’s Health -
IAB8_1
- American Cuisine -
IAB8_2
- Barbecues & Grilling -
IAB8_3
- Cajun/Creole -
IAB8_4
- Chinese Cuisine -
IAB8_5
- Cocktails/Beer -
IAB8_6
- Coffee/Tea -
IAB8_7
- Cuisine-Specific -
IAB8_8
- Desserts & Baking -
IAB8_9
- Dining Out -
IAB8_10
- Food Allergies -
IAB8_11
- French Cuisine -
IAB8_12
- Health/Low Fat Cooking -
IAB8_13
- Italian Cuisine -
IAB8_14
- Japanese Cuisine -
IAB8_15
- Mexican Cuisine -
IAB8_16
- Vegan -
IAB8_17
- Vegetarian -
IAB8_18
- Wine -
IAB9_1
- Art/Technology -
IAB9_2
- Arts & Crafts -
IAB9_3
- Beadwork -
IAB9_4
- Birdwatching -
IAB9_5
- Board Games/Puzzles -
IAB9_6
- Candle & Soap Making -
IAB9_7
- Card Games -
IAB9_8
- Chess -
IAB9_9
- Cigars -
IAB9_10
- Collecting -
IAB9_11
- Comic Books -
IAB9_12
- Drawing/Sketching -
IAB9_13
- Freelance Writing -
IAB9_14
- Genealogy -
IAB9_15
- Getting Published -
IAB9_16
- Guitar -
IAB9_17
- Home Recording -
IAB9_18
- Investors & Patents -
IAB9_19
- Jewelry Making -
IAB9_20
- Magic & Illusion -
IAB9_21
- Needlework -
IAB9_22
- Painting -
IAB9_23
- Photography -
IAB9_24
- Radio -
IAB9_25
- Roleplaying Games -
IAB9_26
- Sci-Fi & Fantasy -
IAB9_27
- Scrapbooking -
IAB9_28
- Screenwriting -
IAB9_29
- Stamps & Coins -
IAB9_30
- Video & Computer Games -
IAB9_31
- Woodworking -
IAB10_1
- Appliances -
IAB10_2
- Entertaining -
IAB10_3
- Environmental Safety -
IAB10_4
- Gardening -
IAB10_5
- Home Repair -
IAB10_6
- Home Theater -
IAB10_7
- Interior Decorating -
IAB10_8
- Landscaping -
IAB10_9
- Remodeling & Construction -
IAB11_1
- Immigration -
IAB11_2
- Legal Issues -
IAB11_3
- U.S. Government Resources -
IAB11_4
- Politics -
IAB11_5
- Commentary -
IAB12_1
- International News -
IAB12_2
- National News -
IAB12_3
- Local News -
IAB13_1
- Beginning Investing -
IAB13_2
- Credit/Debt & Loans -
IAB13_3
- Financial News -
IAB13_4
- Financial Planning -
IAB13_5
- Hedge Fund -
IAB13_6
- Insurance -
IAB13_7
- Investing -
IAB13_8
- Mutual Funds -
IAB13_9
- Options -
IAB13_10
- Retirement Planning -
IAB13_11
- Stocks -
IAB13_12
- Tax Planning -
IAB14_1
- Dating -
IAB14_2
- Divorce Support -
IAB14_3
- Gay Life -
IAB14_4
- Marriage -
IAB14_5
- Senior Living -
IAB14_6
- Teens -
IAB14_7
- Weddings -
IAB14_8
- Ethnic Specific -
IAB15_1
- Astrology -
IAB15_2
- Biology -
IAB15_3
- Chemistry -
IAB15_4
- Geology -
IAB15_5
- Paranormal Phenomena -
IAB15_6
- Physics -
IAB15_7
- Space/Astronomy -
IAB15_8
- Geography -
IAB15_9
- Botany -
IAB15_10
- Weather -
IAB16_1
- Aquariums -
IAB16_2
- Birds -
IAB16_3
- Cats -
IAB16_4
- Dogs -
IAB16_5
- Large Animals -
IAB16_6
- Reptiles -
IAB16_7
- Veterinary Medicine -
IAB17_1
- Auto Racing -
IAB17_2
- Baseball -
IAB17_3
- Bicycling -
IAB17_4
- Bodybuilding -
IAB17_5
- Boxing -
IAB17_6
- Canoeing/Kayaking -
IAB17_7
- Cheerleading -
IAB17_8
- Climbing -
IAB17_9
- Cricket -
IAB17_10
- Figure Skating -
IAB17_11
- Fly Fishing -
IAB17_12
- Football -
IAB17_13
- Freshwater Fishing -
IAB17_14
- Game & Fish -
IAB17_15
- Golf -
IAB17_16
- Horse Racing -
IAB17_17
- Horses -
IAB17_18
- Hunting/Shooting -
IAB17_19
- Inline Skating -
IAB17_20
- Martial Arts -
IAB17_21
- Mountain Biking -
IAB17_22
- NASCAR Racing -
IAB17_23
- Olympics -
IAB17_24
- Paintball -
IAB17_25
- Power & Motorcycles -
IAB17_26
- Pro Basketball -
IAB17_27
- Pro Ice Hockey -
IAB17_28
- Rodeo -
IAB17_29
- Rugby -
IAB17_30
- Running/Jogging -
IAB17_31
- Sailing -
IAB17_32
- Saltwater Fishing -
IAB17_33
- Scuba Diving -
IAB17_34
- Skateboarding -
IAB17_35
- Skiing -
IAB17_36
- Snowboarding -
IAB17_37
- Surfing/Bodyboarding -
IAB17_38
- Swimming -
IAB17_39
- Table Tennis/Ping-Pong -
IAB17_40
- Tennis -
IAB17_41
- Volleyball -
IAB17_42
- Walking -
IAB17_43
- Waterski/Wakeboard -
IAB17_44
- World Soccer -
IAB18_1
- Beauty -
IAB18_2
- Body Art -
IAB18_3
- Fashion -
IAB18_4
- Jewelry -
IAB18_5
- Clothing -
IAB18_6
- Accessories -
IAB19_1
- 3D Graphics -
IAB19_2
- Animation -
IAB19_3
- Antivirus Software -
IAB19_4
- C/C++ -
IAB19_5
- Cameras & Camcorders -
IAB19_6
- Cell Phones -
IAB19_7
- Computer Certification -
IAB19_8
- Computer Networking -
IAB19_9
- Computer Peripherals -
IAB19_10
- Computer Reviews -
IAB19_11
- Data Centers -
IAB19_12
- Databases -
IAB19_13
- Desktop Publishing -
IAB19_14
- Desktop Video -
IAB19_15
- Email -
IAB19_16
- Graphics Software -
IAB19_17
- Home Video/DVD -
IAB19_18
- Internet Technology -
IAB19_19
- Java -
IAB19_20
- JavaScript -
IAB19_21
- Mac Support -
IAB19_22
- MP3/MIDI -
IAB19_23
- Net Conferencing -
IAB19_24
- Net for Beginners -
IAB19_25
- Network Security -
IAB19_26
- Palmtops/PDAs -
IAB19_27
- PC Support -
IAB19_28
- Portable -
IAB19_29
- Entertainment -
IAB19_30
- Shareware/Freeware -
IAB19_31
- Unix -
IAB19_32
- Visual Basic -
IAB19_33
- Web Clip Art -
IAB19_34
- Web Design/HTML -
IAB19_35
- Web Search -
IAB19_36
- Windows -
IAB20_1
- Adventure Travel -
IAB20_2
- Africa -
IAB20_3
- Air Travel -
IAB20_4
- Australia & New Zealand -
IAB20_5
- Bed & Breakfasts -
IAB20_6
- Budget Travel -
IAB20_7
- Business Travel -
IAB20_8
- By US Locale -
IAB20_9
- Camping -
IAB20_10
- Canada -
IAB20_11
- Caribbean -
IAB20_12
- Cruises -
IAB20_13
- Eastern Europe -
IAB20_14
- Europe -
IAB20_15
- France -
IAB20_16
- Greece -
IAB20_17
- Honeymoons/Getaways -
IAB20_18
- Hotels -
IAB20_19
- Italy -
IAB20_20
- Japan -
IAB20_21
- Mexico & Central America -
IAB20_22
- National Parks -
IAB20_23
- South America -
IAB20_24
- Spas -
IAB20_25
- Theme Parks -
IAB20_26
- Traveling with Kids -
IAB20_27
- United Kingdom -
IAB21_1
- Apartments -
IAB21_2
- Architects -
IAB21_3
- Buying/Selling Homes -
IAB22_1
- Contests & Freebies -
IAB22_2
- Couponing -
IAB22_3
- Comparison -
IAB22_4
- Engines -
IAB23_1
- Alternative Religions -
IAB23_2
- Atheism/Agnosticism -
IAB23_3
- Buddhism -
IAB23_4
- Catholicism -
IAB23_5
- Christianity -
IAB23_6
- Hinduism -
IAB23_7
- Islam -
IAB23_8
- Judaism -
IAB23_9
- Latter-Day Saints -
IAB23_10
- Pagan/Wiccan -
IAB24
- Uncategorized -
IAB25_1
- Unmoderated UGC -
IAB25_2
- Extreme Graphic/Explicit Violence -
IAB25_3
- Pornography -
IAB25_4
- Profane Content -
IAB25_5
- Hate Content -
IAB25_6
- Under Construction -
IAB25_7
- Incentivized -
IAB26_1
- Illegal Content -
IAB26_2
- Warez -
IAB26_3
- Spyware/Malware -
IAB26_4
- Copyright Infringement
GA Tracking Type
-
EMAIL
-
API
Measurement
Measurement service type
JS_TAG
- JS tag
Conversion type
-
OTHER
- Other -
LEGACY
- Legacy -
ADD_TO_CART
- Add to cart -
ADD_TO_WISHLIST
- Add to wishlist -
COMPLETE_REGISTRATION
- Complete registration -
CONTACT
- Contact -
LEAD
- Lead -
PAGE_VIEW
- Page view -
PURCHASE
- Purchase -
START_TRIAL
- Start trial -
SUBSCRIBE
- Subscribe
Attribution model type
-
ONE
- One -
EVERY
- Every
Attribution model count
-
ONE
- One -
EVERY
- Every
Conversion trigger type
-
RULE
- Rule -
CODE
- Code -
S2S
- S2S
Measurement matching rule target type
URL
- Page URL
Measurement matching rule action type
-
CONTAINS
- Contains -
STARTS_WITH
- Starts with
Publishers
Status
-
ENABLED
-
BLACKLISTED
Level
-
ACCOUNT
-
CAMPAIGN
-
ADGROUP
Campaign Goal KPIs
-
TIME_ON_SITE
- Time on Site - Seconds -
MAX_BOUNCE_RATE
- Max Bounce Rate -
PAGES_PER_SESSION
- Pageviews per Visit -
CPA
- Cost per Acquisition -
CPC
- Cost per Click -
CPV
- Cost per Visit -
CP_NON_BOUNCED_VISIT
- Cost per Non-Bounced Visit -
CP_PAGE_VIEW
- Cost per Page View -
CPCV
- Cost per Completed Video View -
CTR
- CTR -
CP_MINUTE
- Cost per Minute
Conversion goal type
-
PIXEL
- Conversion Pixel -
GA4
- Google Analytics 4 -
GA
- Google Analytics -
OMNITURE
- Adobe Analytics
Conversion window
-
LEQ_1_DAY
- 1 day -
LEQ_7_DAYS
- 7 days -
LEQ_30_DAYS
- 30 days -
LEQ_90_DAYS
- 90 days
Image crop
-
OPTIMIZED
- Optimized Image crop will enable us to find and bid with the best cropping strategy for the ad placement in order to maximize number of clicks on budget spend. If the ad group does not get enough volume, the strategy that works best on average will be applied to the placement instead. -
CENTER
-
FACES
-
ENTROPY
-
LEFT
-
RIGHT
-
TOP
-
BOTTOM
-
FILL
- Resizes the image to fit within the requested width and height dimensions while preserving the original aspect ratio and without discarding any original image data. Excess space is filled with a blurred version of the image.
Tracker event type
-
IMPRESSION
- Impression -
VIEWABILITY
- Viewability -
FIRST_QUARTILE
- First quartile -
MIDPOINT
- Midpoint -
THIRD_QUARTILE
- Third quartile -
COMPLETE
- Completion -
CLICK
- Click
Tracker method
-
IMG
- Image-pixel tracking -
JS
- Javascript-based tracking
Auditor
-
OUTBRAIN
- Outbrain -
APPNEXUS
- AppNexus -
APPNEXUS_DISPLAY
- AppNexus Display -
GOOGLEADX
- GoogleADX -
GOOGLEADX_DISPLAY
- GoogleADX Display -
TRIPLELIFT
- Triplelift
Audit status
-
PENDING
-
APPROVED
-
REJECTED
Ad upload batch status
-
DONE
-
FAILED
-
IN_PROGRESS
Video upload status
-
NOT_UPLOADED
-
PROCESSING
-
READY_FOR_USE
-
PROCESSING_ERROR
Video upload type
-
DIRECT_UPLOAD
-
VAST_UPLOAD
-
VAST_URL
Delivery Type
-
STANDARD
- Deliver ads throughout the day. -
ACCELERATED
- Deliver ads as soon as possible.
Device targeting
-
DESKTOP
-
TABLET
-
MOBILE
Environment targeting
-
SITE
-
APP
Operating system targeting
-
ANDROID
- Android -
IOS
- iOS -
WINPHONE
- Windows Phone -
WINRT
- WinRT -
WINDOWS
- Windows -
MACOSX
- macOS -
LINUX
- Linux -
CHROMEOS
- ChromeOS
Operating system version targeting
-
ANDROID_2
- 2 -
ANDROID_3
- 3 -
ANDROID_4
- 4 -
ANDROID_5
- 5 -
ANDROID_6
- 6 -
ANDROID_7
- 7 -
ANDROID_8
- 8 -
ANDROID_9
- 9 -
ANDROID_10
- 10 -
ANDROID_11
- 11 -
ANDROID_12
- 12 -
ANDROID_13
- 13 -
ANDROID_14
- 14 -
IOS_3
- 3 -
IOS_4
- 4 -
IOS_5
- 5 -
IOS_6
- 6 -
IOS_7
- 7 -
IOS_8
- 8 -
IOS_9
- 9 -
IOS_10
- 10 -
IOS_11
- 11 -
IOS_12
- 12 -
IOS_13
- 13 -
IOS_14
- 14 -
IOS_15
- 15 -
IOS_16
- 16 -
IOS_17
- 17 -
IOS_18
- 18 -
WINPHONE_7
- 7 -
WINPHONE_8
- 8 -
WINPHONE_10
- 10 -
WINDOWS_98
- 98 -
WINDOWS_2000
- 2000 -
WINDOWS_XP
- XP -
WINDOWS_VISTA
- Vista -
WINDOWS_7
- 7 -
WINDOWS_8
- 8 -
WINDOWS_10
- 10/11 -
MACOSX_10
- 10 -
MACOSX_11
- 11 -
MACOSX_12
- 12 -
MACOSX_13
- 13 -
MACOSX_14
- 14
Browser targeting
-
CHROME
- Chrome -
SAFARI
- Safari -
FIREFOX
- Firefox -
IE
- Internet Explorer -
OPERA
- Opera -
EDGE
- Microsoft Edge -
SAMSUNG
- Samsung -
UC_BROWSER
- UC Browser -
OTHER
- Other (any browser other than the others named here)
Connection type targeting
-
WIFI
- Wi-Fi -
CELLULAR
- Cellular
Channel targeting
-
NATIVE
- Native -
DISPLAY
- Native-to-display/Display -
VIDEO
- Native-to-video/Video
Interest targeting
-
COMMUNICATION
- Communication Tools -
MEN
- Men’s Lifestyle -
DATING
- Dating & Relationships -
WEATHER
- Weather & Environment -
FASHION
- Beauty & Fashion -
TRAVEL
- Travel and Leisure -
FUN_QUIZZES
- Viral, lists & Quizzes -
HEALTH
- Health & Fitness -
SCIENCE
- Science -
TECHNOLOGY
- Technology -
CARS
- Automotive -
MEDIA
- News -
HOME
- Home & Garden -
FAMILY
- Family & Parenting -
SHOPPING_COUPONS
- Shopping -
ENTERTAINMENT
- Arts & Entertainment -
HOBBIES
- Hobbies & Interests -
RELIGION
- Religion & Spirituality -
MUSIC
- Music -
FOOD
- Food & Drink -
SPANISH
- Spanish Sites -
PETS
- Pets -
WOMEN
- Women’s Lifestyle -
SPORTS
- Sports -
FRENCH
- French Sites -
POLITICS_LAW
- Law, Gov’t & Politics -
GAMES
- Games & Gaming -
FINANCE
- Business & Finance -
EDUCATION
- Education -
UTILITY
- Software & Services -
OTHER
- Other -
FOREIGN
- International Sites -
PREMIUM
- Premium
IAB Content categories
IDs of the categories from the IAB Content Taxonomy 2.2 found here. See column Value
in the taxonomy.
Ad positions
-
ABOVE_THE_FOLD
- Position the ad in the initially visible part of the website. -
BELOW_THE_FOLD
- Position the ad below the initially visible part of the website. -
HEADER
- Position the ad in the header of the website. -
FOOTER
- Position the ad in the footer of the website. -
SIDEBAR
- Position the ad in the sidebar of the website. -
FULL_SCREEN
- Position of the ad in a full-screen banner inline with the content. -
UNKNOWN
- Position of the ad is unknown.
Ad placement types
-
IN_STREAM
- Place ads to be served during video playback (mid-roll) -
IN_BANNER
- Place ads in website banners -
IN_ARTICLE
- Place native ads between the paragraphs of your pages -
IN_FEED
- Place ads between the content of your feed -
FLOATING
- Place ads that flows/slides into the main page using animation -
IN_WIDGET
- Place ads in recommendation widgets
Display ad sizes
-
INLINE_RECTANGLE
- Inline rectangle -
MOBILE_LEADERBOARD
- Mobile leaderboard -
MOBILE_BANNER
- Mobile banner -
LEADERBOARD
- Leaderboard -
MOBILE_INTERSTITIAL
- Mobile interstitial -
LARGE_RECTANGLE
- Large rectangle -
HALF_PAGE
- Half page -
SKYSCRAPER
- Skyscraper -
WIDE_SKYSCRAPER
- Wide Skyscraper -
LARGE_MOBILE_BANNER
- Large mobile banner -
LARGE_MOBILE_BANNER_300
- Large mobile banner (300x100) -
BANNER
- Banner -
PORTRAIT
- Portrait -
LARGE_LEADERBOARD
- Large leaderboard -
BILLBOARD
- Billboard -
SQUARE
- Square -
SMALL_SQUARE
- Small square -
SMALL_RECTANGLE
- Small rectangle -
BUTTON
- Button -
UPPER_BANNER
- Upper banner -
NETBOARD
- Netboard -
LARGE_BANNER
- Large banner -
LARGE_VERTICAL_BANNER
- Large vertical banner -
LARGE_RECTANGLE_MOBILE
- Large rectangle mobile -
LARGE_RECTANGLE_TABLET
- Large rectangle tablet -
LARGE_PORTRAIT
- Large portrait
Video protocols
-
VAST_1
- VAST 1.0 -
VAST_1_WRAPPER
- VAST 1.0 WRAPPER -
VAST_2
- VAST 2.0 -
VAST_2_WRAPPER
- VAST 2.0 WRAPPER -
VAST_3
- VAST 3.0 -
VAST_3_WRAPPER
- VAST 3.0 WRAPPER -
VAST_4
- VAST 4.0 -
VAST_4_WRAPPER
- VAST 4.0 WRAPPER -
DAAST_1
- DAAST 1.0 -
DAAST_1_WRAPPER
- DAAST 1.0 WRAPPER
Video API frameworks
-
VPAID_1
- VPAID 1.0 -
VPAID_2
- VPAID 2.0 -
MRAID_1
- MRAID 1.0 -
MRAID_2
- MRAID 2.0 -
MRAID_3
- MRAID 3.0 -
ORMMA
- ORMMA
Video skippability options
-
ALLOW
- Allow -
REQUIRE
- Require -
BLOCK
- Block
Video delays
-
PRE_ROLL
- Pre-roll -
MID_ROLL
- Mid-roll -
POST_ROLL
- Post-roll
Geo targeting
Can be also found and listed under geolocations
Location type
-
COUNTRY
-
REGION
-
CITY
-
DMA
-
ZIP
DMA
-
669
- 669 Madison, WI -
762
- 762 Missoula, MT -
760
- 760 Twin Falls, ID -
766
- 766 Helena, MT -
662
- 662 Abilene-Sweetwater, TX -
764
- 764 Rapid City, SD -
765
- 765 El Paso, TX -
804
- 804 Palm Springs, CA -
610
- 610 Rockford, IL -
692
- 692 Beaumont-Port Arthur, TX -
693
- 693 Little Rock-Pine Bluff, AR -
691
- 691 Huntsville-Decatur (Florence), AL -
698
- 698 Montgomery (Selma), AL -
758
- 758 Idaho Falls-Pocatello, ID -
542
- 542 Dayton, OH -
543
- 543 Springfield-Holyoke, MA -
540
- 540 Traverse City-Cadillac, MI -
541
- 541 Lexington, KY -
546
- 546 Columbia, SC -
547
- 547 Toledo, OH -
544
- 544 Norfolk-Portsmouth-Newport News,VA -
545
- 545 Greenville-New Bern-Washington, NC -
810
- 810 Yakima-Pasco-Richland-Kennewick, WA -
811
- 811 Reno, NV -
548
- 548 West Palm Beach-Ft. Pierce, FL -
813
- 813 Medford-Klamath Falls, OR -
570
- 570 Florence-Myrtle Beach, SC -
678
- 678 Wichita-Hutchinson, KS -
679
- 679 Des Moines-Ames, IA -
718
- 718 Jackson, MS -
717
- 717 Quincy, IL-Hannibal, MO-Keokuk, IA -
675
- 675 Peoria-Bloomington, IL -
676
- 676 Duluth, MN-Superior, WI -
670
- 670 Ft. Smith-Fayetteville-Springdale-Rogers, AR -
671
- 671 Tulsa, OK -
711
- 711 Meridian, MS -
767
- 767 Casper-Riverton, WY -
661
- 661 San Angelo, TX -
673
- 673 Columbus-Tupelo-West Point, MS -
537
- 537 Bangor, ME -
536
- 536 Youngstown, OH -
535
- 535 Columbus, OH -
534
- 534 Orlando-Daytona Beach-Melbourne, FL -
533
- 533 Hartford & New Haven, CT -
828
- 828 Monterey-Salinas, CA -
530
- 530 Tallahassee, FL-Thomasville, GA -
825
- 825 San Diego, CA -
821
- 821 Bend, OR -
820
- 820 Portland, OR -
539
- 539 Tampa-St Petersburg (Sarasota), FL -
538
- 538 Rochester, NY -
592
- 592 Gainesville, FL -
709
- 709 Tyler-Longview(Lufkin & Nacogdoches), TX -
597
- 597 Parkersburg, WV -
596
- 596 Zanesville, OH -
705
- 705 Wausau-Rhinelander, WI -
702
- 702 La Crosse-Eau Claire, WI -
740
- 740 North Platte, NE -
604
- 604 Columbia-Jefferson City, MO -
790
- 790 Albuquerque-Santa Fe, NM -
839
- 839 Las Vegas, NV -
798
- 798 Glendive, MT -
524
- 524 Atlanta, GA -
525
- 525 Albany, GA -
526
- 526 Utica, NY -
527
- 527 Indianapolis, IN -
520
- 520 Augusta, GA -
521
- 521 Providence, RI-New Bedford, MA -
522
- 522 Columbus, GA -
523
- 523 Burlington, VT-Plattsburgh, NY -
528
- 528 Miami-Ft. Lauderdale, FL -
529
- 529 Louisville, KY -
532
- 532 Albany-Schenectady-Troy, NY -
584
- 584 Charlottesville, VA -
582
- 582 Lafayette, IN -
583
- 583 Alpena, MI -
581
- 581 Terre Haute, IN -
588
- 588 South Bend-Elkhart, IN -
598
- 598 Clarksburg-Weston, WV -
789
- 789 Tucson (Sierra Vista), AZ -
519
- 519 Charleston, SC -
640
- 640 Memphis, TN -
643
- 643 Lake Charles, LA -
642
- 642 Lafayette, LA -
644
- 644 Alexandria, LA -
647
- 647 Greenwood-Greenville, MS -
649
- 649 Evansville, IN -
648
- 648 Champaign & Springfield-Decatur,IL -
513
- 513 Flint-Saginaw-Bay City, MI -
512
- 512 Baltimore, MD -
515
- 515 Cincinnati, OH -
514
- 514 Buffalo, NY -
517
- 517 Charlotte, NC -
516
- 516 Erie, PA -
623
- 623 Dallas-Ft. Worth, TX -
622
- 622 New Orleans, LA -
627
- 627 Wichita Falls, TX & Lawton, OK -
626
- 626 Victoria, TX -
625
- 625 Waco-Temple-Bryan, TX -
624
- 624 Sioux City, IA -
573
- 573 Roanoke-Lynchburg, VA -
571
- 571 Ft. Myers-Naples, FL -
628
- 628 Monroe, LA-El Dorado, AR -
577
- 577 Wilkes Barre-Scranton, PA -
576
- 576 Salisbury, MD -
575
- 575 Chattanooga, TN -
574
- 574 Johnstown-Altoona, PA -
606
- 606 Dothan, AL -
600
- 600 Corpus Christi, TX -
559
- 559 Bluefield-Beckley-Oak Hill, WV -
752
- 752 Colorado Springs-Pueblo, CO -
745
- 745 Fairbanks, AK -
855
- 855 Santa Barbara-Santa Maria-San Luis Obispo, CA -
746
- 746 Biloxi-Gulfport, MS -
819
- 819 Seattle-Tacoma, WA -
508
- 508 Pittsburgh, PA -
656
- 656 Panama City, FL -
657
- 657 Sherman, TX-Ada, OK -
652
- 652 Omaha, NE -
734
- 734 Jonesboro, AR -
737
- 737 Mankato, MN -
736
- 736 Bowling Green, KY -
506
- 506 Boston, MA-Manchester, NH -
507
- 507 Savannah, GA -
504
- 504 Philadelphia, PA -
505
- 505 Detroit, MI -
502
- 502 Binghamton, NY -
503
- 503 Macon, GA -
500
- 500 Portland-Auburn, ME -
501
- 501 New York, NY -
630
- 630 Birmingham, AL -
569
- 569 Harrisonburg, VA -
632
- 632 Paducah, KY-Cape Girardeau, MO-Harrisburg-Mount Vernon, IL -
633
- 633 Odessa-Midland, TX -
757
- 757 Boise, ID -
650
- 650 Oklahoma City, OK -
755
- 755 Great Falls, MT -
637
- 637 Cedar Rapids-Waterloo-Iowa City & Dubuque, IA -
638
- 638 St. Joseph, MO -
561
- 561 Jacksonville, FL -
759
- 759 Cheyenne, WY-Scottsbluff, NE -
651
- 651 Lubbock, TX -
564
- 564 Charleston-Huntington, WV -
565
- 565 Elmira, NY -
566
- 566 Harrisburg-Lancaster-Lebanon-York, PA -
567
- 567 Greenville-Spartanburg, SC-Asheville, NC-Anderson, SC -
868
- 868 Chico-Redding, CA -
549
- 549 Watertown, NY -
747
- 747 Juneau, AK -
862
- 862 Sacramento-Stockton-Modesto, CA -
866
- 866 Fresno-Visalia, CA -
724
- 724 Fargo-Valley City, ND -
725
- 725 Sioux Falls(Mitchell), SD -
722
- 722 Lincoln & Hastings-Kearney, NE -
658
- 658 Green Bay-Appleton, WI -
659
- 659 Nashville, TN -
631
- 631 Ottumwa, IA-Kirksville, MO -
605
- 605 Topeka, KS -
753
- 753 Phoenix, AZ -
881
- 881 Spokane, WA -
743
- 743 Anchorage, AK -
744
- 744 Honolulu, HI -
558
- 558 Lima, OH -
603
- 603 Joplin, MO-Pittsburg, KS -
602
- 602 Chicago, IL -
555
- 555 Syracuse, NY -
554
- 554 Wheeling, WV-Steubenville, OH -
557
- 557 Knoxville, TN -
556
- 556 Richmond-Petersburg, VA -
551
- 551 Lansing, MI -
751
- 751 Denver, CO -
553
- 553 Marquette, MI -
552
- 552 Presque Isle, ME -
550
- 550 Wilmington, NC -
634
- 634 Amarillo, TX -
756
- 756 Billings, MT -
749
- 749 Laredo, TX -
641
- 641 San Antonio, TX -
636
- 636 Harlingen-Weslaco-Brownsville-McAllen, TX -
518
- 518 Greensboro-High Point-Winston Salem, NC -
754
- 754 Butte-Bozeman, MT -
560
- 560 Raleigh-Durham (Fayetteville), NC -
716
- 716 Baton Rouge, LA -
618
- 618 Houston, TX -
619
- 619 Springfield, MO -
771
- 771 Yuma, AZ-El Centro, CA -
770
- 770 Salt Lake City, UT -
773
- 773 Grand Junction-Montrose, CO -
612
- 612 Shreveport, LA -
613
- 613 Minneapolis-St. Paul, MN -
563
- 563 Grand Rapids-Kalamazoo-Battle Creek, MI -
611
- 611 Rochester, MN-Mason City, IA-Austin, MN -
616
- 616 Kansas City, MO -
617
- 617 Milwaukee, WI -
511
- 511 Washington, DC (Hagerstown, MD) -
510
- 510 Cleveland-Akron (Canton), OH -
635
- 635 Austin, TX -
710
- 710 Hattiesburg-Laurel, MS -
801
- 801 Eugene, OR -
509
- 509 Ft. Wayne, IN -
686
- 686 Mobile, AL-Pensacola (Ft. Walton Beach), FL -
609
- 609 St. Louis, MO -
803
- 803 Los Angeles, CA -
802
- 802 Eureka, CA -
687
- 687 Minot-Bismarck-Dickinson(Williston), ND -
800
- 800 Bakersfield, CA -
807
- 807 San Francisco-Oakland-San Jose, CA -
639
- 639 Jackson, TN -
682
- 682 Davenport,IA-Rock Island-Moline,IL -
531
- 531 Tri-Cities-Tn-Va
Country
Countries are identified by their ISO 3166-1 alpha-2 code.
Examples:
-
US
- United States -
CA
- Canada
State / Region
States or Regions are identified by the country’s ISO 3166-1 alpha-2
code and the region’s ISO 3166-2 code concatenated with a -
sign.
Examples:
-
US-NY
- New York, United States -
CA-QC
- Quebec, Canada
City
Cities are identified using Geoname IDs.
Examples:
-
5128581
- New York, New York, United States -
6167865
- Toronto, Ontario, Canada
Postal Code
Postal codes are identified by the Country code and the postal code concatenated with a :
(colon) sign.
Examples:
-
US:10001
- New York, United States -
CA:M4E
- East Toronto (The Beaches), Ontario, Canada
DAY HOUR
Day hour constants represent a particular hour of a day of the week and are used for example with bid modifiers to modify bids on traffic at that those hours.
Examples:
-
MONDAY_0
- mondays from 00:00 to 01:00 EST timezone -
SUNDAY_23
- sundays from 23:00 to 00:00 EST timezone
Creative types
-
NATIVE
-
VIDEO
-
DISPLAY_BANNER
-
DISPLAY_AD_TAG
Creative batch status
-
DONE
-
FAILED
-
IN_PROGRESS
Targeting list connection types
-
INCLUDE
- Targeting list is used in an Include setting -
EXCLUDE
- Targeting list is used in an Exclude setting
DMP type
-
OUTBRAIN
-
OUTBRAIN_INTEREST
-
OUTBRAIN_SENTIMENTS
-
EYEOTA
-
NIELSEN
Generated by aglio on 09 Oct 2024