Outbrain DSP API

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

Starting from November 18th, our API will no longer accept any HTTP requests and redirect them to HTTPS due to security reasons, in case you are using HTTP requests, please update the client to use direct calls to HTTPS to prevent unencrypted communication with our servers.

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 Relation Diagram

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 has marker=0)

  • limit: maximum number of entries to return, up to 1000, defaults to 100

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 to 1000, defaults to 100

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.

New application registration form

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.

Application credentials details

Acquire a new authentication token

POST https://oneapi.zemanta.com/o/token/
Requestsexample 1
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WkNTeDJXanhIeHhWNnJLWkMzaGRiNmVqTzhHTHdjZFV0bHRtcHQ5Sjp1N3BsRWQwNG1IYzExQ2NrUzlkb2poWWl3YVd6TnFlQjF3OUtnTXh3ZTVya1c2U3M3bVRSSXg2UGQ4dDdZdmRZYzdiQzEwMjVINzRzOThFMmVxaEljQmx2QmxIc2M1dkFwOVRKTVAyZTh5Nmt5SktRVVdrcFVpckZSbDNPczJmQw==
Body
grant_type=client_credentials
Responses200
Headers
Content-Type: application/json
Body
{
  "access_token": "UUjXNkJDyLVjDzswOjdVm0ySIBYfp7",
  "token_type": "Bearer",
  "expires_in": 36000,
  "scope": "read write"
}

Acquire a new authentication token
POST/o/token/

This request requires you to use your client credentials (client ID and client secret) as Basic HTTP Authentication. Manually, the header can be constructed as

Authorization: Basic base64(<client_id>:<client_secret>)

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
GET https://oneapi.zemanta.com/rest/v1/accounts/186?includeDeliveryStatus=true
Responses200
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"
  }
}

Get account details
GET/rest/v1/accounts/{accountId}{?includeDeliveryStatus}

URI Parameters
HideShow
accountId
string (required) Example: 186
includeDeliveryStatus
bool (optional) Default: false Example: true

PUT https://oneapi.zemanta.com/rest/v1/accounts/186
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "My Account 1",
  "targeting": {
    "publisherGroups": {
      "included": [
        "153"
      ],
      "excluded": [
        "154"
      ]
    }
  },
  "frequencyCapping": 10
}
Responses200
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"
  }
}

Update account details
PUT/rest/v1/accounts/{accountId}

URI Parameters
HideShow
accountId
string (required) Example: 186

GET https://oneapi.zemanta.com/rest/v1/accounts/186/sources/
Responses200
Headers
Content-Type: application/json
Body
{
  "slug": "outbrainrtb",
  "name": "Outbrain RTB",
  "auditors": [
    "OUTBRAIN"
  ]
}

Get account sources
GET/rest/v1/accounts/{accountId}/sources/

URI Parameters
HideShow
accountId
string (required) Example: 186

GET https://oneapi.zemanta.com/rest/v1/accounts/?includeArchived=&includeDeliveryStatus=true
Responses200
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"
    }
  ]
}

List accounts
GET/rest/v1/accounts/{?includeArchived,includeDeliveryStatus}

URI Parameters
HideShow
includeArchived
bool (optional) Default: false 

Set to true to retrieve archived accounts.

includeDeliveryStatus
boolean (optional) Default: false Example: true

POST https://oneapi.zemanta.com/rest/v1/accounts/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "My Account 1",
  "targeting": {
    "publisherGroups": {
      "included": [
        "153"
      ],
      "excluded": [
        "154"
      ]
    }
  },
  "frequencyCapping": 10,
  "agencyId": "1"
}
Responses201
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"
  }
}

Create a new account
POST/rest/v1/accounts/


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
GET https://oneapi.zemanta.com/rest/v1/accounts/186/credits/861
Responses200
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"
  }
}

Get credit item for account
GET/rest/v1/accounts/{accountId}/credits/{creditId}

URI Parameters
HideShow
accountId
string (required) Example: 186
creditId
string (required) Example: 861

GET https://oneapi.zemanta.com/rest/v1/accounts/186/credits/
Responses200
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"
    }
  ]
}

Get active credit items for account
GET/rest/v1/accounts/{accountId}/credits/

URI Parameters
HideShow
accountId
string (required) Example: 186

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
GET https://oneapi.zemanta.com/rest/v1/campaigns/608?includeDeliveryStatus=true
Responses200
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}

URI Parameters
HideShow
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

GET https://oneapi.zemanta.com/rest/v1/campaigns/608?includeDeliveryStatus=true&includeGoals=true&includeBudgets=true
Responses200
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}

URI Parameters
HideShow
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

PUT https://oneapi.zemanta.com/rest/v1/campaigns/608
Requestsexample 1
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
}
Responses200
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"
  }
}

Update campaign details
PUT/rest/v1/campaigns/{campaignId}

URI Parameters
HideShow
campaignId
string (required) Example: 608

GET https://oneapi.zemanta.com/rest/v1/campaigns/?includeArchived=&includeGoals=false&includeBudgets=false&includeDeliveryStatus=true&accountId=186&excludeInactive=true
Responses200
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}

