​
Request

​
URL

POST https://www.chatbase.co/api/v1/chatbots/{chatbotId}/custom-attributes

​
Path Parameters

​
chatbotId
string
required
The ID of the chatbot to create the custom attribute for

​
Headers

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

​
Body Parameters

​
name
string
required
The name of the custom attribute. Must be unique within the chatbot.
  • Must only contain lowercase letters, numbers, and underscores
  • Must start with a letter
  • Once created, cannot be deleted from the schema
​
type
string
required
The type of the custom attribute. Cannot be changed after creation. Allowed values: text, number, boolean, date
​
label
string
required
The display label for the custom attribute
​
description
string
A description of the custom attribute
{
  "name": "company",
  "type": "text",
  "label": "Company Name",
  "description": "User's company name"
}

​
Important Notes

  1. Custom attributes cannot be deleted once created
  2. If you need to discontinue use of a field, you can archive it using the update endpoint
  3. Archived fields:
    • Cannot be used when creating new contacts
    • Cannot be updated in existing contacts
    • Can only be set to null
    • Still return their existing values in responses
  4. Choose field names carefully as they are permanent
  5. Plan your schema design thoroughly before creating attributes

​
Response

​
Success Response

  • Status: 200 OK
  • Content-Type: application/json
​
message
string
Success message
​
data
Custom Attribute Object
{
  "message": "Success",
  "data": {
    "name": "company",
    "type": "text",
    "label": "Company Name",
    "description": "User's company name",
    "archived": false
  }
}

​
Error Responses

​
400 Bad Request

  • Invalid request body
  • Reserved field name used
  • Invalid field name format
{
  "message": "Invalid request body",
  "issues": [
    {
      "field": "type",
      "message": "Invalid type. Must be one of: text, number, boolean, date"
    }
  ]
}

​
401 Unauthorized

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

​
404 Not Found

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

​
429 Too Many Requests

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

​
500 Internal Server Error

  • Server error occurred
{
  "message": "Error creating contact custom attributes"
}

​
Code Examples

curl -X POST 'https://www.chatbase.co/api/v1/chatbots/5ba682d23d7cf92bef87bfd4/custom-attributes' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "company",
    "type": "text",
    "label": "Company Name",
    "description": "User'\''s company name"
  }'