APIZemanta API
API Endpoint
https://oneapi.zemanta.comThis document describes the Zemanta One REST Campaign Management API.
The API enables Zemanta clients to programatically create and manage campaigns, ad groups and content ads using RESTful objects. Custom performance reports are also available as part of the API.
In order to use Zemanta REST API, please contact your sales representative.
Who should read this document?
This document is inteded for programmers who are developing an integration with the Zemanta One system. A prerequisite for working with Zemanta REST API is an understanding of HTTP and JSON.
Technical Overview ¶
Entities
The diagram and the table below describe the objects this API deals with and the relationships between them.
| Entity | Description | Functionality |
|---|---|---|
| Account | Zemanta One 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 Content Ads | Read, Create, Update |
| Content Ad | 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
HTTP Response Status Codes
| Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | The request was successful |
| 201 | Created | Entity successfuly 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
Zemanta One API paginates list views using marker offset pagination by default.
By specifying the offset URL query parameter it is possible to use a simple limit offset pagination which might lead to slow responses with large lists.
Marker Offset Pagination
The format for marker offset pagination URL is:
/rest/v1/{resourceListPath}/{?marker,limit}
Navigation through pages is done by two URL parameters:
-
marker: the primary key of the last element in the previous page (the first page hasmarker=0) -
limit: maximum number of entries to return, up to1000, defaults to100
The response has the following content:
{
"count": 1000,
"next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?marker=200&limit=100",
"data": []
}Limit Offset Pagination
The format for limit offset pagination URL is:
/rest/v1/{resourceListPath}/?offset{,limit}Navigation through pages is done by two URL parameters:
-
offset: the offset of starting element of the page in the list -
limit: maximum number of entries to return, up to1000, defaults to100
The response has the following content:
{
"count": 1000,
"next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=200&limit=100",
"previous": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=100&limit=100",
"data": []
}Rate Limiting
Each Zemanta One user can perform a maximum of 20 requests per second to the Zemanta One API. In case that limit is crossed, the API will start responding with HTTP status 429 (Too Many Requests).
Authentication
Zemanta 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 Zemanta One. Then go to https://one.zemanta.com/o/applications/ and click the New Application button. Enter a name for your application, as shown in the image, and click the “Save” button.
After you click the “Save” button, you will see the details of your newly created application credentials. The provided Client ID and Client Secret are used for API authentication.
Acquire a new authentication token ¶
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WkNTeDJXanhIeHhWNnJLWkMzaGRiNmVqTzhHTHdjZFV0bHRtcHQ5Sjp1N3BsRWQwNG1IYzExQ2NrUzlkb2poWWl3YVd6TnFlQjF3OUtnTXh3ZTVya1c2U3M3bVRSSXg2UGQ4dDdZdmRZYzdiQzEwMjVINzRzOThFMmVxaEljQmx2QmxIc2M1dkFwOVRKTVAyZTh5Nmt5SktRVVdrcFVpckZSbDNPczJmQw==Body
grant_type=client_credentialsHeaders
Content-Type: application/jsonBody
{
"access_token": "UUjXNkJDyLVjDzswOjdVm0ySIBYfp7",
"token_type": "Bearer",
"expires_in": 36000,
"scope": "read write"
}Account Management ¶
Accounts ¶
| Property | Type | Description | Create | Update |
|---|---|---|---|---|
| id | string | the account’s id | N/A | read only |
| agencyId | string | the agency’s id | required | read only |
| name | string | the name of the account | required | optional |
| archived | bool | Is the account archived? Set to true to archive an account and to false to restore it. |
optional | optional |
| targeting | targeting | account targeting settings | optional | optional |
| currency | Currency | the account’s currency (default is USD) | optional | N\A |
| frequencyCapping | number | The maximum number of times ads from the account can be shown to a unique user in one day. | optional | optional |
Account Targeting Settings
| Targeting | Property | Property | Type | Description |
|---|---|---|---|---|
| publisherGroups | ||||
| included | array[publisherGroupId] | whitelisted publisher group IDs | ||
| excluded | array[publisherGroupId] | blacklisted publisher group IDs |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
]
}Headers
Content-Type: application/jsonBody
{
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"agencyId": "1"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "186",
"agencyId": "1",
"name": "My Account 1",
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Account Credit ¶
After your Insertion Order for media spend has been executed Zemanta’s Customer Success team will assign a credit line to your account. With credit added to your account you have the ability to create budget items and associate them with the campaigns you’re planning.
| Property | Type | Description |
|---|---|---|
| id | string | the credit item’s id |
| startDate | date | start date of the credit |
| endDate | date | end date of the credit |
| total | money | total credit amount |
| allocated | money | amount already allocated to campaign budgets |
| available | money | amount still available for allocation |
| currency | Currency | the credit’s currency |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "861",
"startDate": "2016-01-01",
"endDate": "2016-11-05",
"createdOn": "2014-06-04",
"total": "1000.0000",
"allocated": "400.0000",
"available": "600.0000",
"currency": "EUR"
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "861",
"startDate": "2016-01-01",
"endDate": "2016-11-05",
"createdOn": "2014-06-04",
"total": "1000.0000",
"allocated": "400.0000",
"available": "600.0000",
"currency": "EUR"
}
]
}Pixels ¶
Zemanta’s pixels allow you to report conversions, build audiences and get insights about how people use your website. Pixels need to be properly placed in order to measure goals effectively. We recommend placing your pixel on the confirmation page which is shown to a person after the desired action is performed.
| Property | Type | Description | Create | Update |
|---|---|---|---|---|
| id | string | ID of the pixel | N/A | read only |
| accountId | string | ID of the account | read only | read only |
| name | string | name of the pixel | required | read only |
| archived | bool | Is the pixel archived? Set to true to archive a pixel and to false to restore it. |
optional | optional |
| audienceEnabled | bool | Is the pixel used for building custom audiences? Set to true to enable it. Can not be disabled once enabled. Only one pixel can be used for building custom audiences. |
optional | optional |
| url | string | URL of the pixel | read only | read only |
| notes | string | a note describing where the pixel is placed on your website and what it tracks | optional | optional |
| lastTriggered | date | date of when the pixel was last triggered | read only | read only |
| impressions | number | number of times the pixel was triggered yesterday | read only | read only |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "123",
"accountId": "186",
"name": "audience_pixel",
"archived": false,
"audienceEnabled": false,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
}Headers
Content-Type: application/jsonBody
{
"archived": false,
"audienceEnabled": true,
"notes": "pixel used for audience testing"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "123",
"accountId": "186",
"name": "audience_pixel",
"archived": false,
"audienceEnabled": true,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for audience testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "123",
"accountId": "186",
"name": "test_pixel",
"archived": false,
"audienceEnabled": false,
"url": "https://p1.zemanta.com/p/186/123/",
"notes": "pixel used for testing",
"lastTriggered": "2019-01-01T12:00:00.000000",
"impressions": 100
}
]
}Headers
Content-Type: application/jsonBody
{
"name": "test_pixel",
"archived": false,
"audienceEnabled": false,
"notes": "pixel used for testing"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "124",
"accountId": "186",
"name": "test_pixel",
"archived": false,
"audienceEnabled": false,
"url": "https://p1.zemanta.com/p/186/124/",
"notes": "pixel used for testing",
"lastTriggered": null,
"impressions": 0
}
}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 |
| pixelId | string | ID of the pixel that is the source of this traffic | required | read only |
| name | string | name of the audience | required | optional |
| archived | bool | Is the audience archived? Set to true to archive an audience and to false to restore it. |
optional | optional |
| ttl | number | The number of days people will remain in your audience after they’ve visited your website. People will be removed from your audience after the set time period unless they visit your website again. | required | read only |
| rules | audience rule | Include traffic that meets the specified conditions. | required | read only |
| createdDt | date | audience creation date | read only | read only |
Audience Rules
Choose how you want to add people to your audience. Include all of your website visitors or create rules that only add people visiting specific parts of your website. Audience can have multiple rules set. CONTAINS and STARTS_WITH rules can match multiple values separated by a comma. STARTS_WITH values need to be valid URLs.
| Property | Type | Description | Create | Create (VISIT) |
Update |
|---|---|---|---|---|---|
| type | enum | rule type | required | required | read only |
| value | string | rule value | required | N/A | read only |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "234",
"pixelId": "123",
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}Headers
Content-Type: application/jsonBody
{
"name": "new_audience",
"archived": false
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "234",
"pixelId": "123",
"name": "new_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "CONTAINS",
"value": "these,are,all"
},
{
"type": "CONTAINS",
"value": "test,tags"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "234",
"pixelId": "123",
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "STARTS_WITH",
"value": "http://test.com,https://urls.com"
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
]
}Headers
Content-Type: application/jsonBody
{
"pixelId": 123,
"name": "test_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "VISIT"
}
]
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "234",
"pixelId": "123",
"name": "new_audience",
"archived": false,
"ttl": 7,
"rules": [
{
"type": "VISIT",
"value": ""
}
],
"createdDt": "2019-01-01T12:00:00.000000"
}
}Campaign Management ¶
Campaigns ¶
A Campaign is a collection of Ad Groups. It holds common settings for all Ad Groups and also has budgets and goals associated.
| Property | Type | Description | Create | Update |
|---|---|---|---|---|
| id | string | the campaign’s id | N/A | read only |
| accountId | string | id of the account this campaign belongs to | required | read only |
| name | string | the name of the campaign | required | optional |
| 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. Read more. | 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 |
Tracking Settings
Postclick tracking integration can be set up for Google Analytics and Adobe Analytics.
| Tracking | Property | Type | Description |
|---|---|---|---|
| ga | |||
| enabled | boolean | Google Analytics integration enabled | |
| type | GA Tracking Type | Google Analytics tracking type | |
| webProperyId | 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 |
|---|---|---|---|---|
| devices | array[device] | A list of default device types that will be set on newly created ad groups. | ||
| placements | array[placement] | A list of default placements that will be set on newly created ad groups. | ||
| os | array[operatingSystem | A list of default operating systems and operating system versions that will be se on newly created ad groups. | ||
| publisherGroups | ||||
| included | array[publisherGroupId] | whitelisted publisher group IDs | ||
| excluded | array[publisherGroupId] | blacklisted publisher group IDs |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "608",
"accountId": "186",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "608",
"accountId": "186",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "608",
"accountId": "186",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
]
}Headers
Content-Type: application/jsonBody
{
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10,
"accountId": "186"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "608",
"accountId": "186",
"name": "My Campaign 1",
"archived": false,
"iabCategory": "IAB1_1",
"tracking": {
"ga": {
"enabled": true,
"type": "API",
"webPropertyId": "UA-123456789-1"
},
"adobe": {
"enabled": true,
"trackingParameter": "cid"
}
},
"targeting": {
"publisherGroups": {
"included": [
"153"
],
"excluded": [
"154"
]
}
},
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"totalCost": "2240.56",
"impressions": 4146083,
"clicks": 14621,
"cpc": "0.130"
}
}Get campaign performance ¶GET/rest/v1/campaigns/{campaignId}/stats/{?from,to}
This endpoint allows you to quickly view the performance of the campaign in a time span.
For more detailed reports, please use the Reporting endpoints.
- campaignId
string(required) Example: 608- from
string(required) Example: 2016-11-18- to
string(required) Example: 2016-11-18
Campaign Budgets ¶
Each budget item is part of a Credit Item and allows a campaign to spend a portion of the credit.
A campaign needs at least one active budget associated with it before its Ad Groups can be started.
More info available here.
| Property | Type | Description | Create | Update |
|---|---|---|---|---|
| id | string | the budget’id | N/A | read only |
| creditId | string | id of the credit this budget is part of | required | read only |
| amount | money | total amount allocated by the budget | required | optional |
| margin | string (decimal) | margin percentage fraction (e.g. 0.1) | optional | optional |
| comment | string | free-form text field | optional | optional |
| startDate | date | budget start date, must be in the future | required | optional |
| endDate | date | budget end date, must end before the credit ends | required | optional |
| state | string | budget state, ACTIVE / PENDING / INACTIVE / DEPLETED | N/A | read only |
| spend | money | the amount of the budget already spent | N/A | read only |
| available | money | the amount of the budget still available | N/A | read only |
Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "1910",
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
]
}Headers
Content-Type: application/jsonBody
{
"creditId": "861",
"amount": "600",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1911",
"amount": "600",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "600.0000"
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1910",
"creditId": "861",
"amount": "400",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "400.0000"
}
}Headers
Content-Type: application/jsonBody
{
"amount": "800"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1911",
"creditId": "861",
"amount": "800",
"margin": "0.1",
"comment": "my budget",
"startDate": "2016-01-01",
"endDate": "2016-01-31",
"state": "ACTIVE",
"spend": "0.0000",
"available": "800.0000"
}
}Campaign goals ¶
Campaign goals give Zemanta’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 |
| conversionWindow | enum | conversion goal type | required | required | read only |
| goalId | string | goal id | N/A | required | read only |
| pixelUrl | url | pixel url, if applicable | N/A | N/A | read only |
Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "1238",
"type": "TIME_ON_SITE",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"name": "My conversion goal",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "mygoal",
"pixelUrl": "http://example.com/mypixel1"
}
}
]
}Headers
Content-Type: application/jsonBody
{
"type": "CPA",
"value": "30.0",
"primary": false,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "mygoal",
"pixelUrl": "http://example.com/mypixel1"
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1239",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "mygoal",
"pixelUrl": "http://example.com/mypixel1"
}
}
}Headers
Content-Type: application/jsonBody
{
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "101"
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1234",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "PIXEL",
"name": "My pixel",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "101",
"pixelUrl": "https://p1.zemanta.com/p/1/4321/"
}
}
}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://one.zemanta.com/v2/pixels/account/<accountId>) by clicking the Copy Tag button.
Inside the tag you will find a URL of form https://p1.zemanta.com/p/<accountId>/<pixelId>/.
Use the pixelId number when creating a new pixel (see example 2).
- campaignId
string(required) Example: 608
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1239",
"type": "CPA",
"value": "30.0",
"primary": true,
"conversionGoal": {
"type": "GA",
"name": "My conversion goal 2",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "mygoal",
"pixelUrl": "http://example.com/mypixel1"
}
}
}Headers
Content-Type: application/jsonBody
{
"primary": true
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1238",
"type": "CPA",
"primary": false,
"conversionGoal": {
"type": "PIXEL",
"name": "My conversion goal",
"conversionWindow": "LEQ_7_DAYS",
"goalId": "mygoal",
"pixelUrl": "http://example.com/mypixel1"
}
}
}Ad Group Management ¶
Ad Groups ¶
An Ad Group is a collection of Content 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 |
| startDate | string | start date of the ad group | optional | optional |
| biddingType | CPC / CPM |
Bidding type. Set to CPC (use maxCpc) to focus on the clicks that your ad receives or CPM (use maxCpm) to focus on impressions. |
optional | optional |
| maxCpc | money | maximum CPC for this ad group | optional | optional |
| maxCpm | money | maximum CPM for this ad group (currently beta only, please contact us for access) | optional | optional |
| targeting | targeting | targeting settings | optional | optional |
| dayparting | dayparting | dayparting settings | optional | optional |
| trackingCode | string | tracking codes appended to all content ads URLs (more) | optional | optional |
| autopilot | autopilot | Zemanta 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 Zemanta hits the maximum number of clicks you set it will stop spending for the rest of the day. | optional | optional |
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. | ||
| placements | array[placement] | A list of placements to target. If none specified, content is served to all placements. | ||
| 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 | ||||
| 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 | ||||
| included | array[interestCategory] | interest categories to target | ||
| excluded | array[interestCategory] | interest categories to avoid | ||
| publisherGroups | ||||
| included | array[publisherGroupId] | whitelisted publisher group IDs | ||
| excluded | array[publisherGroupId] | blacklisted 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 |
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. |
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": "bluekai:839868"
},
{
"category": "bluekai:763921"
}
]
},
{
"NOT": [
{
"category": "bluekai: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. bluekai:671901) |
Currently the only supported provider is bluekai. See BlueKai Taxonomy API for a list of all available
BlueKai categories.
Zemanta Autopilot Settings
Get more information about Zemanta Autopilot in our knowledge base.
In order to set Autopilot state to ACTIVE_CPC_BUDGET all real-time bidding sources
groupEnabled setting has to be set to true.
| Property | Type | Description |
|---|---|---|
| state | autopilot state | autopilot state |
| dailyBudget | dailyBudget | autopilot daily budget |
Headers
Content-Type: application/jsonBody
{
"data": {
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
}Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
]
}Headers
Content-Type: application/jsonBody
{
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "2040",
"campaignId": "608",
"name": "My ad group 1",
"state": "INACTIVE",
"archived": false,
"startDate": "2016-10-05",
"endDate": "2116-11-05",
"bidding_type": "CPC",
"maxCpc": "0.25",
"maxCpm": "",
"dailyBudget": "20.0",
"targeting": {
"devices": [
"DESKTOP",
"MOBILE"
],
"placements": [
"SITE",
"APP"
],
"os": [
{
"name": "ANDROID",
"version": {
"min": "ANDROID_6_0",
"max": "ANDROID_7_1"
}
}
],
"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": "bluekai:21230"
}
]
},
"customAudiences": {
"included": [
"123"
],
"excluded": [
"124"
]
},
"retargetingAdGroups": {
"included": [
"2050"
],
"excluded": [
"2051"
]
}
},
"trackingCode": "this=1&that=2",
"autopilot": {
"state": "ACTIVE_CPC",
"dailyBudget": "100.0001"
},
"dayparting": {
"monday": [
0,
1,
2,
3
],
"friday": [
20,
21,
22,
23
],
"timezone": "America/New_York"
},
"deliveryType": "STANDARD",
"frequencyCapping": 10
}
}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 |
| cpc | money | CPC for the given source |
| cpm | money | CPM for the given source (when ad group biddingType is CPM) |
| dailyBudget | money | daily budget for the given source |
Headers
Content-Type: application/jsonBody
{
"data": [
{
"source": "yahoo",
"state": "ACTIVE",
"cpc": "0.20",
"cpm": null,
"dailyBudget": "10.0"
},
{
"source": "gumgum",
"state": "ACTIVE",
"cpc": "0.20",
"cpm": null,
"dailyBudget": "10.0"
},
{
"source": "triplelift",
"state": "ACTIVE",
"cpc": "0.20",
"cpm": null,
"dailyBudget": "10.0"
}
]
}Headers
Content-Type: application/jsonBody
[
{
"source": "gumgum",
"dailyBudget": "15.0",
"cpc": "0.25"
},
{
"source": "triplelift",
"state": "INACTIVE"
}
]Headers
Content-Type: application/jsonBody
{
"data": [
{
"source": "yahoo",
"state": "ACTIVE",
"cpc": "0.20",
"cpm": null,
"dailyBudget": "10.0"
},
{
"source": "gumgum",
"state": "ACTIVE",
"cpc": "0.25",
"cpm": null,
"dailyBudget": "15.0"
},
{
"source": "triplelift",
"state": "INACTIVE",
"cpc": "0.20",
"cpm": null,
"dailyBudget": "10.0"
}
]
}Headers
Content-Type: application/jsonBody
{
"source": "adiant",
"state": "ACTIVE",
"dailyBudget": "15.0",
"cpc": "0.25"
}Headers
Content-Type: application/jsonBody
{
"data": {
"source": "adiant",
"state": "ACTIVE",
"cpc": "0.25",
"cpm": null,
"dailyBudget": "15.0"
}
}All Real-time bidding sources as one ¶
The sources you can promote your content on come in two flavours: real-time
bidding (RTB) and non-real-time bidding (Non-RTB) sources. RTB sources are all
sources except yahoo, outbrain, instagram and facebook.
In order to simplify manual source management (when not using Zemanta Autopilot), you can use this special RTB settings endpoint, which allows you to group all RTB sources together and treat them as a single source. This allows you to set the state and daily budget of all RTB sources at once. The daily budget set by this endpoint will be shared among all RTB sources.
This setting has to be enabled in order to be able to set autopilot
state to ACTIVE_CPC_BUDGET.
| Property | Type | Description |
|---|---|---|
| groupEnabled | boolean | enable or disable treating all RTB sources as a single source |
| state | ACTIVE/INACTIVE |
the state of all RTB sources |
| cpc | money | CPC for all RTB sources |
| cpm | money | CPM for all RTB sources (when ad group biddingType is CPM) |
| dailyBudget | money | daily budget shared among all RTB sources |
Headers
Content-Type: application/jsonBody
{
"data": {
"groupEnabled": true,
"state": "ACTIVE",
"cpc": "0.25",
"cpm": null,
"dailyBudget": "50.00"
}
}Headers
Content-Type: application/jsonBody
{
"groupEnabled": true,
"state": "ACTIVE",
"dailyBudget": "40.00"
}Headers
Content-Type: application/jsonBody
{
"data": {
"groupEnabled": true,
"state": "ACTIVE",
"dailyBudget": "40.00"
}
}Bid Modifiers ¶
| 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 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 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.
Bid Modifier Types
The following bid modifier types are supported:
| Type | Description | Allowed Values |
|---|---|---|
| PUBLISHER | Modifies the bidding price for a specific source at a specific publisher. | the domain name of the publisher |
| SOURCE | Modifies the bidding price for a specific source. | the ID of the source as a string |
| 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 |
| PLACEMENT | Modifies the bidding price for a specific add placement. | see Placement 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 |
| AD | Modifies the bidding price for a specific content ad. | the ID of the content ad as a string |
A note on SOURCE bid modifiers: API already supports SOURCE bid modifiers, but setting them currently has no effect in the system. Full support for SOURCE bid modifiers will be added shortly.
Headers
Content-Type: application/jsonBody
{
"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
}
]
}Get bid modifiers for an ad group ¶GET/rest/v1/adgroups/{adGroupId}/bidmodifiers/{?type}
- adGroupId
string(required) Example: 2040- type
string(optional)- filter results by bid modifier type
Headers
Content-Type: application/jsonBody
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1245",
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
}
}Headers
Content-Type: application/jsonBody
[
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
},
{
"type": "DEVICE",
"sourceSlug": "",
"target": "TABLET",
"modifier": 1.6
}
]Headers
Content-Type: application/jsonBody
{
"data": [
{
"type": "COUNTRY",
"sourceSlug": "",
"target": "US",
"modifier": 1.5
},
{
"type": "DEVICE",
"sourceSlug": "",
"target": "TABLET",
"modifier": 1.6
}
]
}Headers
Content-Type: application/jsonBody
[
{
"id": 1236
},
{
"id": 1237
}
]Headers
Content-Type: application/jsonBody
{}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1235",
"type": "DEVICE",
"sourceSlug": "",
"target": "MOBILE",
"modifier": 0.99
}
}Headers
Content-Type: application/jsonBody
{
"modifier": 0.98
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1235",
"type": "DEVICE",
"sourceSlug": "",
"target": "MOBILE",
"modifier": 0.98
}
}Update a bid modifier for an ad group ¶PUT/rest/v1/adgroups/{adGroupId}/bidmodifiers/{bidModifierId}
Only the modifier value can be changed for an existing Bid Modifier. It is not allowed to change the type, sourceSlug and target of an existing Bid Modifier, instead one can delete the existing Bid Modifier and create a new one with the desired values for these three attributes. However if type, sourceSlug and target values did not change, they can be provided along with the modified modifier value and will not cause a validation error.
- adGroupId
string(required) Example: 2040- bidModifierId
string(required) Example: 1235
Headers
Content-Type: application/jsonBody
{}Content Ad management ¶
Upload Content Ads ¶
Content Ads are uploaded in batches. First, you create an upload batch with the Content Ads you want to upload. Then, you poll the status of the batch and the validation status of the individual Content Ads. If any of the Content Ads in the batch fail the validation process, none of the Content Ads in the batch will be accepted into the system.
If and when all the Content Ads in the batch pass the validation process, they are accepted into the system.
Content Ad
| Property | Type | Description | Create | Update |
|---|---|---|---|---|
| id | string | the content ad’s id | N/A | read only |
| adGroupId | string | the id of the ad group this Content Ad belongs to | N/A | read only |
| state | ACTIVE/INACTIVE |
the state of the Content Ad | N/A | optional |
| label | string | free-form text label | optional | read only |
| url | string | landing url | required | read only |
| title | string | title of the Content Ad | required | read only |
| imageUrl | string | URL of the Content Ad’s image | required | read only |
| imageCrop | image crop | what strategy to use when cropping (most commonly center or faces, more info) |
required | read only |
| displayUrl | string | the URL displayed with the Ad | required | read only |
| brandName | string | the brand name of the Content Ad | required | read only |
| description | string | the description of the Content Ad | required | read only |
| callToAction | string | call to action, most commonly Read more |
required | read only |
| trackerUrls | array[string] | tracker URLs | optional | read only |
Upload Batch
| Property | Type | Description |
|---|---|---|
| id | string | id of the upload batch |
| status | batch status | status of the upload batch |
| validationStatus | array[validation status] | An array of validation statuses for each Content Ad uploaded in this batch. The statuses are in the same order as the ads were uploaded. |
| approvedContentAds | array[Content Ad] | An array that contains the uploaded Content Ads if/when all the ads pass the validation process. The Content Ads are in the same order as they were uploaded, but with added Zemanta IDs. |
Headers
Content-Type: application/jsonBody
[
{
"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",
"trackerUrls": [
"https://example.com/t1",
"https://example.com/t2"
]
}
]Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1302",
"status": "IN_PROGRESS",
"validationStatus": [
{
"__all__": "Content ad still processing."
}
],
"approvedContentAds": []
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "1302",
"status": "DONE",
"validationStatus": [],
"approvedContentAds": [
{
"id": "16805",
"adGroupId": "2040",
"state": "ACTIVE",
"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",
"trackerUrls": [
"https://example.com/t1",
"https://example.com/t2"
]
}
]
}
}Manage content ads ¶
Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "16805",
"adGroupId": "2040",
"state": "ACTIVE",
"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",
"trackerUrls": [
"https://example.com/t1",
"https://example.com/t2"
]
}
]
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "16805",
"adGroupId": "2040",
"state": "ACTIVE",
"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",
"trackerUrls": [
"https://example.com/t1",
"https://example.com/t2"
]
}
}Headers
Content-Type: application/jsonBody
{
"state": "INACTIVE"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "16805",
"adGroupId": "2040",
"state": "INACTIVE",
"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",
"trackerUrls": [
"https://example.com/t1",
"https://example.com/t2"
]
}
}Edit a content ad ¶PUT/rest/v1/contentads/{contentAdId}
Note: At the moment only the state, label and trackerUrls fields can be modified through the API.
As an alternative to editing other fields, please pause and/or archive the existing ads you want to change
and create new ones via the API.
- contentAdId
string(required) Example: 16805
Publishers management ¶
Publisher Groups ¶
Publisher Groups are named collections of publishers that can be referenced in Ad Group’s publisherGroups
targeting section as whitelists or blacklists.
Publishers are represented as publisher domain (or name) and source pairs in the same manner as in publisher reports and blacklist management.
| Property | Type | Description |
|---|---|---|
| id | string | id of the publisher group |
| name | string | name of the publisher group |
Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "111",
"accountId": "186",
"name": "Default whitelist"
}
]
}Headers
Content-Type: application/jsonBody
{
"name": "Secondary whitelist"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "153",
"accountId": "186",
"name": "Secondary whitelist"
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "153",
"accountId": "186",
"name": "Secondary whitelist"
}
}Headers
Content-Type: application/jsonBody
{
"name": "Mobile campaigns blacklist"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "153",
"accountId": "186",
"name": "Mobile campaigns blacklist"
}
}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 |
| source | string | source identifier, if not set it refers to all sources | optional |
| includeSubdomains | boolean | if true, the publisher’s subdomains will also be included in the group | optional, defaults to true |
Headers
Content-Type: application/jsonBody
{
"count": 2,
"next": "https://oneapi.zemanta.com/rest/v1/publishergroups/154/entries/?offset=2&limit=5",
"data": [
{
"id": "652",
"publisherGroupId": "153",
"publisher": "example.com/publisher1",
"source": "gumgum"
},
{
"id": "655",
"publisherGroupId": "153",
"publisher": "example.com/publisher2",
"source": "gumgum"
}
]
}List publisher group entries ¶GET/rest/v1/publishergroups/{publisherGroupId}/entries/{?offset,limit}
- publisherGroupId
string(required) Example: 153- offset
int(optional) Example: 00-based starting index
- limit
int(required) Example: 100Maximum number of entries to return, up to
1000, defaults to100
Headers
Content-Type: application/jsonBody
[
{
"publisherGroupId": "153",
"publisher": "example.com/publisher3",
"source": "triplelift"
},
{
"publisherGroupId": "153",
"publisher": "example.com/publisher4",
"source": "yahoo"
}
]Headers
Content-Type: application/jsonBody
{
"data": [
{
"id": "650",
"publisherGroupId": "153",
"publisher": "example.com/publisher3",
"source": "triplelift"
},
{
"id": "622",
"publisherGroupId": "153",
"publisher": "example.com/publisher4",
"source": "yahoo"
}
]
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "622",
"publisherGroupId": "153",
"publisher": "example.com/publisher4",
"source": "yahoo"
}
}Headers
Content-Type: application/jsonBody
{
"publisher": "example.com/publisher4",
"source": "yahoo"
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "622",
"publisherGroupId": "153",
"publisher": "example.com/publisher4",
"source": "yahoo"
}
}Blacklisting ¶
This endpoint allows you to manage publisher status on different levels.
Optionally, you can assign a bid modifier to a publisher to modify the
bidding price for that publisher. Publisher bid modifiers are currently
only supported on ADGROUP level.
NOTE: Publisher bid modifiers are currently only supported on RTB sources
Headers
Content-Type: application/jsonBody
{
"data": [
{
"name": "example.com/publisher1",
"status": "ENABLED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher2",
"status": "ENABLED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher3",
"status": "BLACKLISTED",
"level": "ADGROUP",
"source": null
}
]
}Headers
Content-Type: application/jsonBody
[
{
"name": "example.com/publisher1",
"status": "BLACKLISTED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher2",
"status": "BLACKLISTED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher3",
"status": "ENABLED",
"level": "ADGROUP",
"source": "gumgum",
"modifier": 0.8
}
]Headers
Content-Type: application/jsonBody
{
"data": [
{
"name": "example.com/publisher1",
"status": "BLACKLISTED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher2",
"status": "BLACKLISTED",
"level": "ADGROUP",
"source": "gumgum"
},
{
"name": "example.com/publisher3",
"status": "ENABLED",
"level": "ADGROUP",
"source": "gumgum",
"modifier": 0.8
}
]
}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.
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"]
}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
-
Media Source, Media Source Id
-
Publisher
Time breakdown:
-
Day (e.g. 2017-03-30)
-
Week (e.g. Week 2017-03-27 - 2017-04-02)
-
Month (e.g. Month 3/2017)
Entity Specific Fields
-
Account:
- Total Fee
- Recognized Flat Fee
-
Content Ad:
- URL
- Display URL
- Brand Name
- Description
- Image Hash
- Image URL
- Call to action
- Label
- Uploaded
- Batch Name
-
Media Source:
- Media Source Slug
Common Fields
-
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
Conversion Fields
To get conversion data in the report, simply specify the same column names as you see them in the Zemanta Dashboard.
For example, if your conversion goal name is “MyGoal”, the valid column names would be
-
MyGoal 1 day
-
MyGoal 7 days
-
MyGoal 30 days
-
MyGoal 90 days
Report jobs ¶
Headers
Content-Type: application/jsonBody
{
"fields": [
{
"field": "Content Ad Id"
},
{
"field": "Content Ad"
},
{
"field": "Label"
},
{
"field": "Total Spend"
},
{
"field": "Impressions"
},
{
"field": "Clicks"
},
{
"field": "Avg. CPC"
}
],
"filters": [
{
"field": "Date",
"operator": "between",
"from": "2016-10-01",
"to": "2016-10-31"
},
{
"field": "Ad Group Id",
"operator": "=",
"value": "2040"
}
]
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "27",
"status": "IN_PROGRESS",
"result": null
}
}Headers
Content-Type: application/jsonBody
{
"data": {
"id": "27",
"status": "DONE",
"result": "https://z1-rest-reports.s3.amazonaws.com/KgrK55qCMO85v9JhHwCIv8kso2quYwEGV2MLpiVUgDVRDJm3HiGk1lWrOGfxJ7k2.csv"
}
}Utilities ¶
Geolocations ¶
Headers
Content-Type: application/jsonBody
<a name="bluekai-taxonomy"></a>List geolocations ¶GET/rest/v1/geolocations/{?keys,types,nameContains,limit}
- keys
string(optional) Example: US,US-HIComma-separated list of location keys
- types
string(optional) Example: COUNTRY,REGIONComma-separated list of location types
- nameContains
string(optional) Example: UnitedSearch query
- limit
int(optional) Example: 10Maximum number of locations to return, up to
50, defaults to10
BlueKai Taxonomy ¶
Headers
Content-Type: application/jsonBody
{
"data": {
"categoryId": 671901,
"name": "Parent category name",
"description": "Parent category description",
"navigationOnly": false,
"price": "1.0",
"reach": 1000000000,
"childNodes": [
{
"categoryId": 671902,
"name": "Child category name",
"description": "Child category description",
"navigationOnly": false,
"price": "1.20",
"reach": 1000000000,
"childNodes": []
}
]
}
}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
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 / Content ad State
-
ACTIVE -
INACTIVE
Autopilot State
-
ACTIVE_CPC- Optimize Bids -
ACTIVE_CPC_BUDGET- Optimize Bids and Daily Budgets -
INACTIVE- Disabled
Language
-
ARABIC- Arabic -
GERMAN- German -
GREEK- Greek -
ENGLISH- English -
SPANISH- Spanish -
FRENCH- French -
INDONESIAN- Indonesian -
ITALIAN- Italian -
JAPANESE- Japanese -
MALAY- Malay -
DUTCH- Dutch -
PORTUGUESE- Portuguese -
ROMANIAN- Romanian -
RUSSIAN- Russian -
SWEDISH- Swedish -
TURKISH- Turkish -
VIETNAMESE- Vietnamese -
SIMPLIFIED_CHINESE- Simplified Chinese -
TRADITIONAL_CHINESE- Traditional Chinese -
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- Mororcycles -
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- Colledge 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/Pre School -
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/Lowfat 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- 3-D 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- CopyrightInfringement
Publishers
Status
-
ENABLED -
BLACKLISTED
Level
-
ADGROUP -
CAMPAIGN -
ACCOUNT
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 -
NEW_UNIQUE_VISITORS- New Users -
CPV- Cost per Visit -
CP_NON_BOUNCED_VISIT- Cost per Non-Bounced Visit -
CP_NEW_VISITOR- Cost per New Visitor -
CP_PAGE_VIEW- Cost per Page View -
CPCV- Cost per Completed Video View
Conversion goal type
-
PIXEL- Conversion Pixel -
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
Content ad upload batch status
-
DONE -
FAILED -
IN_PROGRESS -
CANCELLED
Delivery Type
-
STANDARD- Deliver ads throughout the day. -
ACCELERATED- Deliver ads as soon as possible.
Device targeting
-
DESKTOP -
TABLET -
MOBILE
Placement targeting
-
SITE -
APP
Operating system targeting
-
WINDOWS- Windows -
MACOSX- MacOSX and macOS -
LINUX- Linux -
ANDROID- Android -
IOS- iOS -
WINPHONE- Windows Phone
Operating system version targeting
-
WINDOWS_10- Windows 10 -
WINDOWS_8_1- Windows 8.1 -
WINDOWS_8- Windows 8 -
WINDOWS_7- Windows 7 -
WINDOWS_VISTA- Windows Vista -
WINDOWS_XP- Windows XP -
WINDOWS_2000- Windows 2000 -
WINDOWS_98- Windows 98 -
MACOSX_10_13- macOS 10.13 High Sierra -
MACOSX_10_12- macOS 10.12 Sierra -
MACOSX_10_11- Mac OS X 10.11 El Capitan -
MACOSX_10_10- Mac OS X 10.10 Yosemite -
MACOSX_10_9- Mac OS X 10.9 Mavericks -
MACOSX_10_8- Mac OS X 10.8 Mountain Lion -
MACOSX_10_7- Mac OS X 10.7 Lion -
MACOSX_10_6- Mac OS X 10.6 Snow Leopard -
MACOSX_10_5- Mac OS X 10.5 Leopard -
MACOSX_10_4- Mac OS X 10.4 Tiger -
ANDROID_8_0- Android 8.0 Oreo -
ANDROID_7_1- Android 7.1 Nougat -
ANDROID_7_0- Android 7.0 Nougat -
ANDROID_6_0- Android 6.0 Marshmallow -
ANDROID_5_1- Android 5.1 Lollipop -
ANDROID_5_0- Android 5.0 Lollipop -
ANDROID_4_4- Android 4.4 KitKat -
ANDROID_4_3- Android 4.3 Jelly Bean -
ANDROID_4_2- Android 4.2 Jelly Bean -
ANDROID_4_1- Android 4.1 Jelly Bean -
ANDROID_4_0- Android 4.0 Ice Cream Sandwich -
ANDROID_3_2- Android 3.2 Honeycomb -
ANDROID_3_1- Android 3.1 Honeycomb -
ANDROID_3_0- Android 3.0 Honeycomb -
ANDROID_2_3- Android 2.3 Gingerbread -
ANDROID_2_2- Android 2.2 Froyo -
ANDROID_2_1- Android 2.1 Eclair -
IOS_11_0- iOS 11.0 -
IOS_10_3- iOS 10.3 -
IOS_10_2- iOS 10.2 -
IOS_10_1- iOS 10.1 -
IOS_10_0- iOS 10.0 -
IOS_9_3- iOS 9.3 -
IOS_9_2- iOS 9.2 -
IOS_9_1- iOS 9.1 -
IOS_9_0- iOS 9.0 -
IOS_8_4- iOS 8.4 -
IOS_8_3- iOS 8.3 -
IOS_8_2- iOS 8.2 -
IOS_8_1- iOS 8.1 -
IOS_8_0- iOS 8.0 -
IOS_7_1- iOS 7.1 -
IOS_7_0- iOS 7.0 -
IOS_6_1- iOS 6.1 -
IOS_6_0- iOS 6.0 -
IOS_5_1- iOS 5.1 -
IOS_5_0- iOS 5.0 -
IOS_4_3- iOS 4.3 -
IOS_4_2- iOS 4.2 -
IOS_4_1- iOS 4.1 -
IOS_4_0- iOS 4.0 -
IOS_3_2- iOS 3.2 -
WINPHONE_10- Windows Phone 10 -
WINPHONE_8_1- Windows Phone 8.1 -
WINPHONE_8_0- Windows Phone 8.0 -
WINPHONE_7- Windows Phone 7
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
Geo targeting
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
Generated by aglio on 20 Nov 2019