Segment Creation

Contextual segments are curated lists of URLs grouped around a topic, interest, or intent signal. When you create a segment, Classify analyzes your inputs and builds a URL list that you can activate in any DSP as a deal ID.

Segment creation is asynchronous. You receive a segment ID immediately, and the segment typically finishes building within 1–2 hours. Once complete, proceed to Segment Activation to get your deal ID.

---

The segment object

{
  "id": 61,
  "name": "Snowblower Buyers",
  "status": "complete",
  "created_date": "2026-02-12T22:09:38Z",
  "processed_date": "2026-02-12T23:51:14Z"
}

Field	Type	Description
id	integer	Unique identifier for the segment
name	string	Display name provided at creation
status	string	Current build status: pending → processing → complete or failed
created_date	string (ISO 8601)	When the segment request was received
processed_date	string (ISO 8601) | null	When the segment finished building. null until complete.

---

Create a segment

POST https://api.clsfy.me/v1/clsfy/segment-requests

Parameters

Parameter	Type	Required	Description
name	string	Required	Display name for the segment. Used to identify it in your DSP and in reporting.
prompt	string	Conditional	A natural language description of your target audience. Can be a short descriptive brief, a brand story, or a hypothetical article your ideal audience would read. At least one of prompt or example_urls is required.
example_urls	array[string]	Conditional	URLs representing the type of content your target audience reads. Classify uses these as seed content to find similar pages at scale. At least one of prompt or example_urls is required.
block_tlds	array[string]	Optional	Domains to exclude from the segment — useful for blocking competitor sites or specific publishers.
client_id	string	Optional	Defaults to the client associated with your API key. Only needed if your key manages multiple clients.

Request

curl

curl -X POST "https://api.clsfy.me/v1/clsfy/segment-requests" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Snowblower Buyers",
    "prompt": "Homeowners researching and purchasing snowblowers for winter driveway maintenance",
    "example_urls": [
      "https://www.popularmechanics.com/home/tools/a29489351/best-snow-blowers/",
      "https://www.thespruce.com/snow-blowers-and-snow-shovels-4118591"
    ],
    "block_tlds": ["craftsman.com"]
  }'

Python

import requests

response = requests.post(
    "https://api.clsfy.me/v1/clsfy/segment-requests",
    headers={
        "X-API-Key": "<your_api_key>",
        "Content-Type": "application/json",
    },
    json={
        "name": "Snowblower Buyers",
        "prompt": "Homeowners researching and purchasing snowblowers for winter driveway maintenance",
        "example_urls": [
            "https://www.popularmechanics.com/home/tools/a29489351/best-snow-blowers/",
            "https://www.thespruce.com/snow-blowers-and-snow-shovels-4118591",
        ],
        "block_tlds": ["craftsman.com"],
    },
)

segment = response.json()
print(segment["id"])  # e.g. 61

Response

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

{
  "id": 61,
  "name": "Snowblower Buyers",
  "status": "pending",
  "created_date": "2026-02-12T22:09:38Z",
  "processed_date": null
}

---

Get a segment

Retrieves a segment by ID. Use this to check build status while your segment is processing.

GET https://api.clsfy.me/v1/clsfy/segment-requests/{id}

Parameter	Type	Description
id	integer	The segment ID returned at creation

curl

curl "https://api.clsfy.me/v1/clsfy/segment-requests/61" \
  -H "X-API-Key: <your_api_key>"

Python

import requests

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

segment = response.json()
print(segment["status"])  # "pending" | "processing" | "complete" | "failed"

---

List your segments

Returns all segments associated with your API key.

GET https://api.clsfy.me/v1/clsfy/segment-requests

curl

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

Python

import requests

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

segments = response.json()

Returns an array of segment objects:

[
  {
    "id": 61,
    "name": "Snowblower Buyers",
    "status": "complete",
    "created_date": "2026-02-12T22:09:38Z",
    "processed_date": "2026-02-12T23:51:14Z"
  },
  {
    "id": 60,
    "name": "Home Improvement Weekend Warriors",
    "status": "processing",
    "created_date": "2026-02-12T21:00:00Z",
    "processed_date": null
  }
]

---

Polling for completion

Poll GET /v1/clsfy/segment-requests/{id} until status is "complete" or processed_date is not null. There's no need to poll more frequently than once per minute — segments take 1–2 hours to build.

If status is "failed", contact your Classify representative.

Once complete, proceed to Segment Activation to get your deal ID for DSP targeting.

Python

import requests
import time

def wait_for_segment(segment_id: int, api_key: str, poll_interval: int = 60):
    """Poll until a segment finishes building. Returns the completed segment object."""
    url = f"https://api.clsfy.me/v1/clsfy/segment-requests/{segment_id}"
    headers = {"X-API-Key": api_key}

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

        if segment["status"] == "complete":
            print(f"Segment {segment_id} is ready.")
            return segment
        elif segment["status"] == "failed":
            raise RuntimeError(f"Segment {segment_id} failed to build.")

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

---

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": "Segment with ID 999 not found"
}

HTTP status codes

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