Track API

The Track API is the primary way to feed customer behaviour into Pulse. It accepts event, identify, and alias calls.

Endpoint

POST https://zruqflqnlzriyowvhcdy.supabase.co/functions/v1/track

Authorization

Authorization: Bearer pk_<your-scoped-key>

The key must include the track:write scope.

Event payload

{
  "external_id": "user_123",
  "name": "item_added_to_cart",
  "occurred_at": "2026-05-10T14:03:00Z",
  "properties": {
    "sku": "SKU-42",
    "price": 29.00,
    "currency": "USD"
  },
  "context": {
    "ip": "203.0.113.12",
    "ua": "Mozilla/5.0…"
  }
}

Identify payload

{
  "type": "identify",
  "external_id": "user_123",
  "anon_id": "anon_8f3c2b1a-...",
  "email": "sara@example.com",
  "phone": "+234801xxxxxxx",
  "first_name": "Sara",
  "last_name": "Okafor",
  "country": "NG",
  "attributes": {
    "plan": "premium",
    "signup_source": "referral",
    "wallet_balance_ngn": 125000
  }
}

Identify calls are merged into the customer record — fields not included in the call are left untouched.

Pass anon_id on the first identify after a user signs in. The server moves every event and device token from the anonymous customer onto the identified one and deletes the orphan anon row, so historic anonymous behaviour is preserved on the real profile. The official SDKs do this for you automatically.

Alias payload

{
  "type": "alias",
  "external_id": "user_123",
  "previous_id": "user_456"
}

Use alias to merge two known external IDs (e.g. you discover the same person has two accounts). For the common anonymous → identified flow, just call identify with anon_id set — no alias call needed.

Response

{ "ok": true, "event_id": "uuid", "customer_id": "uuid" }

Bulk ingest

Wrap up to 500 events in a single request by posting { "events": [...] }. Each is validated independently; the response includes per-event success or error.

Idempotency

Include a stable idempotency_key to prevent duplicate events (e.g. on retry). Pulse keeps keys for 24 hours.