# Create contacts (v1)

> POST /api/v1/chatbots/:chatbotId/contacts — create or upsert one or more contacts under an agent. Chatbase-compatible: send a users array.

## POST /api/v1/chatbots/:chatbotId/contacts

Create or update contacts for an agent. This is a Chatbase-compatible endpoint: send a `users` array. Each entry is **upserted by `external_id`** — if a contact with that `external_id` already exists for the agent it is updated, otherwise a new one is created (a random `external_id` is generated when you omit it).

> **AUTH & IDS:** Authenticate with `Authorization: Bearer oc_...`. `chatbotId` is your **agent id**. Up to 1000 contacts per request.

### Body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| users | array | Yes | Array of contact objects (alias: `contacts`). 1–1000 items. |
| users[].external_id | string | No | Your stable id. Used as the upsert key. Auto-generated if omitted. |
| users[].name | string | No | Display name. Send `null` to clear. |
| users[].email | string | No | Email address. |
| users[].phonenumber | string | No | Phone number. |
| users[].stripe_accounts | array | No | Array of Stripe account references. |
| users[].custom_attributes | object | No | Key/value map of your custom attributes. |

```bash
curl https://app.bookbag.ai/api/v1/chatbots/123/contacts \
  -H "Authorization: Bearer $BOOKBAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "external_id": "user_8821",
        "name": "Sam Rivera",
        "email": "sam@acme.com",
        "custom_attributes": { "plan": "pro", "ltv": 540 }
      }
    ]
  }'
```

Contacts are returned with an `id` of the form `contact_<n>`, your `external_id`, the standard `name` / `email` / `phonenumber` fields, `stripe_accounts` (array), `custom_attributes` (object), and `created_at` / `updated_at` as Unix seconds.

### Status codes

| Status | Body | Meaning |
| --- | --- | --- |
| 200 | { message, data } | Contacts created/updated. |
| 400 | { message: "Invalid request data" } | No `users` array, or it was empty. |
| 400 | { message: "Maximum 1000 contacts per request" } | More than 1000 entries. |
| 401 | { message } | Missing or invalid key. |
| 404 | { message: "Resource not found" } | Unknown chatbot or out of workspace/agent scope. |

See [Errors](/docs/api/errors) for the v1 error body.