Identify User

Creates or updates the Organization-scoped identity for userId (user_id is its old name and still works). Properties are merged into the stored ones (new values replace old ones; keys you leave out are kept), and each alias moves to this identity.

POST/v1/identify

Authorization

AuthorizationBearer token (EmitKit API key) · headerrequired

EmitKit API key in the Authorization header as Bearer emitkit_…

X-API-KeyAPI key · headerrequired

EmitKit API key beginning with emitkit_.

Request body

requiredapplication/json

aliasesstring[]

Other ids or emails this user is known by in your events' userId

propertiesobject

Merged into the identity's properties

default: {}

userIdstringrequired

Your id for the user

min length 1

user_idstringdeprecated

Deprecated: the old name of userId, still accepted in its place. If both are sent they must match.

min length 1

Responses

200

The identity was created or updated.

dataobjectrequired

Show properties

aliasesobjectrequired

Show properties

createdstring[]required

idstringrequired

propertiesobjectrequired

updatedAtstring<date-time>required

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

userIdstringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

400

The request does not match the operation contract.

codestringrequired

Stable: switch on this, not on error or message.

detailsobject[]required

Show properties

Array of object

codestring

min length 1

messagestringrequired

min length 1

pathstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

errorstringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

401

Authentication credentials are missing or invalid.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

403

The API key lacks this operation's scope (a read-only key can only read), isn't bound to a Project, or its Project was deleted.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

What's missing, e.g. the scope the operation needs.

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

413

The request body exceeds the public API's 1 MiB limit.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

Allowed:Request body exceeds the 1 MiB limitEvent exceeds the 16 KB storage limit

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

429

The authenticated principal exceeded its rate limit.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

500

The identity could not be written.

codestringrequired

Stable: switch on this, not on error or message.

errorstringrequired

messagestringrequired

requestIdstring<uuid>required

matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

successbooleanrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (EmitKit API key)Remember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -X POST "https://api.emitkit.com/v1/identify" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "aliases": [
    "string"
  ],
  "properties": {},
  "userId": "string",
  "user_id": "string"
}'

const response = await fetch("https://api.emitkit.com/v1/identify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"aliases\": [\n    \"string\"\n  ],\n  \"properties\": {},\n  \"userId\": \"string\",\n  \"user_id\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://api.emitkit.com/v1/identify",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"aliases\": [\n    \"string\"\n  ],\n  \"properties\": {},\n  \"userId\": \"string\",\n  \"user_id\": \"string\"\n}",
)

Response

{
  "data": {
    "aliases": {
      "created": [
        "string"
      ]
    },
    "id": "string",
    "properties": {
      "property1": null,
      "property2": null
    },
    "updatedAt": "2019-08-24T14:15:22Z",
    "userId": "string"
  },
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": true
}

{
  "code": "validation_error",
  "details": [
    {
      "code": "string",
      "message": "string",
      "path": [
        "string"
      ]
    }
  ],
  "error": "Validation error",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "unauthorized",
  "error": "Unauthorized",
  "message": "Invalid or missing authentication credentials",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "forbidden",
  "error": "Forbidden",
  "message": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "payload_too_large",
  "error": "Payload too large",
  "message": "Request body exceeds the 1 MiB limit",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "rate_limited",
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}

{
  "code": "internal_error",
  "error": "Failed to identify user",
  "message": "The identity could not be written",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "success": false
}