URI Parameters
HideShow
includeArchived
bool (optional) Default: false 

Set 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: 186

Optional account ID.

excludeInactive
bool (optional) Default: false Example: true

Set 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.


GET https://oneapi.zemanta.com/rest/v1/campaigns/?includeArchived=&includeGoals=true&includeBudgets=true&accountId=186&excludeInactive=true
Responses200
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}

URI Parameters
HideShow
includeArchived
bool (optional) Default: false 

Set to true to retrieve archived campaigns.

includeGoals
bool (optional) Default: false Example: true
includeBudgets
bool (optional) Default: false Example: true
accountId
number (optional) Example: 186

Optional account ID.

excludeInactive
bool (optional) Default: false Example: true

Set 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.


GET https://oneapi.zemanta.com/rest/v1/campaigns/ids/?includeArchived=false&accountId=186&excludeInactive=true
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    1834152,
    1942877,
    2488992
  ]
}

Get campaigns IDs
GET/rest/v1/campaigns/ids/{?includeArchived,accountId,excludeInactive}

URI Parameters
HideShow
includeArchived
bool (optional) Default: false Example: false

Set to true to include IDs of archived campaigns.

accountId
number (optional) Example: 186

Optional account ID.

excludeInactive
bool (optional) Default: false Example: true

Set 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.


POST https://oneapi.zemanta.com/rest/v1/campaigns/
Requestsexample 1
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"
}
Responses201
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"
  }
}

Create new campaign
POST/rest/v1/campaigns/


GET https://oneapi.zemanta.com/rest/v1/campaigns/608/stats/?from=2016-11-18&to=2016-11-18
Responses200
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.

URI Parameters
HideShow
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
GET https://oneapi.zemanta.com/rest/v1/campaigns/608/budgets/
Responses200
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"
    }
  ]
}

List campaign budgets
GET/rest/v1/campaigns/{campaignId}/budgets/

URI Parameters
HideShow
campaignId
string (required) Example: 608

POST https://oneapi.zemanta.com/rest/v1/campaigns/608/budgets/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "creditId": "861",
  "amount": "600",
  "margin": "0.1",
  "comment": "my budget",
  "startDate": "2016-01-01",
  "endDate": "2016-01-31"
}
Responses201
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"
  }
}

Create a new campaign budget
POST/rest/v1/campaigns/{campaignId}/budgets/

URI Parameters
HideShow
campaignId
string (required) Example: 608

GET https://oneapi.zemanta.com/rest/v1/campaigns/608/budgets/1910
Responses200
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"
  }
}

Get a campaign budget
GET/rest/v1/campaigns/{campaignId}/budgets/{budgetId}

URI Parameters
HideShow
campaignId
string (required) Example: 608
budgetId
string (required) Example: 1910

PUT https://oneapi.zemanta.com/rest/v1/campaigns/608/budgets/1910
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "amount": "800"
}
Responses200
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"
  }
}

Edit a campaign budget
PUT/rest/v1/campaigns/{campaignId}/budgets/{budgetId}

URI Parameters
HideShow
campaignId
string (required) Example: 608
budgetId
string (required) Example: 1910

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
GET https://oneapi.zemanta.com/rest/v1/campaigns/608/goals/
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "1238",
      "type": "TIME_ON_SITE",
      "primary": true,
      "conversionGoal": {
        "type": "GA",
        "name": "My conversion goal",
        "goalId": "mygoal0"
      }
    }
  ]
}

List campaign goals
GET/rest/v1/campaigns/{campaignId}/goals/

URI Parameters
HideShow
campaignId
string (required) Example: 608

POST https://oneapi.zemanta.com/rest/v1/campaigns/608/goals/
Requestsexample 1example 2
Headers
Content-Type: application/json
Body
{
  "type": "CPA",
  "value": "30.0",
  "primary": false,
  "conversionGoal": {
    "type": "GA",
    "name": "My conversion goal 2",
    "goalId": "mygoal"
  }
}
Responses201
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"
  }
}
Responses201
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).

URI Parameters
HideShow
campaignId
string (required) Example: 608

GET https://oneapi.zemanta.com/rest/v1/campaigns/608/goals/1239
Responses200
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"
    }
  }
}

Get campaign goal details
GET/rest/v1/campaigns/{campaignId}/goals/{goalId}

URI Parameters
HideShow
campaignId
string (required) Example: 608
goalId
string (required) Example: 1239

PUT https://oneapi.zemanta.com/rest/v1/campaigns/608/goals/1239
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "primary": false
}
Responses200
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"
    }
  }
}

Modify a campaign goal
PUT/rest/v1/campaigns/{campaignId}/goals/{goalId}

URI Parameters
HideShow
campaignId
string (required) Example: 608
goalId
string (required) Example: 1239

DELETE https://oneapi.zemanta.com/rest/v1/campaigns/608/goals/1238
Responses204
This response has no content.

Remove campaign goal
DELETE/rest/v1/campaigns/{campaignId}/goals/{goalId}

