Skip to main content
POST
/
v1
/
identify
import { EmitKit } from '@emitkit/js';
const client = new EmitKit('emitkit_xxxxxxxxxxxxxxxxxxxxx');

await client.identify({
  user_id: 'user_123',
  properties: {
    email: 'john@example.com',
    name: 'John Doe',
    plan: 'pro'
  },
  aliases: ['john@example.com', 'johndoe']
});
{
  "success": true,
  "data": {
    "id": "user_identity_xxxxxxxxxxxxxxxxxxxxx",
    "userId": "user_123",
    "properties": {
      "email": "john@example.com",
      "name": "John Doe",
      "plan": "pro"
    },
    "aliases": {
      "created": [
        "john@example.com",
        "johndoe"
      ]
    },
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Authorizations

ā€‹
Authorization
string
header
required

API key authentication. Format: emitkit_xxxxxxxxxxxxxxxxxxxxx

Create API keys in your EmitKit dashboard. Keys are scoped to a specific organization and project.

Body

application/json
ā€‹
user_id
string
required

Unique identifier for the user. This is your internal user ID. Must be consistent across identify calls for the same user.

Required string length: 1 - 255
Example:

"user_123"

ā€‹
properties
object

Custom properties about the user. Any valid JSON structure is accepted. Properties are replaced on each identify call, not merged. Common properties: email, name, plan, createdAt, etc.

Example:
{
  "email": "john@example.com",
  "name": "John Doe",
  "plan": "pro",
  "signupDate": "2025-01-15"
}
ā€‹
aliases
string[]

Array of alternative identifiers for this user (emails, usernames, external IDs). Aliases allow you to reference users by multiple identifiers in your events. Duplicate aliases are silently ignored and returned in the response.

Maximum array length: 50
Required string length: 1 - 255
Example:
[
  "john@example.com",
  "johndoe",
  "john.doe@company.com"
]

Response

User identified successfully (created or updated)

ā€‹
success
boolean
required

Indicates successful user identification

Example:

true

ā€‹
data
object
required
ā€‹
requestId
string<uuid>
required

Unique request identifier for debugging and support

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"