SourceTrack REST API

Get an API token

1. In SourceTrack, open Settings > Advanced > Server API Tokens.
2. Click Generate API Token, name it and tick the scopes it needs.
3. Copy the token. It is shown only once.

Only the site owner or a workspace admin can create one. API tokens are part of every paid plan and the trial, not the Free plan. A site can have up to 25 active tokens.

Send the token in the header Authorization: Bearer YOUR_API_KEY. The token decides which site you work with, so do not send a site key or site id. Keep it on your server, never in browser code.

A token can do only what its scopes allow. No scope includes another, so tick each one you need.

To connect an AI assistant instead, see the MCP guide.

Make your first request

This call answers with the site the token belongs to. It needs the read:diagnostics scope.

curl "https://api.srctk.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Every answer has success, data and error. Many errors also carry a code, such as INVALID_PARAMETER. A number that cannot be measured is left out and named in omitted, not filled in with 0.

Send an event from your server

Use POST /api/server/event with the write:events scope for orders, sign-ups or deal stages your backend knows about. To link the event to a visit, send the visitor id from the browser (sourcetrack.getToken()) as anonymous_id.

curl -X POST "https://api.srctk.com/api/server/event" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "purchase",
    "anonymous_id": "VISITOR_ID_FROM_THE_BROWSER",
    "event_id": "order-10029",
    "order_id": "10029",
    "value": 149.00,
    "currency": "USD"
  }'

• No duplicates: send an event_id, such as the order id. A repeat with the same id is answered "duplicate": true and not stored again. Without one, a retry is stored twice.
• Value: send value with a 3-letter currency. Leave both out if you do not know the value. Do not send 0 for "unknown".
• Counting: an event with a value, a conversion_type or the name $conversion is a conversion. Any other event counts toward your monthly page view allowance.
• If it fails: a 503 means nothing was stored. Retry after the seconds in the Retry-After header.

Update contacts and correct conversions

• Contacts: POST /api/v1/contacts (write:contacts) with an email, plus anonymous_id or external_id to tie the person to a visit or your own user id. Sending the same email again updates the contact.
• Corrections: PATCH /api/v1/conversions/:event_id (write:conversion_edits) with the value the order is still worth. After a 40 refund on a 100 order, send 60. DELETE reverses all of its revenue. Stripe and Shopify conversions are changed by refunding them there.

All endpoints

Window routes take days (1 to 90, default 30), or from and to dates. The full reference with every field is in the app at app.sourcetrack.ai/developers/api.

What the error answers mean

• 400: a field or parameter is invalid. The message names it.
• 401: the token is missing or unknown. Check the Authorization header.
• 402: the plan does not include API access, the subscription is inactive, or the account email is not verified yet.
• 403: the token does not have the scope this endpoint needs.
• 429: too many requests. Wait a little, then retry.
• 503: a temporary problem on our side. Nothing was stored. Retry shortly.

Rate limits

Limits at the time of writing: 100 requests a minute per IP address on most endpoints, 100 a minute per token on the stats endpoints, and 10,000 a minute per IP address on POST /api/server/event. We may change them.

Privacy and data requests

The contact routes return counts and ids, not email addresses, names or IP addresses. To erase a visitor or answer an access request, use the privacy tools in your SourceTrack settings, not an API token. See our privacy policy.