Record an event

POST /api/tracking/collect records a page view, lead or sale for your tracking source, and forwards signed events to Meta and Google Ads.

POST/api/tracking/collect

Authorization

serverKey

AuthorizationBearer <token>

The source's server key (atr_server_...), shown to workspace administrators in Settings > Tracking. Send it from your server only, never from a page. Without it, a call is accepted only from an allowed domain, and its events are never forwarded to Meta or Google Ads.

In: header

Query Parameters

key*string

The public key of your tracking source (atr_...), shown in Settings > Tracking. You can send it in the x-adrails-key header instead.

Match^atr_[A-Za-z0-9_-]{20,80}$

Header Parameters

Origin?string

Sent by the browser. Must match an allowed domain of the source when the call is not signed with the server key.

Formaturi

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

One event. Text fields are trimmed; an empty string is refused, so leave a field out or send null instead. Unknown fields are ignored.

event_name*string

Lowercase name, 2 to 64 characters of a-z, 0-9 and _, starting with a letter. These names are sent to Meta under its standard names: page_view (PageView), view_content (ViewContent), add_to_cart (AddToCart), checkout_start (InitiateCheckout), purchase (Purchase), lead (Lead), signup (CompleteRegistration), subscription (Subscribe), trial_started (StartTrial), app_install (Install). Any other name is sent to Meta as it is.

Match^[a-z][a-z0-9_]{1,63}$

event_id*string

Your unique id for this event, such as an order id. A second event with the same id for the source is not recorded again. Use the id your Meta pixel sent for the same action, so Meta counts it once.

Length8 <= length <= 160

event_time?string

When the event happened, as an ISO 8601 date-time. Must be within the last 7 days and at most 5 minutes ahead. Defaults to the time Adrails receives the event.

Formatdate-time

action_source?string

Where the event happened.

Default"website"

Value in

"website"
"app"

value?|

The amount of the conversion, in currency, in units (89.90, not 8990). A signed event above the source's largest value per event is recorded but held back from Meta and Google Ads.

Range0 <= value <= 1000000000

currency?|

ISO 4217 currency code of value. Upper-cased by Adrails.

Length3 <= length <= 3

visitor_id?|

The visitor id the script stores in the _adrails_visitor_v1 cookie. Send it from your server to tie a sale to the visit.

Length1 <= length <= 160

landing_url?|

The page the visitor landed on. Sent to Meta as event_source_url.

Formaturi

Lengthlength <= 2000

referrer?|

The page that sent the visitor.

Formaturi

Lengthlength <= 2000

utm_source?|

Length1 <= length <= 120

utm_medium?|

Length1 <= length <= 120

utm_campaign?|

Length1 <= length <= 300

utm_content?|

Length1 <= length <= 300

utm_term?|

Length1 <= length <= 300

campaign_id?|

The ad platform's campaign id, when your ad URLs carry it.

Length1 <= length <= 200

adset_id?|

The ad set or ad group id.

Length1 <= length <= 200

ad_id?|

The ad id.

Length1 <= length <= 200

fbclid?|

Meta's click id from the landing URL.

Length1 <= length <= 300

fbc?|

Meta's click cookie (_fbc). Sent to Meta to match the conversion to the click.

Length1 <= length <= 300

fbp?|

Meta's browser cookie (_fbp). Sent to Meta to match the conversion to the browser.

Length1 <= length <= 300

gclid?|

Google's click id. Required for Google Ads to credit the conversion.

Length1 <= length <= 300

ttclid?|

TikTok's click id. Recorded for attribution.

Length1 <= length <= 300

msclkid?|

Microsoft Advertising's click id. Recorded for attribution.

Length1 <= length <= 300

user?

The customer, for matching. Adrails stores the email and external id only as keyed hashes and never stores the phone number. On a signed event sent to Meta, each is sent SHA-256 hashed.

properties?

Your own fields, kept with the event. At most 8,000 characters once serialized as JSON. Not sent to the ad platforms.

Response Body

`application/json`

curl -X POST "https://example.com/api/tracking/collect?key=<public key>" \  -H "authorization: Bearer <server key>" \  -H "content-type: application/json" \  -d '{    "event_name": "purchase",    "event_id": "order-1042",    "value": 89.9,    "currency": "EUR",    "fbc": "fb.1.1759313000000.IwAR2xYz",    "fbp": "fb.1.1759312000000.1234567890",    "gclid": "Cj0KCQjw9Kk",    "user": {      "email": "customer@example.com",      "external_id": "customer-381"    }  }'

{  "accepted": true,  "duplicate": true,  "eventId": "order-1042"}

OPTIONS/api/tracking/collect

Query Parameters

key*string

The public key of your tracking source (atr_...), shown in Settings > Tracking. You can send it in the x-adrails-key header instead.

Match^atr_[A-Za-z0-9_-]{20,80}$

Header Parameters

Origin*string

Formaturi

Response Body

curl -i -X OPTIONS "https://adrails.ai/api/tracking/collect?key=<public key>" \  -H "Origin: https://shop.example.com" \  -H "Access-Control-Request-Method: POST" \  -H "Access-Control-Request-Headers: content-type"

Empty

Record an event

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

202application/json

400application/json

403application/json

404application/json

413application/json

429application/json

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

204

403

Authorization

Query Parameters

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Query Parameters

Header Parameters

Response Body