Segment Activation

Once a segment has finished building (status complete), you activate it by specifying a target DSP and buyer seat. Classify pushes the segment into the DSP's supply chain and returns a Deal ID you can target directly in your campaigns.

Activation is asynchronous. You receive an activation ID immediately, and the Deal ID is typically ready within a few hours.

tip

Need to check whether your segment is ready to activate? See Segment Creation — Polling for completion.

The activation object

{
  "id": 142,
  "segment_ids": [61],
  "dsp": "The Trade Desk",
  "buyer_seat": "seat-abc123",
  "status": "complete",
  "deal_id": "classify-ttd-61-a8f3c",
  "ttl_hours": 720,
  "start_date": "2026-01-15",
  "end_date": "2026-02-15",
  "geo": ["US", "CA"],
  "formats": ["banner", "video"],
  "devices": ["desktop", "mobile"],
  "kpis": [
    {"metric": "ctr", "target": 0.003},
    {"metric": "viewability", "target": 0.70}
  ],
  "budget": {"amount": 50000, "currency": "USD"},
  "created_date": "2026-02-12T22:09:38Z",
  "processed_date": "2026-02-12T22:41:22Z"
}

Field	Type	Description
`id`	integer	Unique identifier for this activation
`segment_ids`	array[integer]	The segment IDs included in this deal
`dsp`	string	The DSP the deal was pushed to
`buyer_seat`	string	Your buyer seat ID in the DSP
`status`	string	`pending` → `processing` → `complete` or `failed`
`deal_id`	string \| null	The Deal ID to target in your DSP. `null` until `status` is `complete`.
`ttl_hours`	integer \| null	How long the deal remains active, in hours. `null` until `status` is `complete`.
`start_date`	string (ISO 8601) \| null	Campaign start date, if provided
`end_date`	string (ISO 8601) \| null	Campaign end date, if provided
`geo`	array[string] \| null	Targeted countries, if provided
`formats`	array[string] \| null	Ad formats, if provided
`devices`	array[string] \| null	Device types, if provided
`kpis`	array[object] \| null	KPI targets, if provided
`budget`	object \| null	Campaign budget, if provided
`created_date`	string (ISO 8601)	When the activation request was submitted
`processed_date`	string (ISO 8601) \| null	When the Deal ID was issued. `null` until complete.

Activate a segment

POST https://api.clsfy.me/v1/clsfy/activations

Parameters

Parameter	Type	Required	Description
`segment_ids`	array[integer]	Required	One or more segment IDs to include in the deal. Segments must have `status: "complete"`.
`dsp`	string	Required	The DSP to push the deal to. Must be a value from the supported DSP list.
`buyer_seat`	string	Required	Your buyer seat identifier in the target DSP.
`start_date`	string (ISO 8601)	Optional	Campaign start date (e.g. `"2026-01-15"`).
`end_date`	string (ISO 8601)	Optional	Campaign end date.
`geo`	array[string]	Optional	ISO 3166-1 alpha-2 country codes to target (e.g. `["US", "CA", "GB"]`). Omit for global.
`formats`	array[string]	Optional	Ad formats to include. Values: `banner`, `video`, `native`, `ctv`, `audio`. Omit for all formats.
`devices`	array[string]	Optional	Device types to target. Values: `desktop`, `mobile`, `tablet`, `ctv`. Omit for all devices.
`kpis`	array[object]	Optional	Performance targets. Each object has a `metric` (string) and `target` (number). See KPIs.
`budget`	object	Optional	Campaign budget. Object with `amount` (number) and `currency` (string, ISO 4217).

Request

curl
Python

curl -X POST "https://api.clsfy.me/v1/clsfy/activations" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_ids": [61],
    "dsp": "The Trade Desk",
    "buyer_seat": "seat-abc123",
    "start_date": "2026-01-15",
    "end_date": "2026-02-15",
    "geo": ["US", "CA"],
    "formats": ["banner", "video"],
    "devices": ["desktop", "mobile"],
    "kpis": [
      {"metric": "ctr", "target": 0.003},
      {"metric": "viewability", "target": 0.70}
    ],
    "budget": {"amount": 50000, "currency": "USD"}
  }'

import requests

response = requests.post(
    "https://api.clsfy.me/v1/clsfy/activations",
    headers={
        "X-API-Key": "<your_api_key>",
        "Content-Type": "application/json",
    },
    json={
        "segment_ids": [61],
        "dsp": "The Trade Desk",
        "buyer_seat": "seat-abc123",
        "start_date": "2026-01-15",
        "end_date": "2026-02-15",
        "geo": ["US", "CA"],
        "formats": ["banner", "video"],
        "devices": ["desktop", "mobile"],
        "kpis": [
            {"metric": "ctr", "target": 0.003},
            {"metric": "viewability", "target": 0.70},
        ],
        "budget": {"amount": 50000, "currency": "USD"},
    },
)

activation = response.json()
print(activation["id"])  # e.g. 142

Response

Returns the newly created activation object with status: "pending".

