AdTarget REST API

The AdTarget REST API lets your backend fire business events for Telegram leads: purchases, CRM milestones, custom events, and cold-lead conversions when you already know the site/channel context.

Base URL: https://adtarget.io/api/v1

Two separate surfaces

AdTarget deliberately separates browser-like tracking from privileged backend events:

Flow	Surface	API key
Pageview / visit	`POST /backend/track/init`	No
Deferred `_fbp` patch	`POST /backend/track/update-fbp`	No
Telegram invite click + redirect	`GET /backend/track/invite`	No
Lead, Purchase, Custom, CRM/broker event	`POST /api/v1/events/conversion`	Yes
Event for an existing Telegram lead	`POST /api/v1/leads/{telegramUserId}/events`	Yes
Value submitted after conversion	`POST /api/v1/leads/{telegramUserId}/conversions/{conversionId}/value`	Yes

Use the keyless tracker-compatible endpoints for first-party reverse proxies. They mirror track.js: the websiteId is public, requests are domain-validated/rate-limited, and no private account secret is needed.

Use the account-wide API key only for backend events that should never come from browser code.

Never expose ADTARGET_API_KEY to browser code. Pageviews and invite clicks do not need it.

When to use the API

You want to trigger Purchase events from your CRM, broker, payment provider, or webhook.
You need custom events for business actions such as Deposit, Withdrawal, or Upgrade.
You want to fire events for an existing Telegram user and let AdTarget infer the site/channel from that user’s funnel history.
You want to fire a cold backend event and can supply siteId/websiteId, channelId, and attribution fields yourself.

See Server-side tracking if you are replacing track.js with a reverse proxy. That guide uses /backend/track/* for visits and invite clicks, then /api/v1/events/conversion only for purchases/custom backend events.

Quick example

Fire a Purchase event for an existing lead:


curl -X POST https://adtarget.io/api/v1/events/conversion \
  -H "Authorization: Bearer atk_live_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "telegramUserId": 1234567890,
    "eventType": "Purchase",
    "value": 97.00,
    "currency": "USD",
    "pii": {
      "email": "lead@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }'

Response:


{
  "conversionId": "j97abc123...",
  "capiStatus": "pending",
  "coldLead": false,
  "sends": [{ "sendId": "kn7...", "platform": "meta" }]
}

For existing Telegram leads, account-scoped keys resolve the site, channel, visit, and session from the lead history. If a recent matching Purchase already exists, AdTarget updates or reuses that conversion instead of dispatching a duplicate. Check the Events tab in your dashboard or query GET /api/v1/leads/{telegramUserId} to confirm.

Next steps

Authentication — how Bearer tokens work
Endpoints — full reference with curl / JS / Python examples
Idempotency — safe retries with Idempotency-Key
Errors & Rate Limits — response codes and retry behaviour
Server-side / Reverse Proxy — replace the tracker entirely