---
updatedAt: 2025-11-07T16:20:50.000Z
agentTools:
  projectIndex: https://developers.heap.io/llms.txt
---

# 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.

> 🚧 If your Heap data is in an EU datacenter, the correct endpoint is:
>
> <https://c.eu.heap-api.com/api/v1/identify> (**NOT** heapanalytics.com)

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "server-side-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://heapanalytics.com/"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/api/v1/identify": {
      "post": {
        "summary": "Identify",
        "description": "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.",
        "operationId": "identify-1",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "app_id",
                  "user_id",
                  "identity"
                ],
                "properties": {
                  "app_id": {
                    "type": "string",
                    "description": "The environment ID of your Main Production project."
                  },
                  "user_id": {
                    "type": "string",
                    "description": "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": {
                    "type": "string",
                    "description": "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": {
                    "type": "string",
                    "description": "ISO8601 e.g. \"2017-03-10T22:21:56+00:00\". Defaults to the current time if not provided."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "curl \\\n  -H 'Content-Type: application/json' \\\n  -X POST \\\n  -d '{\n    \"app_id\": \"11\",\n    \"identity\": \"user@example.com\",\n    \"user_id\": \"1847839267195673\"\n  }' \\\n  'https://heapanalytics.com/api/v1/identify'"
            }
          ],
          "samples-languages": [
            "curl"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```