> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# End users API

> Manage end-user records over the /api/endusers endpoints, from single reads and writes to batch import.

The End users API reads and writes the end-user records in your organization. Every request needs an organization-scoped key that holds the **End-users** permission. Send it as `Authorization: Bearer YOUR_API_KEY`. See [API authentication](/docs/developer/authentication).

## Operations

| Operation                                                | Endpoint                           |
| -------------------------------------------------------- | ---------------------------------- |
| [List end users](/docs/developer/api/end-users/list)          | `GET /api/endusers`                |
| [Create an end user](/docs/developer/api/end-users/create)    | `POST /api/endusers`               |
| [Batch-create end users](/docs/developer/api/end-users/batch) | `POST /api/endusers/batch`         |
| [Get an end user](/docs/developer/api/end-users/get)          | `GET /api/endusers/{endUserId}`    |
| [Update an end user](/docs/developer/api/end-users/update)    | `PATCH /api/endusers/{endUserId}`  |
| [Delete an end user](/docs/developer/api/end-users/delete)    | `DELETE /api/endusers/{endUserId}` |

## The end-user record

Responses return this public shape.

<ResponseField name="_id" type="string">
  The record ID, used in the by-ID endpoints.
</ResponseField>

<ResponseField name="name" type="string">
  Display name.
</ResponseField>

<ResponseField name="email" type="string">
  Email, normalized on write.
</ResponseField>

<ResponseField name="phone" type="string">
  Phone, normalized on write.
</ResponseField>

<ResponseField name="tags" type="string[]">
  Free-form tags.
</ResponseField>

<ResponseField name="origin" type="string">
  `inbound`, `imported`, or `manual`.
</ResponseField>

<ResponseField name="channelIdentifiers" type="object">
  Per-channel identifiers on this profile.
</ResponseField>

<ResponseField name="consent" type="object">
  Per-channel consent state.
</ResponseField>

<ResponseField name="createdAt" type="number">
  Creation time, milliseconds since epoch.
</ResponseField>

<ResponseField name="lastSeenAt" type="number">
  Last activity time, milliseconds since epoch.
</ResponseField>

## Errors

Error responses use the shape `{ "error": "…", "code": "…" }`.

| Status | Code                                              | Cause                                                                      |
| ------ | ------------------------------------------------- | -------------------------------------------------------------------------- |
| `400`  | `INVALID_BODY`                                    | Malformed body, or an unknown or missing `origin` on create and batch      |
| `400`  | `INVALID_ORIGIN`                                  | The `origin` query value on list is not `inbound`, `imported`, or `manual` |
| `400`  | `INVALID_URL`                                     | The by-ID path does not match `/api/endusers/{endUserId}`                  |
| `400`  | `CREATE_FAILED`, `UPDATE_FAILED`, `DELETE_FAILED` | The write failed, including a duplicate email or phone on update           |
| `401`  | `UNAUTHORIZED`                                    | Missing, invalid, or revoked key                                           |
| `403`  | `FORBIDDEN`                                       | Key lacks the **End-users** permission                                     |
| `404`  | `NOT_FOUND`                                       | No record matches the ID                                                   |
| `405`  | `METHOD_NOT_ALLOWED`                              | The method is not supported on this route                                  |
| `409`  | `DUPLICATE_ENDUSER`                               | Create only. Email or phone already exists on another record               |

## Related pages

* [API authentication](/docs/developer/authentication)
* [End user profiles](/docs/guides/end-users/profiles)
* [Import and export end users](/docs/guides/end-users/import-and-export)