---
title: "Create an identity link"
method: POST
path: "/identities"
tags: ["Identities"]
---

# Create an identity link

`POST /identities`

Links a Qonversion anonymous user to an external identity ID.
If `user_id` is null, a new user is created and linked.
This is the mechanism for matching Qonversion anonymous users with your own user IDs.

## Headers

- `Idempotency-Key` string

## Request body

- V4IdentityCreateRequest
  - `identity_id` string, required — External identity ID to assign. Identities are append-only — posting the same identity_id twice returns 409.
  - `user_id` string, nullable — Qonversion user ID to bind. If null, a new anonymous user is created and linked.

## Response `201`

Identity created successfully.

- V4Identity
  - `object` 'identity', required
  - `id` string, required — External identity identifier.
  - `url` string, required — Canonical API path.
  - `user_id` string, required — Qonversion user identifier linked to this identity.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — User not found
- `409` — Identity already exists
- `415` — Unsupported media type
- `422` — Logical error
- `500` — Internal error
- `502` — Storage error
- `504` — Upstream timeout

---

[API](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4.md) · [All operations](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qonversion/qonversion-rest-api-v4/revisions/e3f72cf8951c/schema)