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

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",
      "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",
        "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