Campaigns

The Campaign object contains the details of the campaign the advertiser would like to run, along with a list of units. It starts out as a proposal, then moves into a booked state once purchased.

The Campaign Object

The campaign can be of 2 types:

• Direct

• Rtb

In addition to standard data, the campaign object involves three other sub-objects: geography, resolutions, and units. These are detailed below.

Proposal Object

When submitting a campaign you use a proposal object like below

campaign_type: direct | rtb
advertiser_id: integer
start_date: string (Format: MM/DD/YYYY)
end_date: string (Format: MM/DD/YYYY)
target_budget_cents: integer (USD cents)
media_types: array[media_types object] (optional)
placements: array[placements object] (optional)
geographies: array[geography object] (optional)

The Media Types Object

You can call the media type

Expected format:
{
    direct_ids: [array of strings],
    rtb_ids: [array of strings]
}

The Geography Object

By default the API only supports U.S.-based inventory, but non-U.S. inventory can be included upon request.

The API currently supports three ways of targeting via geography:

• Nielsen DMA IDs

• U.S. ZIP Codes.

• Market IDs

You can use both zip codes and DMAs/Markets in the same request.

This is the expected format for the geography object:

Expected format:
{
  dma_ids: [array of integers],
  market_ids: [array of integers],
  zip_codes: [array of strings]
}

Example:
{
  dma_ids: [501, 524], #=> e.g. New York, Atlanta,
  market_ids: [737, 686] #=> e.g. New York, Atlanta
  zip_codes: ["75225", "90291"]
}

Important: Please note that DMA ids and Market ids are integers and zip codes are strings.

Endpoints

POST /campaigns #=> Create campaign
GET /campaigns/:id #=> Get campaign details
GET /campaigns #=> List campaigns
POST /campaigns/:id/book #=> Book the campaign

Create Campaign

create campaign

POSThttps://www.example.com/v1/campaigns

Header parameters

Body

application/json

campaign_type*string

partner_id*integer

advertiser_id*integer

start_date*string (date)

end_date*string (date)

target_budget_cents*integer

placementsobject

geographiesobject

media_typesobject

Response

200

successful

Body

application/json

token*string

campaign_type*string

advertiser_id*integer

start_date*string (date)

end_date*string (date)

target_budget_cents*integer

placements*object

geographies*object

media_types*object

Request

JavaScriptCurlPython

const response = await fetch('https://www.example.com/v1/campaigns', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "campaign_type": "text",
      "start_date": "2024-11-26",
      "end_date": "2024-11-26"
    }),
});
const data = await response.json();

Response

200

{
  "token": "text",
  "campaign_type": "text",
  "start_date": "2024-11-26",
  "end_date": "2024-11-26",
  "placements": {
    "direct_ids": [
      "text"
    ],
    "rtb_ids": [
      "text"
    ]
  },
  "geographies": {},
  "media_types": {
    "direct_ids": [
      "text"
    ],
    "rtb_ids": [
      "text"
    ]
  }
}

Get Campaign

GET /campaigns/:id

Returns: the full campaign object

List Campaigns

list campaigns

GEThttps://www.example.com/v1/campaigns

Query parameters

Header parameters

Response

200

successful

Body

application/json

records*array of object

pagination*object

Request

JavaScriptCurlPython

const response = await fetch('https://www.example.com/v1/campaigns', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "records": [
    {
      "token": "text",
      "campaign_type": "text",
      "start_date": "2024-11-26",
      "end_date": "2024-11-26",
      "placements": {
        "direct_ids": [
          "text"
        ],
        "rtb_ids": [
          "text"
        ]
      },
      "geographies": {},
      "media_types": {
        "direct_ids": [
          "text"
        ],
        "rtb_ids": [
          "text"
        ]
      }
    }
  ],
  "pagination": {}
}

GET /campaigns

Expects:
- start_date (optionally filter by start_date greater than or equal to)
- end_date (optionally filter by end_date less than or equal to)
- campaign_type (optionally filter by campaign type, accepts 'rtb' or 'direct')
- status (optionally filter by status)

Date format: YYYY-MM-DD

Returns: paginated array of campaign objects

Book a Campaign

When you book a campaign, in our system we'll execute against the proposed inventory matching your preferences.

POST /campaigns/:id/book

Expects
- id

Returns: the full campaign object of the new booked campaign.

You need to have approved creatives for the campaign in order to book an auction campaign. Our system will automatically match each unit with a matching creative based on the resolution.

You can submit more than one creative per unit and they will automatically alternate.

If there are units that don't have a matching creative resolution, the booking will not be completed and the endpoint and will return a 402 along with the resolutions that are missing.