Identify


POST https://api.snowanalytics.app/api/identify

Attach an identity (user ID, email, name) to a Snow visitor from your server, and optionally link a Stripe customer so payments attribute back to the visit. This is the server-side counterpart to the browser’s sa.identify().

Authentication


Authorization: Bearer snw_live_your_key

Use your site’s API key, the same snw_live_… key that authenticates the Events API (it carries the identify:write scope). Legacy single-purpose ski_… identify keys are also accepted.

Request body

Field	Type	Notes
`visitor_id` / `visitorId`	string	Required. The Snow visitor to identify (≤ 64 chars).
`user_id` / `userId`	string	Required. Your stable user ID (≤ 255 chars).
`email`	string	Optional (≤ 255 chars).
`name`	string	Optional (≤ 255 chars).
`image`	string	Optional avatar URL, must be `http`/`https` (≤ 500 chars).
`stripe_customer_id` / `stripeCustomerId`	string	Optional. Link this visitor to a Stripe customer.
`site_id` / `siteId`	string	Optional. If present, it must match the key’s site.
(custom fields)	string \| number \| boolean \| null	Up to 25 extra traits (any beyond the first 25 are dropped); keys use lowercase letters, numbers, `_`, `-`.

Read the visitor’s ID in the browser with sa.getVisitorId() and pass it to your server. See Attribute revenue to visitors for the Stripe-linking flow.

Example


curl -X POST https://api.snowanalytics.app/api/identify \
  -H "Authorization: Bearer snw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "v_abc123",
    "user_id": "user_12345",
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "stripe_customer_id": "cus_123"
  }'

Responses

Status	Body	Meaning
`200 OK`	`{ "status": "success", "data": { "message": "User identified", "profileId": "…" } }`	Identity saved. When custom traits past the 25-field limit are dropped, `data.warning` describes how many.
`400 Bad Request`	`{ "error": … }`	Missing `visitor_id`, invalid identity, or invalid customer ID.
`401 Unauthorized`	`{ "error": "…" }`	Missing or invalid API key.
`403 Forbidden`	`{ "error": "Identify key site mismatch" }`	`site_id` didn’t match the key’s site.
`429 Too Many Requests`	(no body)	Rate limit exceeded.