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

# Create End User

> Create a new end user in your project

End users represent the people who wear devices and are subjects of recordings. They exist in your Bota project but don't log into Bota directly.

## Authentication

Requires an [API key](/authentication) with `end_users:write` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.bota.dev/v1/end-users \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "external_id": "user_12345",
      "email": "john@example.com",
      "name": "John Doe",
      "metadata": {
        "plan": "pro",
        "department": "sales"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/end-users', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      external_id: 'user_12345',
      email: 'john@example.com',
      name: 'John Doe',
      metadata: {
        plan: 'pro',
        department: 'sales',
      },
    }),
  });

  const endUser = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.bota.dev/v1/end-users',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'external_id': 'user_12345',
          'email': 'john@example.com',
          'name': 'John Doe',
          'metadata': {
              'plan': 'pro',
              'department': 'sales',
          },
      },
  )

  end_user = response.json()
  ```
</RequestExample>

## Request Body

<ParamField body="external_id" type="string">
  Your system's unique identifier for this user. Use this to link Bota end users to users in your application.
</ParamField>

<ParamField body="email" type="string">
  User's email address.
</ParamField>

<ParamField body="name" type="string">
  User's display name.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata for your own use.
</ParamField>

## Response

Returns the created end user object.

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "eu_abc123",
    "external_id": "user_12345",
    "email": "john@example.com",
    "name": "John Doe",
    "metadata": {
      "plan": "pro",
      "department": "sales"
    },
    "created_at": "2025-01-15T10:30:00Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Invalid email format"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field         | Type   | Description                                               |
| ------------- | ------ | --------------------------------------------------------- |
| `id`          | string | Unique identifier for the end user (prefixed with `eu_`). |
| `external_id` | string | Your system's unique identifier for this user.            |
| `email`       | string | User's email address.                                     |
| `name`        | string | User's display name.                                      |
| `metadata`    | object | Arbitrary key-value metadata.                             |
| `created_at`  | string | ISO 8601 timestamp of when the end user was created.      |