Skip to main content

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

​
Request Schema

​
Order Fields

FieldTypeRequiredDescription
namestringYesOrder name
nicknamestringNoShort order identifier
clientOrderIdstringYesYour internal order identifier
typestringYesOrder type: TENTPOLE or RON
startTimestring (ISO 8601)YesOrder start date
endTimestring (ISO 8601)YesOrder end date
clusterstringYesCluster identifier
impressionGoalnumberYesTarget number of impressions
campaignIdnumberYesID of the campaign this order belongs to
notesstringNoAdditional notes about the order
marketsarrayYesList of market targeting objects
creativeobjectYesCreative details

​
Market Object

FieldTypeRequiredDescription
typestringYesMarket type: DMA, STATE, ZIP, or NATIONAL
valuestringYesMarket value (e.g., DMA code, state abbreviation, zip code)
namestringNoHuman-readable market name

​
Market Types

TypeValue ExampleDescription
DMA"501"Designated Market Area code
STATE"NJ"Two-letter state abbreviation
ZIP"10001"5-digit ZIP code
NATIONAL"US"National targeting

​
Creative Object

FieldTypeRequiredDescription
namestringYesCreative name
csIdstringConditionalFreeWheel CS ID. Required for TENTPOLE orders
placementIdstringConditionalFreeWheel Placement ID. Required for RON orders
startTimestring (ISO 8601)YesCreative start date
endTimestring (ISO 8601)YesCreative end date
isDVbooleanNoDoubleVerify 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

FieldTypeDescription
idnumberThe unique order ID
namestringOrder name
nickNamestringShort order identifier
statusstringOrder status (see status values below)
clientOrderIdstringYour internal order identifier
typestringOrder type: TENTPOLE or RON
clusterstringCluster identifier
impressionGoalnumberTarget number of impressions
startTimestring (ISO 8601)Order start date
endTimestring (ISO 8601)Order end date
createdAtstring (ISO 8601)Timestamp when the order was created

​
Status Values

StatusDescription
NEEDS_APPROVALNewly created, awaiting review
PENDINGApproved, waiting to start
ACTIVECurrently running
PAUSEDTemporarily paused
COMPLETEFinished delivering
CANCELLEDCancelled before completion

​
Error Responses

​
Example Error Response

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

​
Common Errors

ErrorCause
Campaign not found or does not belong to your clientThe campaignId doesn’t exist or belongs to another client
csId is required for TENTPOLE ordersmust provide csId for TENTPOLE orders
placementId is required for RON ordersmust provide placementId for RON orders
Order type must be either TENTPOLE or RONInvalid order type value
Market type must be one of: DMA, STATE, ZIP, NATIONALInvalid 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