URI Parameters
HideShow
campaignId
string (required) Example: 608
goalId
string (required) Example: 1238

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 CPCor 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
videoPlayerSizes array[adTargetVideoPlayerSize] Select one or more sizes of video player.
playbackMethods array[adTargetVideoPlaybackMethod] Select one or more playback methods set by IAB.
rewarded adTargetVideoRewarded Require or block the video rewarded option.
skippability adTargetVideoSkippability 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
GET https://oneapi.zemanta.com/rest/v1/adgroups/2040?includeDeliveryStatus=true
Responses200
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"
  }
}

Get ad group details
GET/rest/v1/adgroups/{adGroupId}{?includeDeliveryStatus}

URI Parameters
HideShow
adGroupId
string (required) Example: 2040
includeDeliveryStatus
bool (optional) Default: false Example: true

PUT https://oneapi.zemanta.com/rest/v1/adgroups/2040
Requestsexample 1
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
}
Responses200
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"
  }
}

Update ad group details
PUT/rest/v1/adgroups/{adGroupId}

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

GET https://oneapi.zemanta.com/rest/v1/adgroups/?campaignId=608&accountId=186&includeArchived=&includeDeliveryStatus=true&onlyRecentlyAffected=true
Responses200
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}

URI Parameters
HideShow
accountId
number (optional) Example: 186

Optional account ID.

campaignId
number (optional) Example: 608

Optional campaign ID.

includeArchived
bool (optional) Default: false 

Set to true to retrieve archived ad groups.

includeDeliveryStatus
bool (optional) Default: false Example: true
onlyRecentlyAffected
bool (optional) Default: false Example: true

Set to true to only retrieve ad groups which were changed or had changes on related objects in the last 60 minutes.


POST https://oneapi.zemanta.com/rest/v1/adgroups/
Requestsexample 1
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
}
Responses201
Headers
Content-Type: application/json
Body
<a name="ad-group-sources"></a>

Create new ad group
POST/rest/v1/adgroups/


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
GET https://oneapi.zemanta.com/rest/v1/adgroups/2040/sources/
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "source": "yahoo",
      "state": "ACTIVE"
    },
    {
      "source": "gumgum",
      "state": "ACTIVE"
    },
    {
      "source": "triplelift",
      "state": "ACTIVE"
    }
  ]
}

Get ad group source settings
GET/rest/v1/adgroups/{adGroupId}/sources/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

PUT https://oneapi.zemanta.com/rest/v1/adgroups/2040/sources/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "source": "gumgum",
    "state": "INACTIVE"
  },
  {
    "source": "triplelift",
    "state": "INACTIVE"
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "source": "yahoo",
      "state": "ACTIVE"
    },
    {
      "source": "gumgum",
      "state": "INACTIVE"
    },
    {
      "source": "triplelift",
      "state": "INACTIVE"
    }
  ]
}

Update ad group source settings
PUT/rest/v1/adgroups/{adGroupId}/sources/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

POST https://oneapi.zemanta.com/rest/v1/adgroups/2040/sources/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "source": "adiant",
  "state": "ACTIVE"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "source": "adiant",
    "state": "ACTIVE"
  }
}

Add a new ad group source
POST/rest/v1/adgroups/{adGroupId}/sources/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

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.

POST https://oneapi.zemanta.com/rest/v1/ads/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "adGroupId": "2040",
    "creative": {
      "id": "16805"
    }
  }
]
Responses201
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
          }
        ]
      }
    }
  ]
}

Create ads
POST/rest/v1/ads/


POST https://oneapi.zemanta.com/rest/v1/ads/
Requestsexample 1
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
      }
    ]
  }
}
Responses201
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

GET https://oneapi.zemanta.com/rest/v1/ads/?adGroupId=2040&includeAudits=true&includeSources=true&includeArchived=true
Responses200
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}

URI Parameters
HideShow
adGroupId
number (required) Example: 2040

Ad group ID

includeAudits
boolean (optional) Default: false Example: true

Include Audits

includeSources
boolean (optional) Default: false Example: true

Include Sources

includeArchived
boolean (optional) Default: false Example: true

Set to true to retrieve archived ads.


GET https://oneapi.zemanta.com/rest/v1/ads/16805?imageWidth=300&imageHeight=250&includeAudits=true&includeSources=true
Responses200
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}

URI Parameters
HideShow
adId
string (required) Example: 16805
imageWidth
integer (optional) Example: 300

The width of the ad image.

imageHeight
integer (optional) Example: 250

The height of the ad image.

includeAudits
boolean (optional) Default: false Example: true

Include Audits

includeSources
boolean (optional) Default: false Example: true

Include Sources


PUT https://oneapi.zemanta.com/rest/v1/ads/16805
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "state": "INACTIVE",
  "label": "My updated label",
  "creative": {
    "id": "16805",
    "description": "My updated description"
  }
}
Responses200
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
        }
      ]
    }
  }
}

Edit an Ad
PUT/rest/v1/ads/{adId}

Note: state, label, archived fields are Ad specific fields. You can edit them among other creative fields such as url, displayUrl, brandName, description, callToAction, imageCrop, adTag, trackers and tags.

