Skip to main content
POST
Identify

Description

Create or update a user profile. Call this when a user signs up, logs in, or when you want to update their attributes. Short alias: POST /v1/i When to use:
  • User signs up or logs in → call identify with their userId and traits
  • User updates their profile (name, email, plan) → call identify with updated traits
  • Merging anonymous pre-signup activity → call identify with both userId and anonymousId
What happens:
  1. If userId is new → creates a new user profile
  2. If userId exists → merges traits with existing profile (additive, not replace)
  3. If both userId and anonymousId are provided → links all anonymous events to the identified profile

Headers

string
required
HTTP Basic Auth. See Events Authentication.
string
default:"application/json"
required
Must be application/json.

Body

string
Your application’s stable identifier for this user. At least one of userId or anonymousId is required.
string
Anonymous ID from the SDK. Required if userId is not provided. Providing both triggers identity merge.
object
Key-value user attributes to set or update (for example email, name, plan).
string
When the identify happened, as ISO 8601. Defaults to server time if omitted.
string
Deduplication ID. SDKs generate this automatically.
object
Optional environment metadata (device, OS, app, IP, locale, and more). SDKs populate this automatically. See Context Object.

Response

Successful requests return HTTP 200 with an empty JSON object.