---
title: "Identify"
method: POST
path: "/api/v1/identify"
---

# Identify

`POST /api/v1/identify`

This API allows you to identify users given some anonymous user_id from the Heap SDK and some known identity, such as an email address.  When this call is made, all events associated with the provided user_id are migrated to the user with the provided identity.<br><br>To protect the integrity of your data, we limit the number of identities mapped to a user_id to 1. We also limit the number of user_ids mapped to an identity to 10, over a one-month period.<br><br>As an example, if you send an identify request for user_id `123` and identity `susan`, we will drop a subsequent identify call for user_id `123` and identity `bill`.  Likewise, if you send 10 identify calls with 10 different user_ids for identity `susan` in a one-month period, the 11th user_id for identity `susan` will be ignored.

## Request body

- object
  - `app_id` string, required — The environment ID of your Main Production project.
  - `user_id` string, required — The user_id from the Heap SDK. The user_id must be the string representation of a number between zero and 2^53 - 1.
  - `identity` string, required — An identity, typically corresponding to an existing user. If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters.
  - `timestamp` string — ISO8601 e.g. "2017-03-10T22:21:56+00:00". Defaults to the current time if not provided.

## Response `200`

200

- object

## Other responses

- `400` — 400

---

[API](https://skmtc.dev/heap/apis/server-side-api.md) · [All operations](https://skmtc.dev/heap/apis/server-side-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/heap/server-side-api/revisions/6cb04521d6fa/schema)