URI Parameters
HideShow
adId
string (required) Example: 16805

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.
POST https://oneapi.zemanta.com/rest/v1/ads/batch/
Requestsexample 1
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
        }
      ]
    }
  }
]
Responses201
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "1302",
    "status": "IN_PROGRESS",
    "validationStatus": [
      {
        "__all__": "Ad still processing."
      }
    ],
    "approvedAds": []
  }
}

Create a new ad upload batch
POST/rest/v1/ads/batch/


GET https://oneapi.zemanta.com/rest/v1/ads/batch/1302
Responses200
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"
      }
    ]
  }
}

Check ad upload batch status
GET/rest/v1/ads/batch/{batchId}

URI Parameters
HideShow
batchId
string (required) Example: 1302

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
GET https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/?type=
Responses200
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}

URI Parameters
HideShow
adGroupId
string (required) Example: 2040
type
string (optional) 

POST https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "type": "COUNTRY",
  "sourceSlug": "",
  "target": "US",
  "modifier": 1.5
}
Responses201
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "1245",
    "type": "COUNTRY",
    "sourceSlug": "",
    "target": "US",
    "modifier": 1.5
  }
}

Add bid modifier for an ad group
POST/rest/v1/adgroups/{adGroupId}/bidmodifiers/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

PUT https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "type": "COUNTRY",
    "sourceSlug": "",
    "target": "US",
    "modifier": 1.5
  },
  {
    "type": "DEVICE",
    "sourceSlug": "",
    "target": "TABLET",
    "modifier": 1.6
  }
]
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "type": "COUNTRY",
      "sourceSlug": "",
      "target": "US",
      "modifier": 1.5
    },
    {
      "type": "DEVICE",
      "sourceSlug": "",
      "target": "TABLET",
      "modifier": 1.6
    }
  ]
}

Bulk add or edit bid modifiers for an ad group
PUT/rest/v1/adgroups/{adGroupId}/bidmodifiers/

Use for adding or editing multiple bid modifiers at the same time.

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

DELETE https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "id": 1240
  },
  {
    "id": 1241
  }
]
Responses204
This response has no content.

Delete bid modifiers for an ad group
DELETE/rest/v1/adgroups/{adGroupId}/bidmodifiers/

A list of Bid Modifier IDs has to be included in request body to delete certain Bid Modifiers belonging to an Ad Group.

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

GET https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/1235
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "1235",
    "type": "DEVICE",
    "sourceSlug": "",
    "target": "MOBILE",
    "modifier": 0.99
  }
}

Get a bid modifier for an ad group
GET/rest/v1/adgroups/{adGroupId}/bidmodifiers/{bidModifierId}

URI Parameters
HideShow
adGroupId
string (required) Example: 2040
bidModifierId
string (required) Example: 1235

PUT https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/1235
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "modifier": 0.98
}
Responses200
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.

URI Parameters
HideShow
adGroupId
string (required) Example: 2040
bidModifierId
string (required) Example: 1235

DELETE https://oneapi.zemanta.com/rest/v1/adgroups/2040/bidmodifiers/1235
Responses204
This response has no content.

Delete a bid modifier for an ad group
DELETE/rest/v1/adgroups/{adGroupId}/bidmodifiers/{bidModifierId}

URI Parameters
HideShow
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
GET https://oneapi.zemanta.com/rest/v1/adgroups/2040/realtimestats/
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "spend": "1234.0000",
    "clicks": 4321
  }
}

Get real-time statistics for an ad group
GET/rest/v1/adgroups/{adGroupId}/realtimestats/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

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
POST https://oneapi.zemanta.com/rest/v1/creatives/batch/
Requestsexample 1
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
      }
    ]
  }
]
Responses201
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "1302",
    "status": "IN_PROGRESS",
    "validationStatus": [],
    "creatives": []
  }
}

Create a new creative batch
POST/rest/v1/creatives/batch/


GET https://oneapi.zemanta.com/rest/v1/creatives/batch/1302
Responses200
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
          }
        ]
      }
    ]
  }
}

Check creative batch status
GET/rest/v1/creatives/batch/{batchId}

URI Parameters
HideShow
batchId
string (required) Example: 1302

Manage creatives

GET https://oneapi.zemanta.com/rest/v1/creatives/?agencyId=&accountId=186&includeAudits=true&includeSources=true
Responses200
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}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID

includeAudits
boolean (optional) Default: false Example: true

Include Audits

includeSources
boolean (optional) Default: false Example: true

Include Sources


GET https://oneapi.zemanta.com/rest/v1/creatives/16805?includeAudits=true&includeSources=true
Responses200
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."
        ]
      }
    ]
  }
}

Get creative details
GET/rest/v1/creatives/{creativeId}{?includeAudits,includeSources}

URI Parameters
HideShow
creativeId
string (required) Example: 16805
includeAudits
boolean (optional) Default: false Example: true

Include Audits

includeSources
boolean (optional) Default: false Example: true

Include Sources


