API documentation

Public API · v1

Track clicks. Record conversions.

ClinXtra exposes two public endpoints: a tracked redirect that mints a signed click_id, and a postback endpoint that records the conversion when your funnel completes. Endpoints are edge-served, idempotent on click_id, and accept either GET query strings or POST JSON bodies.

1. Tracked click endpoint

GEThttps://clinxtra.cybergen.ai/api/public/c/{offer_id}

Records a click on an offer, runs fraud checks, and 302-redirects the visitor to the offer's CTA URL with a signed click_id token appended. Tokens are HMAC-signed and expire after 30 days.

offer_idrequired

UUID of the offer (path param).

lead

Optional UUID of the originating lead (query).

Responses: 302 redirect (success or capped) · 400 invalid offer id · 403 blocked by fraud rules · 404 offer unavailable.

2. Conversion postback

GETPOSThttps://clinxtra.cybergen.ai/api/public/p

Fire this when the user converts. The click_id token returned by the click endpoint authenticates the call. Replays are idempotent — only the first conversion is recorded; subsequent calls return already_converted: true.

click_idrequired

Signed token from the click redirect URL.

payout_cents

Integer payout in cents. Optional but recommended.

ref

Your network's transaction id, stored for reconciliation.

(any)

Extra params are stored verbatim in the conversion payload (JSONB).

GET (macro setup)

POST (server-to-server)

curl -X POST "https://clinxtra.cybergen.ai/api/public/p" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "{click_id}",
    "payout_cents": 2500,
    "ref": "{transaction_id}"
  }'

Successful response

{
  "ok": true,
  "signed": false,
  "conversion_id": "b1e1c8ad-…",
  "already_converted": false
}

3. Signed requests (HMAC-SHA256)

Signed postbacks are auto-approved on receipt — no manual review. Unsigned postbacks still record the conversion, but are queued in pending until an admin approves them. To sign a request, ask your account manager for an API key pair, then attach three headers:

x-clinxtra-key-idrequired

The public key id assigned to your tenant.

x-clinxtra-timestamprequired

Unix epoch seconds. Must be within ±5 minutes of server time.

x-clinxtra-signaturerequired

Hex HMAC-SHA256 of {timestamp}.{payload} using your secret.

Payload is the raw POST body, or — for GET — the URL query string without the leading ?.

# Signed POST (server-to-server, auto-approves the conversion)
TS=$(date +%s)
BODY='{"click_id":"{click_id}","payout_cents":2500,"ref":"tx-123"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl -X POST "https://clinxtra.cybergen.ai/api/public/p" \
  -H "Content-Type: application/json" \
  -H "x-clinxtra-key-id: $KEY_ID" \
  -H "x-clinxtra-timestamp: $TS" \
  -H "x-clinxtra-signature: $SIG" \
  -d "$BODY"

4. Errors & status codes

Status	Meaning
`200`	Conversion recorded (or already recorded — check already_converted).
`302`	Click endpoint: redirect to the offer destination.
`400`	Missing or malformed click_id / offer_id.
`401`	click_id is invalid, expired, or signature did not verify.
`403`	Tenant mismatch between signed key and click_id, or click blocked by fraud rules.
`404`	Offer is unavailable (paused, expired, or deleted).
`500`	Server error — safe to retry with the same click_id.

Responses are JSON with cache-control: no-store. Need help? Contact your account manager or email partners@clinxtra.cybergen.ai.