​
Request

​
URL

POST https://www.chatbase.co/api/v1/chatbots/{chatbotId}/contacts

​
Path Parameters

​
chatbotId
string
required
The ID of the chatbot to add contacts to

​
Headers

​
Authorization
string
required
Bearer <YOUR_API_KEY>
​
Content-Type
string
required
application/json

​
Body Parameters

​
users
array
required
Array of contact objects to add.
  • Minimum: 1 contact
  • Maximum: 1000 contacts

​
Field Handling

​
Default Fields

Only the following default fields are recognized and stored:
  • external_id
  • name
  • email
  • phonenumber
  • stripe_accounts
Any other fields outside of custom_attributes will be silently stripped from the data.

​
Custom Attributes

Fields under custom_attributes go through the following validation:
  1. Each field is checked against the chatbot’s custom attribute schema
  2. Unknown fields (not in schema) are silently stripped
  3. Fields that exist in the schema are validated:
    • Check if the field is archived (error if archived)
    • Validate the value against the field’s type
    • Store the value if validation passes

​
Example Request Body

{
  "users": [
    {
      "external_id": "123456",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phonenumber": "+1234567890",
      "stripe_accounts": [
        {
          "label": "Team 1",
          "stripe_id": "cus_1234567890"
        }
      ],
      "unknown_field": "will be stripped",
      "custom_attributes": {
        "company": "Acme Inc",           // will be validated and stored
        "unknown_attr": "will be stripped", // not in schema, will be stripped
        "archived_field": "error",        // will cause 400 error if archived
        "age": "invalid"                 // will cause 400 error if type is number
      }
    }
  ]
}

​
Response

​
Success Response

  • Status: 200 OK
  • Content-Type: application/json
​
message
string
Success message
​
data
object
​
created
array
Array of created contact objects
{
  "message": "Success",
  "data": {
    "created": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "external_id": "123456",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phonenumber": "+1234567890",
        "stripe_accounts": [
          {
            "label": "Team 1",
            "stripe_id": "cus_1234567890"
          }
        ],
        "custom_attributes": {
          "company": "Acme Inc"
        },
        "created_at": 1571672154,
        "updated_at": 1571672154
      }
    ]
  }
}

​
Error Responses

​
400 Bad Request

  • Invalid request body
  • Maximum contacts limit reached
  • Invalid custom attribute value type
  • Archived custom attribute used
{
  "message": "Invalid request body",
  "issues": [
    {
      "field": "custom_attributes.age",
      "message": "Expected number, received string"
    }
  ]
}

​
401 Unauthorized

  • Invalid or missing API key
{
  "message": "Unauthorized access"
}

​
404 Not Found

  • Chatbot not found
{
  "message": "Chatbot not found"
}

​
409 Conflict

  • Email already exists
{
  "message": "Email already exists"
}

​
429 Too Many Requests

  • Rate limit exceeded
{
  "message": "Rate limit exceeded"
}

​
Code Examples

curl -X POST 'https://www.chatbase.co/api/v1/chatbots/5ba682d23d7cf92bef87bfd4/contacts' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "users": [
      {
        "external_id": "123456",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phonenumber": "+1234567890",
        "custom_attributes": {
          "company": "Acme Inc"
        }
      }
    ]
  }'