PUT https://oneapi.zemanta.com/rest/v1/creatives/16805
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "description": "My updated description"
}
Responses200
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
      }
    ]
  }
}

Edit a creative
PUT/rest/v1/creatives/{creativeId}

Note: At the moment only the url, displayUrl, brandName, description, callToAction, imageCrop, adTag, trackers and tags fields can be modified through the API.

URI Parameters
HideShow
creativeId
string (required) Example: 16805

POST https://oneapi.zemanta.com/rest/v1/creatives/
Requestsexample 1
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
    }
  ]
}
Responses201
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
      }
    ]
  }
}

Create a creative
POST/rest/v1/creatives/


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
POST https://oneapi.zemanta.com/rest/v1/videoassets/
Requestsexample 1example 2example 3
Headers
Content-Type: application/json
Body
{
  "name": "test_video.mp4",
  "accountId": "186",
  "upload": {
    "type": "DIRECT_UPLOAD"
  }
}
Responses200
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"
  }
}
Responses200
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"
}
Responses200
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).


GET https://oneapi.zemanta.com/rest/v1/videoassets/video_asset_id

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"
URI Parameters
HideShow
videoAssetId
string (required) Example: video_asset_id

GET https://oneapi.zemanta.com/rest/v1/videoassets/video_asset_id
Responses200200200
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).

URI Parameters
HideShow
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
GET https://oneapi.zemanta.com/rest/v1/measurement/services/123
Responses200
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"
  }
}

Get measurement service details
GET/rest/v1/measurement/services/{measurementServiceId}

URI Parameters
HideShow
measurementServiceId
string (required) Example: 123

PUT https://oneapi.zemanta.com/rest/v1/measurement/services/123
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Updated measurement service name"
}
Responses200
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"
  }
}

Edit a measurement service
PUT/rest/v1/measurement/services/{measurementServiceId}

URI Parameters
HideShow
measurementServiceId
string (required) Example: 123

POST https://oneapi.zemanta.com/rest/v1/measurement/services/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "New measurement service",
  "agencyId": null,
  "accountId": "186",
  "serviceType": "JS_TAG",
  "notes": "notes describing measurement service"
}
Responses201
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"
  }
}

Create a new measurement service
POST/rest/v1/measurement/services/


GET https://oneapi.zemanta.com/rest/v1/measurement/services/?agencyId=&accountId=186&keyword=new&serviceType=JS_TAG&offset=0&limit=50
Responses200
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}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID

keyword
string (optional) Example: new
serviceType
string (optional) Example: JS_TAG
offset
int (optional) Default: 0 Example: 0

based starting index

limit
int (optional) Default: 10 Example: 50

Maximum 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
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
GET https://oneapi.zemanta.com/rest/v1/measurement/conversiondefinitions/223
Responses200
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",
    "attributionModelType": "FIRST",
    "attributionModelCount": "EVERY",
    "clickConversionWindow": 7,
    "viewConversionWindow": 1,
    "conversionTriggerType": "CODE",
    "measurementMatchingRules": [],
    "lastTriggered": "2021-11-18T11:54:44.217697",
    "recentTraffic": "679"
  }
}

Get conversion definition details
GET/rest/v1/measurement/conversiondefinitions/{conversionDefinitionId}

URI Parameters
HideShow
conversionDefinitionId
string (required) Example: 223

PUT https://oneapi.zemanta.com/rest/v1/measurement/conversiondefinitions/223
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Updated conversion definition name",
  "accountId": "186"
}
Responses200
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",
    "attributionModelType": "FIRST",
    "attributionModelCount": "EVERY",
    "clickConversionWindow": 7,
    "viewConversionWindow": 1,
    "conversionTriggerType": "CODE",
    "measurementMatchingRules": [],
    "lastTriggered": "2021-11-18T11:54:44.217697",
    "recentTraffic": "679"
  }
}

Edit a conversion definition
PUT/rest/v1/measurement/conversiondefinitions/{conversionDefinitionId}

URI Parameters
HideShow
conversionDefinitionId
string (required) Example: 223

POST https://oneapi.zemanta.com/rest/v1/measurement/conversiondefinitions/
Requestsexample 1
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",
  "attributionModelType": "FIRST",
  "attributionModelCount": "EVERY",
  "clickConversionWindow": 7,
  "viewConversionWindow": 1,
  "conversionTriggerType": "CODE",
  "measurementMatchingRules": []
}
Responses201
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",
    "attributionModelType": "FIRST",
    "attributionModelCount": "EVERY",
    "clickConversionWindow": 7,
    "viewConversionWindow": 1,
    "conversionTriggerType": "CODE",
    "measurementMatchingRules": [],
    "lastTriggered": null,
    "recentTraffic": "0"
  }
}

Create a new conversion definition
POST/rest/v1/measurement/conversiondefinitions/


GET https://oneapi.zemanta.com/rest/v1/measurement/conversiondefinitions/?agencyId=&accountId=186&keyword=new&offset=0&limit=50
Responses200
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",
      "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}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID

keyword
string (optional) Example: new
offset
int (optional) Default: 0 Example: 0

