AdTarget REST API

The AdTarget REST API lets your backend fire every event the tracker JS supports — visits, invites, joins, custom events, and purchases — directly from your server.

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

When to use the API

You run a reverse proxy (Cloudflare Worker, Nginx, Next.js middleware) and want to skip loading track.js entirely.
You want to trigger Purchase events from your CRM, broker, or webhook (no manual dashboard click).
You need custom events for any business action (e.g. Deposit, Withdrawal, Upgrade).
You want to fire events for leads from non-tracked sources (organic Telegram, other channels).

Feature parity with the tracker

Every behaviour of the tracker is rejouable through the API:

Tracker capability	API equivalent
`POST /track/init`	`POST /api/v1/events/visit`
`POST /track/update-fbp` (deferred fbp)	`POST /api/v1/events/update-fbp`
`GET /track/invite` (click + invite + redirect)	`POST /api/v1/events/invite`
Telegram join → conversion → CAPI	`POST /api/v1/events/conversion`
Purchase value submitted from dashboard	`POST /api/v1/leads/{telegramUserId}/conversions/{conversionId}/value`
Custom events configured in the dashboard	`POST /api/v1/events/conversion` with `eventType: "Custom"`

See Server-side tracking for a worked example of fully replacing the tracker.

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,
    "channelId": "-1001234567890",
    "eventType": "Purchase",
    "value": 97.00,
    "currency": "USD",
    "pii": {
      "email": "lead@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "fbc": "fb.1.1700000000.AbCdEfGh",
    "clientIp": "203.0.113.42",
    "userAgent": "Mozilla/5.0 ..."
  }'

Response:


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

The conversion is enqueued for Meta CAPI dispatch immediately. 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