Skip to content
IForevents Docs
IForevents Docs
HomeDashboardGitHubPrivacyTermsSecurityIntroduction
Support and SLA

Create or update a tracked user

POST
/v1/events/identify

Upserts the profile identified by custom_id: your own id for the person, the same value track and batch take in X-User-Id. Events sent under that id before the first identify already belong to the profile; identify only adds the name, e-mail and properties. It stores no event and does not count against the plan's events.

Authorization

projectKey
X-Project-Key<token>

Public write key. Safe to embed in client applications; grants ingest only. Paired with X-Project-Secret it also grants read-only programmatic access.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/events/identify" \  -H "Content-Type: application/json" \  -d '{    "custom_id": "user_12345",    "email": "[email protected]",    "name": "Ada Lovelace",    "properties": {      "plan": "pro"    }  }'
{  "user": {    "created_at": "2026-09-13T12:30:45Z",    "custom_id": "user_12345",    "email": "[email protected]",    "events_count": 42,    "name": "Ada Lovelace",    "project_uuid": "5f1c2e7a-1c2d-4b3e-9f10-1a2b3c4d5e6f",    "properties": {      "plan": "pro"    },    "updated_at": "2026-09-13T12:30:45Z",    "uuid": "00000000-0000-0000-8b20-15635fadf462"  }}
anonymous_id?string

The device's anonymous id (anon_...), kept after identify so destinations can merge the anonymous history. Forwarded to IForevents Cloud destinations; not stored.

context?

What the SDK knows about the device and app. Unknown members are dropped, strings are cut at 256 characters, and a context that does not decode is ignored. Forwarded to IForevents Cloud destinations; not stored.

custom_id*string

Your identifier for the user; identifies the same profile on every call.

email?string
message_id?string

The SDK's id for the call, a UUID made once per call and kept across retries (on a batch, each item carries its own). The api deduplicates on it for 24 hours: a resent call with the same id and content is answered as accepted and stored once; the same id with different content is refused with 409 event_id_conflict. Forwarded to IForevents Cloud destinations.

name?string
phone_number?string
properties?
sent_at?string

When the SDK sent the request (RFC 3339), on the device's clock. Forwarded to IForevents Cloud destinations; not stored.