based starting index

limit
int (optional) Default: 10 Example: 50

Maximum 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
GET https://oneapi.zemanta.com/rest/v1/measurement/audiences/234
Responses200
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
  }
}

Get audience details
GET/rest/v1/measurement/audiences/{audienceId}

URI Parameters
HideShow
audienceId
string (required) Example: 234

PUT https://oneapi.zemanta.com/rest/v1/measurement/audiences/234
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "updated_audience"
}
Responses200
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"
      }
    ]
  }
}

Update audience
PUT/rest/v1/measurement/audiences/{audienceId}

URI Parameters
HideShow
audienceId
string (required) Example: 234

GET https://oneapi.zemanta.com/rest/v1/measurement/audiences/?agencyId=&accountId=186&keyword=updated&limit=50&offset=0
Responses200
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}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID

keyword
string (optional) Example: updated
offset
int (optional) Default: 0 Example: 0

based starting index

limit
int (optional) Default: 10 Example: 50

Maximum number of entries to return, up to 50


POST https://oneapi.zemanta.com/rest/v1/measurement/audiences/
Requestsexample 1
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"
    }
  ]
}
Responses201
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"
      }
    ]
  }
}

Create new audience
POST/rest/v1/measurement/audiences/


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
GET https://oneapi.zemanta.com/rest/v1/accounts/186/publishergroups/
Responses200
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": "111",
      "accountId": "186",
      "name": "Default include list"
    }
  ]
}

List publisher groups
GET/rest/v1/accounts/{accountId}/publishergroups/

URI Parameters
HideShow
accountId
string (required) Example: 186

POST https://oneapi.zemanta.com/rest/v1/accounts/186/publishergroups/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Secondary include list"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "153",
    "accountId": "186",
    "name": "Secondary include list"
  }
}

Create a new publisher group
POST/rest/v1/accounts/{accountId}/publishergroups/

URI Parameters
HideShow
accountId
string (required) Example: 186

GET https://oneapi.zemanta.com/rest/v1/accounts/186/publishergroups/153
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "153",
    "accountId": "186",
    "name": "Secondary include list"
  }
}

Get publisher group details
GET/rest/v1/accounts/{accountId}/publishergroups/{publisherGroupId}

URI Parameters
HideShow
accountId
string (required) Example: 186
publisherGroupId
string (required) Example: 153

PUT https://oneapi.zemanta.com/rest/v1/accounts/186/publishergroups/153
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Mobile campaigns exclude list"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "153",
    "accountId": "186",
    "name": "Mobile campaigns exclude list"
  }
}

Edit a publisher group
PUT/rest/v1/accounts/{accountId}/publishergroups/{publisherGroupId}

URI Parameters
HideShow
accountId
string (required) Example: 186
publisherGroupId
string (required) Example: 153

DELETE https://oneapi.zemanta.com/rest/v1/accounts/186/publishergroups/155
Responses204
This response has no content.

Delete a publisher group
DELETE/rest/v1/accounts/{accountId}/publishergroups/{publisherGroupId}

Publisher groups can be deleted when they are not referenced by any Ad Group.

URI Parameters
HideShow
accountId
string (required) Example: 186
publisherGroupId
string (required) Example: 155

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
GET https://oneapi.zemanta.com/rest/v1/publishergroups/157/entries/?offset=0&limit=100
Responses200
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}

URI Parameters
HideShow
publisherGroupId
string (required) Example: 157
offset
int (optional) Example: 0

0-based starting index

limit
int (required) Default: 100 Example: 100

Maximum number of entries to return, up to 1000


POST https://oneapi.zemanta.com/rest/v1/publishergroups/157/entries/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "publisherGroupId": "157",
    "publisher": "example.com",
    "source": "triplelift"
  },
  {
    "publisherGroupId": "157",
    "publisher": "example.com",
    "source": "yahoo"
  }
]
Responses201
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"
    }
  ]
}

Create new publisher group entries
POST/rest/v1/publishergroups/{publisherGroupId}/entries/

This endpoint supports creating multiple entries at once that are all appended to the same publisher group.

URI Parameters
HideShow
publisherGroupId
string (required) Example: 157

GET https://oneapi.zemanta.com/rest/v1/publishergroups/157/entries/625
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "625",
    "publisherGroupId": "157",
    "publisher": "example.com",
    "source": "yahoo"
  }
}

Get a publisher group entry
GET/rest/v1/publishergroups/{publisherGroupId}/entries/{entryId}

URI Parameters
HideShow
publisherGroupId
string (required) Example: 157
entryId
string (required) Example: 625

PUT https://oneapi.zemanta.com/rest/v1/publishergroups/157/entries/625
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "publisher": "example.com",
  "source": "yahoo"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "625",
    "publisherGroupId": "157",
    "publisher": "example.com",
    "source": "yahoo"
  }
}

Edit a publisher group entry
PUT/rest/v1/publishergroups/{publisherGroupId}/entries/{entryId}

URI Parameters
HideShow
publisherGroupId
string (required) Example: 157
entryId
string (required) Example: 625

