Skip to Content
Track your Telegram conversions with Meta Ads - Get started in minutes!
API ReferenceIdempotency

Idempotency

Every endpoint accepts an optional Idempotency-Key header. Use it to safely retry requests when your network or our backend has a hiccup.

How it works

  1. Your first request runs normally. We store the response body keyed on (apiKeyId, idempotencyKey).

  2. Any request with the same key within 24h returns the same response with a header:

    X-Idempotent-Replay: true

  3. Two days later the cached row is purged. Calling with the same key again will re-execute the request.

Guidelines

  • The key is string ≤ 128 characters.
  • Generate one per business action: order_<order_id>, signup_<user_id>_<timestamp>, etc.
  • Don’t reuse keys across different operations. Each key represents one logical “attempt”.
  • The Idempotency-Key is scoped per API key — two different keys may use the same string without conflict.

Example

Fire a Purchase event with retry safety:

curl -X POST https://adtarget.io/api/v1/events/conversion \
  -H "Authorization: Bearer atk_live_..." \
  -H "Idempotency-Key: order_98765" \
  -H "Content-Type: application/json" \
  -d '{ "telegramUserId": 1234567890, "channelId": "-1001234567890", "eventType": "Purchase", "value": 49.00, "currency": "USD" }'

If your network drops the response and you retry with the same Idempotency-Key, AdTarget returns the original conversionId without firing a second Meta event.

We don’t validate that the body matches the original request. If you reuse a key with a different body, you’ll get back the original response — not the new one. Always generate a fresh key for a different intent.

What gets cached

  • The full response body and HTTP status code.
  • The conversionId for forensic linking.

We do not cache anything about the request body itself. The key is the sole replay identifier.

Combined with Meta dedup

AdTarget has two layers of duplicate protection:

  1. Idempotency-Key replays the same API response for the same logical request within 24h.
  2. Conversion upsert logic reuses recent matching events for the same resolved site, Telegram user, channel, and event type. Pending/failed/skipped events are updated and retried; sent events are returned with deduplicated: true and are not sent again.

Meta CAPI also deduplicates within 48h based on event_id.

Optional visit deduplication for /track/init

POST /backend/track/init accepts an optional visitRequestId UUID in the JSON body. This is the preferred public field; the legacy gatewayRequestId name remains accepted as a backward-compatible alias. If both fields are sent, they must contain the same UUID; different values return HTTP 400. Reuse the same UUID when retrying one logical pageview: AdTarget returns the same visit and fills only attribution fields that were previously missing. Existing values and routing are never overwritten. Retries must keep the same websiteId, tempId, and sessionId; changing browser identity is rejected.

Omit visitRequestId to preserve the historical behavior: every call creates a distinct visit, including repeated calls in the same browser session. Use a new UUID for every genuinely new pageview.

Keyless direct-invite retries

POST /backend/track/direct-invite uses the body field visitRequestId (UUID), not the Idempotency-Key header. The legacy gatewayRequestId alias remains accepted. Reuse the same UUID for retries of one redirect attempt.

Repeated calls create one visit, one PageView outbox entry, and one Telegram invitation. Later calls enrich only fields that are still missing (click IDs, UTM parameters, geography, and referrer); an existing value is never overwritten. Pixel routing is fixed by the first call and cannot be changed by a retry. websiteId, tempId, and sessionId must still identify the original browser visit. Use a new UUID for a new click or redirect intent.

EndpointsErrors & Rate Limits