POST /v1/identify

POST /v1/identify — link an anonymous_id to a user_id.

Bind a known user_id to the visitor's anonymous_id. Persists as a special $identify event so future analysis can stitch pre- and post-login behavior together.

Auth

Required scope	ingest
Key kinds	pk_* · sk_*

Request

POST /v1/identify
Authorization: Bearer {key}
Content-Type: application/json

{
  "anonymous_id": "u_abc",
  "user_id": "user_42",
  "traits": { "email": "[e-mail]", "plan": "pro" }
}

Field	Required	Notes
anonymous_id	yes	The pseudonymous id the visitor's browser/server has been using.
user_id	yes	Your stable internal user id.
traits	no	Free-form attributes about the user, stored on the $identify event's properties.

Response

{ "ok": true }

How it integrates

After /v1/identify:

1. Subsequent events should include "user_id" on each track call. The SDK does this automatically once you call identify().

2. Historical events for the same anonymous_id remain — they're not retroactively rewritten. Joins for user-level analysis use the $identify event as a stitch point.

3. The sessions_v view sees user_id on the $identify event itself; running totals per user are easy.

Example query: time-to-conversion per user

SELECT
  user_id,
  MIN(if(event_name = '$identify', timestamp, NULL)) AS signed_up_at,
  MIN(if(event_name = 'purchase', timestamp, NULL)) AS first_purchase
FROM events
WHERE project_id = '...'
  AND timestamp > now() - INTERVAL 30 DAY
  AND user_id IS NOT NULL
GROUP BY user_id;