DELETE https://oneapi.zemanta.com/rest/v1/publishergroups/157/entries/625
Responses204
This response has no content.

Delete a publisher group entry
DELETE/rest/v1/publishergroups/{publisherGroupId}/entries/{entryId}

URI Parameters
HideShow
publisherGroupId
string (required) Example: 157
entryId
string (required) Example: 625

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
GET https://oneapi.zemanta.com/rest/v1/adgroups/2040/publishers/
Responses200
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"
    }
  ]
}

Get publisher status
GET/rest/v1/adgroups/{adGroupId}/publishers/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

PUT https://oneapi.zemanta.com/rest/v1/adgroups/2040/publishers/
Requestsexample 1
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"
  }
]
Responses200
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"
    }
  ]
}

Set publisher status
PUT/rest/v1/adgroups/{adGroupId}/publishers/

URI Parameters
HideShow
adGroupId
string (required) Example: 2040

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
GET https://oneapi.zemanta.com/rest/v1/deals/?agencyId=&accountId=186
Responses200
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]"
    }
  ]
}

List deals
GET/rest/v1/deals/{?agencyId,accountId}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID


GET https://oneapi.zemanta.com/rest/v1/deals/123
Responses200
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]"
  }
}

Get deal details
GET/rest/v1/deals/{id}

URI Parameters
HideShow
id
string (required) Example: 123

PUT https://oneapi.zemanta.com/rest/v1/deals/123
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "accountId": "186",
  "description": "My updated description"
}
Responses200
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]"
  }
}

Edit a deal
PUT/rest/v1/deals/{id}

URI Parameters
HideShow
id
string (required) Example: 123

POST https://oneapi.zemanta.com/rest/v1/deals/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "dealId": "77766X123",
  "name": "Deal with ID 77766X123",
  "accountId": "186",
  "source": "gumgum"
}
Responses201
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]"
  }
}

Create a deal
POST/rest/v1/deals/


DELETE https://oneapi.zemanta.com/rest/v1/deals/124
Responses204
This response has no content.

Delete a deal
DELETE/rest/v1/deals/{id}

URI Parameters
HideShow
id
string (required) Example: 124

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

Deal Entity

Property Type Description
id string ID of the connected entity
name string Name of the connected entity
GET https://oneapi.zemanta.com/rest/v1/deals/123/connections/
Responses200
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": {}
    }
  ]
}

List connections of a deal
GET/rest/v1/deals/{id}/connections/

URI Parameters
HideShow
id
string (required) Example: 123

DELETE https://oneapi.zemanta.com/rest/v1/deals/123/connections/223
Responses204
This response has no content.

Remove a connection from a deal
DELETE/rest/v1/deals/{id}/connections/{connectionId}

URI Parameters
HideShow
id
string (required) Example: 123
connectionId
string (required) Example: 223

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)
GET https://oneapi.zemanta.com/rest/v1/lists/keyword/?agencyId=&accountId=186

List keyword lists
GET/rest/v1/lists/keyword/{?agencyId,accountId}

URI Parameters
HideShow
agencyId
number (optional) 

Agency ID

accountId
number (optional) Example: 186

Account ID


POST https://oneapi.zemanta.com/rest/v1/lists/keyword/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "An agency-scoped keyword list",
  "agencyId": "1"
}
Responses201
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"
  }
}

Create keyword list
POST/rest/v1/lists/keyword/


PUT https://oneapi.zemanta.com/rest/v1/lists/keyword/123
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "An agency-scoped keyword list",
  "agencyId": "1"
}
Responses200
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"
  }
}

Edit keyword list
PUT/rest/v1/lists/keyword/{listId}

URI Parameters
HideShow
listId
string (required) Example: 123

DELETE https://oneapi.zemanta.com/rest/v1/lists/keyword/125
Responses204
This response has no content.

Delete keyword list
DELETE/rest/v1/lists/keyword/{listId}

URI Parameters
HideShow
listId
string (required) Example: 125

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)
GET https://oneapi.zemanta.com/rest/v1/lists/keyword/123/entries/

List entries of a keyword list
GET/rest/v1/lists/keyword/{listId}/entries/

URI Parameters
HideShow
listId
string (required) Example: 123

POST https://oneapi.zemanta.com/rest/v1/lists/keyword/123/entries/
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "keyword": "Cat"
  },
  {
    "keyword": "Dog"
  },
  {
    "keyword": "Llama"
  }
]
Responses201
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"
    }
  ]
}

Add entries to a keyword list
POST/rest/v1/lists/keyword/{listId}/entries/

URI Parameters
HideShow
listId
string (required) Example: 123

DELETE https://oneapi.zemanta.com/rest/v1/lists/keyword/123/entries/983423
Responses204
This response has no content.

Remove an entry from a keyword list
DELETE/rest/v1/lists/keyword/{listId}/entries/{entryId}

URI Parameters
HideShow
listId
string (required) Example: 123
entryId
string (required) Example: 983423

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
GET https://oneapi.zemanta.com/rest/v1/lists/keyword/123/connections/
Responses200
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"
    }
  ]
}

