Identities - Qonversion

An Identity binds a Qonversion User ID to your own external user ID (e.g., your auth system’s primary key). This enables consistent user tracking across devices and platforms. Identities are the preferred way to reconcile anonymous SDK users with authenticated users after login.

Key concepts

Identity ID — The external ID you control (e.g., user_42). Up to 255 characters, alphanumeric + ., _, -.
Qonversion User ID — The QON_… ID the identity is attached to.
Create shape — v3 used POST /identities/{identity_id}; v4 replaces this with POST /identities where the identity ID is sent in the body for cleaner REST semantics.
Append-only — Identities cannot be re-bound via this API. A POST that cannot bind the identity returns one of the outcomes below.

Situation	Status	`error.code`
The request repeats the same `user_id` for an identity that user already has	`422`	`already_completed`
The identity is already linked to a different user, or the repeated request omits `user_id`	`409`	`already_exists`
This user already has a different identity	`422`	`user_already_converted`
The user has purchases that conflict with another identity	`409`	`conflicting_purchases`

Available endpoints

Method	Endpoint	Description	Status
POST	`/identities`	Create an identity link	New
GET	`/identities/{identity_id}`	Get an identity by external ID	Updated — v3

Authentication

All v4 endpoints require a Secret Key. See Authentication.