Create an end user

import requests
url = "https://example.ada.support/api/v2/end-users/"
payload = { "profile": {
        "first_name": "Maria",
        "last_name": "Santos",
        "email": "maria@example.com",
        "language": "pt-BR",
        "metadata": {
            "region": "latam",
            "plan_type": "enterprise"
        },
        "sensitive_metadata": { "fields": {
                "auth_token": "eyJhbGciOiJIUzI1NiIs...",
                "session_id": "sess_abc123"
            } }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "end_user_id": "5f7e0e2c1e7c7e000f0f9c3a",
  "profile": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "display_name": "Ada Lovelace",
    "avatar": "https://example.com/avatars/ada.png",
    "email": "ada.lovelace@ada.cx",
    "language": "en-US",
    "metadata": {
      "example_key1": "example_string_value",
      "example_key2": true,
      "example_key3": 123
    },
    "system_properties": {
      "sunshine_user_id": "5f7e0e2c1e7c7e000f0f9c3a"
    }
  },
  "created_at": "2020-09-20T00:00:00+00:00",
  "updated_at": "2020-09-20T00:00:00+00:00"
}

Create a new end user with optional profile data and sensitive metadata. Use this endpoint to establish an end user with context (language, metadata, sensitive metadata) before starting a conversation via POST /v2/conversations/. This ensures the AI Agent has full user context from the first turn. Available for custom channel (Conversations API) integrations. End users created through this endpoint that are not associated with a conversation within 24 hours of creation are automatically deleted.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

profileobjectOptional

The end user’s profile information. Optional — omitting profile creates a blank end user.

Response

Created

end_user_idstringRead-only

The unique Ada-generated id for the end user

profileobject

The end user's profile information

created_atstringRead-only

The date and time the end user was created

updated_atstringRead-only

The date and time the end user was updated

Errors

400

Bad Request Error

401

Unauthorized Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error