List connections of a keyword list
GET/rest/v1/lists/keyword/{listId}/connections/

URI Parameters
HideShow
listId
string (required) Example: 123

DELETE https://oneapi.zemanta.com/rest/v1/lists/keyword/123/connections/769733
Responses204
This response has no content.

Remove a connection from a keyword list
DELETE/rest/v1/lists/keyword/{listId}/connections/{connectionId}

URI Parameters
HideShow
listId
string (required) Example: 123
connectionId
string (required) Example: 769733

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 - CPA
    • ROAS - ROAS
  • Conversion definition name

  • Attribution type:

    • - Click attr. - click attribution
    • - View attr. - view attribution

Report jobs

POST https://oneapi.zemanta.com/rest/v1/reports/
Requestsexample 1
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"
    }
  ]
}
Responses201
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "27",
    "status": "IN_PROGRESS",
    "result": null
  }
}

Create a new report job
POST/rest/v1/reports/


GET https://oneapi.zemanta.com/rest/v1/reports/27
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": "27",
    "status": "DONE",
    "result": "https://z1-rest-reports.s3.amazonaws.com/KgrK55qCMO85v9JhHwCIv8kso2quYwEGV2MLpiVUgDVRDJm3HiGk1lWrOGfxJ7k2.csv"
  }
}

Get report job status
GET/rest/v1/reports/{jobId}

URI Parameters
HideShow
jobId
string (required) Example: 27

Books closed

GET https://oneapi.zemanta.com/rest/v1/booksclosed/
Responses200
Headers
Content-Type: application/json
Body
{
  "data": {
    "trafficData": {
      "latestCompleteDate": "2020-11-16"
    }
  }
}

Get latest date with complete data
GET/rest/v1/booksclosed/

Get the latest date for which we have complete traffic data available (e.g. spend, clicks, impressions). Postclick data (e.g. Google Analytics, Omniture) might be complete at a later time.


Real-time Reporting

Real-time Reporting

GET https://oneapi.zemanta.com/rest/v1/realtimestats/?breakdown=campaignId&marker=0&limit=100&accountId=186&campaignId=&adGroupId=&contentAdId=
Responses200
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

URI Parameters
HideShow
breakdown
string (required) Example: campaignId

Valid choices are campaignId, adGroupId, contentAdId

marker
integer (optional) Example: 0

the primary key of the last element in the previous page (the first page has marker=0)

limit
integer (optional) Default: 100 Example: 100

Maximum number of entries to return, up to 1000

accountId
integer (optional) Example: 186

Optional account ID

campaignId
integer (optional) 

Optional campaign ID

adGroupId
integer (optional) 

Optional ad group ID

contentAdId
integer (optional) 

Optional content ad ID


Utilities

Geolocations

GET https://oneapi.zemanta.com/rest/v1/geolocations/?keys=US,US-HI&types=COUNTRY,REGION&nameContains=United&limit=10&offset=0
Responses200
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}

URI Parameters
HideShow
keys
string (optional) Example: US,US-HI

Comma-separated list of location keys

types
string (optional) Example: COUNTRY,REGION

Comma-separated list of location types

nameContains
string (optional) Example: United

Search query

limit
int (optional) Default: 10 Example: 10

Maximum number of locations to return, up to 50

offset
int (optional) Example: 0

0-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.

GET https://oneapi.zemanta.com/rest/v1/dmp/category/
Responses200
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": []
        }
      ]
    }
  ]
}

List DMP Categories
GET/rest/v1/dmp/category/

URI Parameters
HideShow
type
string (required) Example: OUTBRAIN_INTEREST

Dmp type


Sources

GET https://oneapi.zemanta.com/rest/v1/sources/?limit=100&offset=0
Responses200
Headers
Content-Type: application/json
Body
{
  "slug": "outbrainrtb",
  "name": "Outbrain RTB",
  "auditors": [
    "OUTBRAIN"
  ]
}

List sources
GET/rest/v1/sources/{?limit,offset}

URI Parameters
HideShow
limit
int (optional) Example: 100

Maximum number of sources to return

offset
int (optional) Example: 0

0-based starting index


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 playback method option

  • PAGE_LOAD_SOUND_ON - PAGE_LOAD_SOUND_ON

  • PAGE_LOAD_SOUND_OFF - PAGE_LOAD_SOUND_OFF

  • ON_CLICK_SOUND_ON - ON_CLICK_SOUND_ON

  • ON_MOUSE_OVER_SOUND_ON - ON_MOUSE_OVER_SOUND_ON

  • ON_VIEWPORT_ENTER_SOUND_ON - ON_VIEWPORT_ENTER_SOUND_ON

  • ON_VIEWPORT_ENTER_SOUND_OFF - ON_VIEWPORT_ENTER_SOUND_OFF

Video player size option

  • SMALL - SMALL

  • MEDIUM - MEDIUM

  • LARGE - LARGE

Video rewarded options

  • ALLOW - Allow

  • REQUIRE - Require

  • BLOCK - Block

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 05 Dec 2024