Identity API (identify + alias)
Identity endpoints connect incoming events to real users in your product.
Identify
POST /api/v2/identify
Upserts a user_customer using:
external_id(stable user id in your app)identifiers(email, internal ids, billing ids, etc.)traits(profile metadata)
Example
bash
curl -X POST "/api/v2/identify" \
-H "Authorization: Bearer YOUR_EVENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_id": "user_123",
"identifiers": {
"email": "[email protected]",
"stripe_customer_id": "cus_123"
},
"traits": {
"name": "Jane Founder",
"plan": "pro"
}
}'
Alias
POST /api/v2/alias
Merges two user identities. Common use case:
- anonymous id -> known user id after signup/login
Example
bash
curl -X POST "/api/v2/alias" \
-H "Authorization: Bearer YOUR_EVENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_external_id": "anon_abc",
"to_external_id": "user_123"
}'
Conflict behavior
If an identifier is already attached to another user, the API returns a conflict error (409).