Request URL POST https://www.chatbase.co/api/v1/chatbots/{chatbotId}/contacts Path Parameters The ID of the chatbot to add contacts to
Body Parameters Array of contact objects to add.
Minimum: 1 contact
Maximum: 1000 contacts
Unique identifier in your system
Contact’s email address. Must be unique if provided.
Array of Stripe accounts for the contact. For more information, see
Contacts .
Custom fields defined in your chatbot’s schema. Each field must:
Exist in the custom attributes schema
Not be archived
Match the defined type
Unknown fields will be silently stripped
Field Handling Default Fields Only the following default fields are recognized and stored:
external_idnameemailphonenumberstripe_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:
Each field is checked against the chatbot’s custom attribute schema
Unknown fields (not in schema) are silently stripped
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 OKContent-Type : application/json
Array of created contact objects
The unique identifier for the contact in Chatbase
Your system’s identifier for the contact
Array of Stripe accounts for the contact.
Object containing the stored custom attributes
Unix timestamp of when the contact was created
Unix timestamp of when the contact was last updated
{ "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 { "message" : "Chatbot not found" } 409 Conflict { "message" : "Email already exists" } 429 Too Many Requests { "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" } } ] }'
