Pixel Registration
Before generating pixel code, register a campaign to get a campaign ID. This ID links all pixel loads back to a single campaign or property for reporting.
Terminology
In Classify's pixel system, a "campaign" is a tracking configuration — not a DSP campaign. Each pixel campaign gets a unique ID that links all pixel loads for reporting. You'll typically create one pixel campaign per DSP campaign you want to track.
The campaign object
{
"id": 609,
"name": "H1 2026 EV Campaign",
"use_case": "campaign_optimization",
"description": "Classify curation deal tracking for EV segment",
"created_date": "2026-02-12T20:33:44Z",
"last_updated_date": "2026-02-12T20:33:44Z"
}
| Field | Type | Description |
|---|---|---|
id | integer | Unique campaign ID. Used in pixel code and reporting. |
name | string | Display name for the campaign or property |
use_case | string | How this pixel will be used. See Use cases. |
description | string | null | Optional description |
created_date | string (ISO 8601) | When the campaign was registered |
last_updated_date | string (ISO 8601) | When the campaign was last modified |
Use cases
| Value | Description |
|---|---|
campaign_optimization | Tracking delivery of a Classify curation deal or segment for optimization |
campaign_reporting | Post-delivery reporting for any programmatic campaign |
publisher_bot_detection | Detecting bot, agent, and non-human traffic on a publisher property |
publisher_agent_targeting | Monitoring AI agent access patterns for monetization or content strategy |
other | Other use cases not listed above |
The use_case determines what reporting is available. Campaign use cases (campaign_optimization, campaign_reporting) produce campaign reports. Publisher use cases (publisher_bot_detection, publisher_agent_targeting) produce publisher reports.
Register a campaign
POST https://api.clsfy.me/v1/pixel/campaigns
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Required | Display name for the campaign or property |
use_case | string | Required | One of the use case values above |
description | string | Optional | Free-text description |
Request
- curl
- Python
curl -X POST "https://api.clsfy.me/v1/pixel/campaigns" \
-H "X-API-Key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "H1 2026 EV Campaign",
"use_case": "campaign_optimization",
"description": "Classify curation deal tracking for EV segment"
}'
import requests
response = requests.post(
"https://api.clsfy.me/v1/pixel/campaigns",
headers={
"X-API-Key": "<your_api_key>",
"Content-Type": "application/json",
},
json={
"name": "H1 2026 EV Campaign",
"use_case": "campaign_optimization",
"description": "Classify curation deal tracking for EV segment",
},
)
campaign = response.json()
print(campaign["id"]) # e.g. 609
Response
{
"id": 609,
"name": "H1 2026 EV Campaign",
"use_case": "campaign_optimization",
"description": "Classify curation deal tracking for EV segment",
"created_date": "2026-02-12T20:33:44Z",
"last_updated_date": "2026-02-12T20:33:44Z"
}
List campaigns
Retrieve all campaigns associated with your API key.
GET https://api.clsfy.me/v1/pixel/campaigns
- curl
- Python
curl "https://api.clsfy.me/v1/pixel/campaigns" \
-H "X-API-Key: <your_api_key>"
import requests
response = requests.get(
"https://api.clsfy.me/v1/pixel/campaigns",
headers={"X-API-Key": "<your_api_key>"},
)
campaigns = response.json()
for c in campaigns:
print(f"{c['id']}: {c['name']} ({c['use_case']})")
Response
[
{
"id": 608,
"name": "H2 2025 Winter Campaign",
"use_case": "campaign_reporting",
"description": null,
"created_date": "2026-02-11T15:42:04Z",
"last_updated_date": "2026-02-11T15:42:04Z"
},
{
"id": 609,
"name": "H1 2026 EV Campaign",
"use_case": "campaign_optimization",
"description": "Classify curation deal tracking for EV segment",
"created_date": "2026-02-12T20:33:44Z",
"last_updated_date": "2026-02-12T20:33:44Z"
}
]
Get a campaign
GET https://api.clsfy.me/v1/pixel/campaigns/{id}
| Parameter | Type | Description |
|---|---|---|
id | integer | The campaign ID |
- curl
curl "https://api.clsfy.me/v1/pixel/campaigns/609" \
-H "X-API-Key: <your_api_key>"
Update a campaign
Update an existing pixel campaign's name, description, or use case.
PUT https://api.clsfy.me/v1/pixel/campaigns/{id}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer (path) | Required | The campaign ID to update |
name | string | Optional | Updated display name |
use_case | string | Optional | Updated use case value |
description | string | Optional | Updated description |
Only include the fields you want to change. Omitted fields are left unchanged.
Request
- curl
- Python
curl -X PUT "https://api.clsfy.me/v1/pixel/campaigns/609" \
-H "X-API-Key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "H1 2026 EV Campaign — Updated",
"description": "Updated tracking configuration"
}'
import requests
response = requests.put(
"https://api.clsfy.me/v1/pixel/campaigns/609",
headers={
"X-API-Key": "<your_api_key>",
"Content-Type": "application/json",
},
json={
"name": "H1 2026 EV Campaign — Updated",
"description": "Updated tracking configuration",
},
)
campaign = response.json()
Response
Returns the updated campaign object.
{
"id": 609,
"name": "H1 2026 EV Campaign — Updated",
"use_case": "campaign_optimization",
"description": "Updated tracking configuration",
"created_date": "2026-02-12T20:33:44Z",
"last_updated_date": "2026-03-10T14:22:15Z"
}
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": "Campaign with ID 999 not found"
}
HTTP status codes
| Status | Meaning |
|---|---|
200 OK | Success |
201 Created | Campaign created |
400 Bad Request | Invalid or missing parameters |
401 Unauthorized | Missing or invalid API key |
404 Not Found | Campaign not found |
422 Unprocessable Content | Validation error (e.g. invalid use_case value) |
429 Too Many Requests | Rate limit exceeded |