{
  "id": 142,
  "segment_ids": [61],
  "dsp": "The Trade Desk",
  "buyer_seat": "seat-abc123",
  "status": "pending",
  "deal_id": null,
  "ttl_hours": null,
  "start_date": "2026-01-15",
  "end_date": "2026-02-15",
  "geo": ["US", "CA"],
  "formats": ["banner", "video"],
  "devices": ["desktop", "mobile"],
  "kpis": [
    {"metric": "ctr", "target": 0.003},
    {"metric": "viewability", "target": 0.70}
  ],
  "budget": {"amount": 50000, "currency": "USD"},
  "created_date": "2026-02-12T22:09:38Z",
  "processed_date": null
}

Get an activation

Retrieves an activation by ID. Use this to poll for the Deal ID.

GET https://api.clsfy.me/v1/clsfy/activations/{id}

Parameter	Type	Description
`id`	integer	The activation ID returned at creation

curl
Python

curl "https://api.clsfy.me/v1/clsfy/activations/142" \
  -H "X-API-Key: <your_api_key>"

import requests

response = requests.get(
    "https://api.clsfy.me/v1/clsfy/activations/142",
    headers={"X-API-Key": "<your_api_key>"},
)

activation = response.json()
if activation["status"] == "complete":
    print("Deal ID:", activation["deal_id"])
    print("TTL (hours):", activation["ttl_hours"])

Polling for your Deal ID

Poll GET /v1/clsfy/activations/{id} until status is "complete" or processed_date is not null. Once ready, the response will include deal_id and ttl_hours.

Take the deal_id into your DSP and set it as the deal target on your line item or campaign.

Python

import requests
import time

def wait_for_deal_id(activation_id: int, api_key: str, poll_interval: int = 60):
    """Poll until a Deal ID is issued. Returns the completed activation object."""
    url = f"https://api.clsfy.me/v1/clsfy/activations/{activation_id}"
    headers = {"X-API-Key": api_key}

    while True:
        activation = requests.get(url, headers=headers).json()

        if activation["status"] == "complete":
            print(f"Deal ID: {activation['deal_id']}")
            print(f"Expires in: {activation['ttl_hours']} hours")
            return activation
        elif activation["status"] == "failed":
            raise RuntimeError(f"Activation {activation_id} failed.")

        print(f"Status: {activation['status']} — retrying in {poll_interval}s")
        time.sleep(poll_interval)

KPIs

Use the kpis array to communicate performance targets to Classify. These inform how the segment is configured and tuned.

Metric	Description	Example target
`ctr`	Click-through rate	`0.003` (0.3%)
`conversion`	Conversion rate	`0.01` (1%)
`viewability`	Viewable impression rate	`0.70` (70%)
`vcr`	Video completion rate	`0.75` (75%)
`cpa`	Cost per acquisition (dollar amount)	`25.00`
`roas`	Return on ad spend (multiplier)	`4.0`

"kpis": [
  {"metric": "ctr", "target": 0.003},
  {"metric": "viewability", "target": 0.70}
]

Supported DSPs

The dsp field must exactly match one of the following values:

View all 93 supported DSPs

DSP Name
Aarki DSP
Active Agent/Adition DSP
Addictive Mobility
Adform
AdKernel DSP
Admixer
Adobe
AdRoll
AdTheorent
Advanced Store Germany
Amazon DSP
ArabyAds DSP
Arpeely DSP
Basis Technologies
Beeswax io
BidSwitch
BidTheatre AB
Blis Media
Blockboard DSP
BridgeCorp
Cadent
Cloud Technologies S.A.
Cognitiv
Conversant
Cox Automotive DSP
Crimtan DSP
Criteo
DeepIntent
Define Media
Delta Projects/Azerion
DV360
Edge226
Emodo
Eskimi DSP
Exponential DSP
Gamoshi DSP
Hawk
illumin
Infillion DSP
InMobi DSP
iPROM DSP
IQM
IQZone DSP
Jaduda GMBH/Splicky
Jampp
Krush Media
Local Sensor
Loopme DSP
MadHive
Madopi Medi
Mars Media
Mediaforce
MediaSmart
MobPro NL
molocoads DSP
Nexxen
Octillion
OneVie
Opera Ads
Point2Web
PubMatic Activate
PulsePoint DSP
Quantcast
Remerge GmbH
Reset Digital
RTB House PL
RTB Mi
Samsung DSP
Sift.co
Simpli.fi
Smaato DSP
Smadex S.L.
Sqreem DSP
StackAdapt
SurfSide
TapTap DSP
TargetSmart
The Trade Desk
ThinkNear
Travelaudience GmbH/Amadeus
Tubia DSP
Unruly
Valassis Digital
Viant
Xandr
Yahoo DSP
YouAppi
Zemanta/Outbrain
Zeta DSP

note

Don't see your DSP? Contact your Classify representative to request support for additional platforms.

Error responses

When a request fails, the API returns a JSON object with an error code and a human-readable message:

{
  "error": "not_found",
  "message": "Activation with ID 999 not found"
}

HTTP status codes

Status	Meaning
`200 OK`	Success
`201 Created`	Activation created
`400 Bad Request`	Invalid or missing parameters
`401 Unauthorized`	Missing or invalid API key
`404 Not Found`	Activation not found
`422 Unprocessable Content`	Validation error (e.g. segment not yet complete)
`429 Too Many Requests`	Rate limit exceeded

The activation object​

Activate a segment​

Parameters​

Request​

Response​

Get an activation​

Polling for your Deal ID​

KPIs​

Supported DSPs​

Error responses​

HTTP status codes​