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.

View as Markdown

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.

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 for the v1 error body.

Get leads

List contacts