Conversion Router API

OpenAPI 3.0 · 1.0.0

Send a conversion event

Call this from your server after a registration is saved. One API key belongs to one website. The page URL chooses the Meta pixel.

What to do

  1. 1 Paste the API key we sent you. It looks like ctk_… and stays in this tab only.
  2. 2 Leave Test selected. test_event: true is stored as Test and is not sent to Meta.
  3. 3 Press Execute. HTTP 202 with "status": "test" means the connection works.
POST /api/v1/events https://tracker.sabtrack.com

Required. Execute returns 401 until this is filled in.

This body is a connection test. It is not sent to Meta.

Source URL https://reddybooks.win/?utm_source=%7B%7Bsite_source_name%7D%7D&utm_medium=paid_social&utm_campaign=%7B%7Bcampaign.name%7D%7D&campaign_id=%7B%7Bcampaign.id%7D%7D&adset_name=%7B%7Badset.name%7D%7D&adset_id=%7B%7Badset.id%7D%7D&ad_name=%7B%7Bad.name%7D%7D&ad_id=%7B%7Bad.id%7D%7D&placement=%7B%7Bplacement%7D%7D&utm_account=reddyfashion&fbclid=PAQk9Dexample

Copy into your server

Same body as the example above. Keep the key in an environment variable, not in frontend code.

curl -X POST https://tracker.sabtrack.com/api/v1/events \
  -H "Authorization: Bearer $CONVERSION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_name": "CompleteRegistration",
  "event_id": "connection_test_1",
  "event_time": 1793952000,
  "source_url": "https://reddybooks.win/?utm_source=%7B%7Bsite_source_name%7D%7D&utm_medium=paid_social&utm_campaign=%7B%7Bcampaign.name%7D%7D&campaign_id=%7B%7Bcampaign.id%7D%7D&adset_name=%7B%7Badset.name%7D%7D&adset_id=%7B%7Badset.id%7D%7D&ad_name=%7B%7Bad.name%7D%7D&ad_id=%7B%7Bad.id%7D%7D&placement=%7B%7Bplacement%7D%7D&utm_account=reddyfashion&fbclid=PAQk9Dexample",
  "test_event": true
}'

Page URL

Send every query parameter on source_url. Pass the URL the visitor actually opened, including utm_account, fbclid, and the rest. Do not trim it down to the path.

https://reddybooks.win/u/sfT2WD2e redirects and currently drops that query string, so the next page has no utm_account or fbclid. Change the redirect so the destination keeps the original parameters. A click on https://reddybooks.win/u/sfT2WD2e?utm_account=reddyfashion&fbclid=… must land with those same parameters still attached. Until that is fixed, send the URL from before the redirect.

Landing script

Paste this on the page the ad opens, before any redirect. No API key on the page. WEBSITE_ID is the id in the dashboard website URL. The same steps are on the landing script page.

<script src="https://tracker.sabtrack.com/t.js" data-website="WEBSITE_ID" async></script>

The script runs only when the URL still has fbclid or utm_account. An empty query, /?source=pwa, and a later page such as /register send nothing.

The page cannot see its own public addresses. The script sends the full URL. v4.tracker.sabtrack.com is IPv4 only and records that visitor’s IPv4. v6.tracker.sabtrack.com is IPv6 only and records that visitor’s IPv6. Both calls share one page-load id, with the user agent. A phone that can reach only one family leaves the other field empty.

Until those two hostnames exist, add data-both="off". The script then stores whichever family reached tracker.sabtrack.com.

Keep sending the registration from your server. If that call’s URL still has fbclid or utm_account, we use it as sent. If the URL is clean, we look for one page load from the last 24 hours with the same user agent and either address. One match: fbclid, utm_account, and the ad ids are copied from the stored URL. Zero or more than one: the registration stays as received.

Moving between the stored IPv4 and IPv6 still matches. A new network is a new address, and fbclid is not a second key. Saving the first URL and sending that saved URL on the registration is what survives a new address.

The landing host has to be a Meta account domain for the website. A host such as reddybooks.win is stored and marked rejected, and a later registration does not use it.

Landing page load

On the first server render of the page the browser opened, after any redirect, you can also POST /api/v1/page-loads with the same API key. The landing script above does this from the browser, so a site that has the tag does not also need this call. This stores the landing URL. It is not a Meta PageView and it is not sent to Meta.

Send it only when that URL still has fbclid or utm_account. Do not send https://reddybooks.win/register or https://reddybooks.win/?source=pwa.

If a later registration has no ad parameters, we look up page loads from the last 24 hours with the same IP and user agent. One match: we attach that page load’s fbclid, utm_account, and ad ids. Zero or more than one: we send the registration as received.

{
  "page_load_id": "load-7c2a9e14-1b0d-4f6a-9c33-0a1e5d8b2f90",
  "event_time": 1794833900,
  "source_url": "https://reddybooks.win/?utm_source=%7B%7Bsite_source_name%7D%7D&utm_medium=paid_social&utm_campaign=%7B%7Bcampaign.name%7D%7D&campaign_id=%7B%7Bcampaign.id%7D%7D&adset_name=%7B%7Badset.name%7D%7D&adset_id=%7B%7Badset.id%7D%7D&ad_name=%7B%7Bad.name%7D%7D&ad_id=%7B%7Bad.id%7D%7D&placement=%7B%7Bplacement%7D%7D&utm_account=reddyfashion&fbclid=PAQk9Dexample",
  "client_ip_address": "49.36.208.137",
  "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15"
}

Request body

Content-Type: application/json. Use the same event_id as the browser pixel eventID.

FieldTypeRequiredDescription
event_namestringyesCompleteRegistration for a finished signup.
event_idstringyesYour id for this registration, max 255 characters. Use the same value as the browser pixel eventID. A repeat of the same id is not sent to Meta again. A real event may reuse an id that was only used with test_event.
event_timeintegeryesUnix time in seconds when the user registered. Not milliseconds. Within the last 7 days, and not more than 10 minutes in the future.
source_urlstringyesThe full page URL the visitor landed on, with every query parameter still attached (utm_account, fbclid, and the rest). Do not drop or rebuild the query string. The host must be a domain registered for this API key. A redirect such as https://reddybooks.win/u/sfT2WD2e must keep the original query string on the destination. If it strips those parameters, send the URL from before the redirect.
test_eventbooleannoDefaults to false. true stores the call as a Test in the dashboard and does not send it to Meta. Omit it, or send false, for a real registration.
user_dataobjectnoOptional. client_ip_address and client_user_agent should be sent here. If they are missing, we copy client_ip_address and client_user_agent from the source_url query string. fbc is built from fbclid the same way. A value sent in this object is kept.
custom_dataobjectnoOptional. currency is a 3-letter code such as INR. value is a number. At most 50 keys.

Responses

Every response includes an X-Request-ID header. Quote it if you ask us to look up a call.

Other 5xx responses and timeouts were not confirmed. Retry the identical body. A 4xx other than 429 was not stored; fix it and you may reuse the same event_id.

OpenAPI JSON