Create Order

Example API Usage

Here are examples of how to create an order using the Addressable.tv API in different programming languages:

import requests
import json

url = "https://api.addressable.tv/client/orders"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "name": "NFL Playoffs - East Coast",
    "nickname": "NFLP-EC",
    "clientOrderId": "ORD-2025-001",
    "type": "TENTPOLE",
    "startTime": "2025-01-15T00:00:00.000Z",
    "endTime": "2025-02-15T23:59:59.000Z",
    "cluster": "sports",
    "impressionGoal": 500000,
    "campaignId": 1234,
    "notes": "East coast targeting for NFL playoffs",
    "markets": [
        {"type": "DMA", "value": "501", "name": "New York"},
        {"type": "DMA", "value": "504", "name": "Philadelphia"},
        {"type": "STATE", "value": "NJ"}
    ],
    "creative": {
        "name": "Brand Spot 30s",
        "csId": "cs123456",
        "startTime": "2025-01-15T00:00:00.000Z",
        "endTime": "2025-02-15T23:59:59.000Z",
        "isDV": True
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data)

const url = 'https://api.addressable.tv/client/orders';
const headers = {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json',
};
const payload = {
  name: 'NFL Playoffs - East Coast',
  nickname: 'NFLP-EC',
  clientOrderId: 'ORD-2025-001',
  type: 'TENTPOLE',
  startTime: '2025-01-15T00:00:00.000Z',
  endTime: '2025-02-15T23:59:59.000Z',
  cluster: 'sports',
  impressionGoal: 500000,
  campaignId: 1234,
  notes: 'East coast targeting for NFL playoffs',
  markets: [
    { type: 'DMA', value: '501', name: 'New York' },
    { type: 'DMA', value: '504', name: 'Philadelphia' },
    { type: 'STATE', value: 'NJ' },
  ],
  creative: {
    name: 'Brand Spot 30s',
    csId: 'cs123456',
    startTime: '2025-01-15T00:00:00.000Z',
    endTime: '2025-02-15T23:59:59.000Z',
    isDV: true,
  },
};

fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error(error));

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class CreateOrder {
    public static void main(String[] args) {
        String payload = """
            {
                "name": "NFL Playoffs - East Coast",
                "nickname": "NFLP-EC",
                "clientOrderId": "ORD-2025-001",
                "type": "TENTPOLE",
                "startTime": "2025-01-15T00:00:00.000Z",
                "endTime": "2025-02-15T23:59:59.000Z",
                "cluster": "sports",
                "impressionGoal": 500000,
                "campaignId": 1234,
                "notes": "East coast targeting for NFL playoffs",
                "markets": [
                    {"type": "DMA", "value": "501", "name": "New York"},
                    {"type": "DMA", "value": "504", "name": "Philadelphia"},
                    {"type": "STATE", "value": "NJ"}
                ],
                "creative": {
                    "name": "Brand Spot 30s",
                    "csId": "cs123456",
                    "startTime": "2025-01-15T00:00:00.000Z",
                    "endTime": "2025-02-15T23:59:59.000Z",
                    "isDV": true
                }
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.addressable.tv/client/orders"))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
            .thenApply(HttpResponse::body)
            .thenAccept(System.out::println)
            .join();
    }
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.addressable.tv/client/orders"

    payload := map[string]interface{}{
        "name":           "NFL Playoffs - East Coast",
        "nickname":       "NFLP-EC",
        "clientOrderId":  "ORD-2025-001",
        "type":           "TENTPOLE",
        "startTime":      "2025-01-15T00:00:00.000Z",
        "endTime":        "2025-02-15T23:59:59.000Z",
        "cluster":        "sports",
        "impressionGoal": 500000,
        "campaignId":     1234,
        "notes":          "East coast targeting for NFL playoffs",
        "markets": []map[string]string{
            {"type": "DMA", "value": "501", "name": "New York"},
            {"type": "DMA", "value": "504", "name": "Philadelphia"},
            {"type": "STATE", "value": "NJ"},
        },
        "creative": map[string]interface{}{
            "name":      "Brand Spot 30s",
            "csId":      "cs123456",
            "startTime": "2025-01-15T00:00:00.000Z",
            "endTime":   "2025-02-15T23:59:59.000Z",
            "isDV":      true,
        },
    }

    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))

    req.Header.Add("x-api-key", "YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        var payload = @"{
            ""name"": ""NFL Playoffs - East Coast"",
            ""nickname"": ""NFLP-EC"",
            ""clientOrderId"": ""ORD-2025-001"",
            ""type"": ""TENTPOLE"",
            ""startTime"": ""2025-01-15T00:00:00.000Z"",
            ""endTime"": ""2025-02-15T23:59:59.000Z"",
            ""cluster"": ""sports"",
            ""impressionGoal"": 500000,
            ""campaignId"": 1234,
            ""notes"": ""East coast targeting for NFL playoffs"",
            ""markets"": [
                {""type"": ""DMA"", ""value"": ""501"", ""name"": ""New York""},
                {""type"": ""DMA"", ""value"": ""504"", ""name"": ""Philadelphia""},
                {""type"": ""STATE"", ""value"": ""NJ""}
            ],
            ""creative"": {
                ""name"": ""Brand Spot 30s"",
                ""csId"": ""cs123456"",
                ""startTime"": ""2025-01-15T00:00:00.000Z"",
                ""endTime"": ""2025-02-15T23:59:59.000Z"",
                ""isDV"": true
            }
        }";

        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Post,
            RequestUri = new Uri("https://api.addressable.tv/client/orders"),
            Content = new StringContent(payload, Encoding.UTF8, "application/json")
        };

        request.Headers.Add("x-api-key", "YOUR_API_KEY");

        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        var data = await response.Content.ReadAsStringAsync();
        Console.WriteLine(data);
    }
}

#include <curl/curl.h>
#include <iostream>
#include <string>

static size_t WriteCallback(void *contents, size_t size, size_t nmemb, void *userp)
{
    ((std::string*)userp)->append((char*)contents, size * nmemb);
    return size * nmemb;
}

int main()
{
    CURL *curl;
    CURLcode res;
    std::string readBuffer;

    const char* payload = R"({
        "name": "NFL Playoffs - East Coast",
        "nickname": "NFLP-EC",
        "clientOrderId": "ORD-2025-001",
        "type": "TENTPOLE",
        "startTime": "2025-01-15T00:00:00.000Z",
        "endTime": "2025-02-15T23:59:59.000Z",
        "cluster": "sports",
        "impressionGoal": 500000,
        "campaignId": 1234,
        "notes": "East coast targeting for NFL playoffs",
        "markets": [
            {"type": "DMA", "value": "501", "name": "New York"},
            {"type": "DMA", "value": "504", "name": "Philadelphia"},
            {"type": "STATE", "value": "NJ"}
        ],
        "creative": {
            "name": "Brand Spot 30s",
            "csId": "cs123456",
            "startTime": "2025-01-15T00:00:00.000Z",
            "endTime": "2025-02-15T23:59:59.000Z",
            "isDV": true
        }
    })";

    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "x-api-key: YOUR_API_KEY");
        headers = curl_slist_append(headers, "Content-Type: application/json");

        curl_easy_setopt(curl, CURLOPT_URL, "https://api.addressable.tv/client/orders");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &readBuffer);

        res = curl_easy_perform(curl);
        if(res != CURLE_OK)
            std::cout << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;

        curl_easy_cleanup(curl);
        curl_slist_free_all(headers);
    }

    std::cout << readBuffer << std::endl;
    return 0;
}

Request Schema

Order Fields

Field	Type	Required	Description
`name`	string	Yes	Order name
`nickname`	string	No	Short order identifier
`clientOrderId`	string	Yes	Your internal order identifier
`type`	string	Yes	Order type: `TENTPOLE`, `RON`, or `LEAGUE_SPORTS`
`startTime`	string (ISO 8601)	Yes	Order start date
`endTime`	string (ISO 8601)	Yes	Order end date
`cluster`	string	Yes	Cluster identifier
`impressionGoal`	number	Yes	Target number of impressions
`campaignId`	number	Yes	ID of the campaign this order belongs to
`notes`	string	No	Additional notes about the order
`markets`	array	Yes	List of market targeting objects
`creative`	object	Yes	Creative details

Market Object

Field	Type	Required	Description
`type`	string	Yes	Market type: `DMA`, `STATE`, `ZIP`, or `NATIONAL`
`value`	string	Yes	Market value (e.g., DMA code, state abbreviation, zip code)
`name`	string	No	Human-readable market name

Market Types

Type	Value Example	Description
`DMA`	`"501"`	Designated Market Area code
`STATE`	`"NJ"`	Two-letter state abbreviation
`ZIP`	`"10001"`	5-digit ZIP code
`NATIONAL`	`"US"`	National targeting

Creative Object

Field	Type	Required	Description
`name`	string	Yes	Creative name
`csId`	string	Conditional	FreeWheel CS ID. Required for TENTPOLE and LEAGUE_SPORTS orders
`placementId`	string	Conditional	FreeWheel Placement ID. Required for RON orders
`startTime`	string (ISO 8601)	Yes	Creative start date
`endTime`	string (ISO 8601)	Yes	Creative end date
`isDV`	boolean	No	DoubleVerify enabled (default: false)

Response Schema

The API returns the created order object with additional system-generated fields.

Example Response

{
  "id": 5678,
  "name": "NFL Playoffs - East Coast",
  "nickName": "NFLP-EC",
  "status": "NEEDS_APPROVAL",
  "clientOrderId": "ORD-2025-001",
  "type": "TENTPOLE",
  "cluster": "sports",
  "impressionGoal": 500000,
  "startTime": "2025-01-15T00:00:00.000Z",
  "endTime": "2025-02-15T23:59:59.000Z",
  "createdAt": "2025-01-15T10:35:00.000Z"
}

Response Fields

Field	Type	Description
`id`	number	The unique order ID
`name`	string	Order name
`nickName`	string	Short order identifier
`status`	string	Order status (see status values below)
`clientOrderId`	string	Your internal order identifier
`type`	string	Order type: `TENTPOLE`, `RON`, or `LEAGUE_SPORTS`
`cluster`	string	Cluster identifier
`impressionGoal`	number	Target number of impressions
`startTime`	string (ISO 8601)	Order start date
`endTime`	string (ISO 8601)	Order end date
`createdAt`	string (ISO 8601)	Timestamp when the order was created

Status Values

Status	Description
`NEEDS_APPROVAL`	Newly created, awaiting review
`PENDING`	Approved, waiting to start
`ACTIVE`	Currently running
`PAUSED`	Temporarily paused
`COMPLETE`	Finished delivering
`CANCELLED`	Cancelled before completion

Error Responses

Example Error Response

{
  "statusCode": 400,
  "message": ["campaignId must be a number", "type must be one of: TENTPOLE, RON, LEAGUE_SPORTS"],
  "error": "Bad Request"
}

Common Errors

Error	Cause
`Campaign not found or does not belong to your client`	The `campaignId` doesn’t exist or belongs to another client
`csId is required for TENTPOLE or LEAGUE_SPORTS orders`	must provide csId for TENTPOLE or LEAGUE_SPORTS orders
`placementId is required for RON orders`	must provide placementId for RON orders
`Order type must be one of: TENTPOLE, RON, LEAGUE_SPORTS`	Invalid order type value
`Market type must be one of: DMA, STATE, ZIP, NATIONAL`	Invalid market type

Notes

You must create a campaign first and use its id as the campaignId
Initial status is always NEEDS_APPROVAL - your account team will review and activate
Ensure startTime is before endTime for both orders and creatives

Get Started

Campaigns and Orders

Export Reports

Integrations

Example API Usage

Request Schema

Order Fields

Market Object

Market Types

Creative Object

Response Schema

Example Response

Response Fields

Status Values

Error Responses

Example Error Response

Common Errors

Notes

​Example API Usage

​Request Schema

​Order Fields

​Market Object

​Market Types

​Creative Object

​Response Schema

​Example Response

​Response Fields

​Status Values

​Error Responses

​Example Error Response

​Common Errors

​Notes

Example API Usage

Request Schema

Order Fields

Market Object

Market Types

Creative Object

Response Schema

Example Response

Response Fields

Status Values

Error Responses

Example Error Response

Common Errors

Notes