> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# External ID support on the End Users API

The End Users API now supports an `external_id` field, letting custom-channel integrations identify end users by their own stable identifier (for example a CRM contact ID or a phone number) across conversations.

## What's new

* **Look up by external ID.** `GET /v2/end-users/?external_id=<value>` returns the matching end user, or `404` if no mapping exists.
* **Idempotent create.** `POST /v2/end-users/` accepts an optional `external_id`. If the identifier is already mapped, the existing end user is returned with `200`. A new end user returns `201`. Safe to retry.
* **Set, update, or clear on PATCH.** `PATCH /v2/end-users/{end_user_id}` accepts `external_id` to set or change the value. Passing `null` clears the mapping and frees the value for reuse. `409` is returned if the value is already assigned to a different end user.

## Constraints

* Maximum 36 characters; `<` and `>` characters are not allowed.
* Values are stored and matched case-insensitively.
* `external_id` is unique per AI Agent.
* Available for custom channel integrations only (V1).

## Get started

* [End Users API overview](/reference/end-users/overview)
* [Reuse end users across conversations with external\_id](/reference/end-users/getting-started#reuse-end-users-across-conversations-with-external_id)
* [Identify end users with a stable external ID — developer guide](/reference/end-users/developer-guide#identify-end-users-with-a-stable-external-id)