Contact Custom Fields: Read and Write Custom Data

Custom fields let you store structured data on contacts beyond the standard profile fields — things like subscription plan, customer tier, last purchase date, or any business-specific attribute. This page documents the two custom field endpoints for a contact: retrieving all field values and setting a single field value.

Get All Custom Fields for a Contact

Returns all custom field values currently set on a contact. The response is an array of field objects, each including the field’s ID, name, description, and current value.

GET /api/v1/contacts/{identifier}/custom-fields

Path Parameters

string

required

Contact lookup string (id:<value>, email:<value>, or phone:<value>). Minimum length: 1 character.

Code Examples

curl --request GET \
  --url "https://app.chatbotx.io/api/v1/contacts/email:user@example.com/custom-fields" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

import requests

identifier = "email:user@example.com"
url = f"https://app.chatbotx.io/api/v1/contacts/{identifier}/custom-fields"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const identifier = 'email:user@example.com';
const options = {
  method: 'GET',
  headers: { Authorization: 'Bearer YOUR_API_TOKEN' }
};

fetch(`https://app.chatbotx.io/api/v1/contacts/${identifier}/custom-fields`, options)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Response Fields

array

required

Array of custom field value objects.

Show Custom field object

string

required

The custom field definition ID.

string

required

Human-readable field name.

string

required

Field description.

string

required

Current value set on this contact for this field.

Example Response

{
  "data": [
    {
      "id": "101",
      "name": "Plan",
      "description": "Subscription plan tier",
      "value": "premium"
    },
    {
      "id": "102",
      "name": "Region",
      "description": "Sales region",
      "value": "Southeast Asia"
    }
  ]
}

Set a Single Custom Field Value

Sets the value of a specific custom field on a contact. You identify both the contact and the target field in the URL path. A successful request returns HTTP 200 OK.

POST /api/v1/contacts/{identifier}/custom-fields/{customFieldId}

Path Parameters

string

required

Contact lookup string. Minimum length: 1 character.

string

required

The numeric ID of the custom field to update. Must match the pattern \d+.

Request Body

string

required

The new value to set for this custom field on the contact.

Code Examples

curl --request POST \
  --url "https://app.chatbotx.io/api/v1/contacts/email:user@example.com/custom-fields/101" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"value": "premium"}'

import requests

identifier = "email:user@example.com"
custom_field_id = "101"
url = f"https://app.chatbotx.io/api/v1/contacts/{identifier}/custom-fields/{custom_field_id}"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {"value": "premium"}

response = requests.post(url, json=payload, headers=headers)
print(response.status_code)  # 200 on success

const identifier = 'email:user@example.com';
const customFieldId = '101';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ value: 'premium' })
};

fetch(
  `https://app.chatbotx.io/api/v1/contacts/${identifier}/custom-fields/${customFieldId}`,
  options
)
  .then(res => {
    if (res.status === 200) console.log('Field updated successfully');
  })
  .catch(err => console.error(err));

Response

HTTP/1.1 200 OK

To find the numeric IDs of your custom fields, call GET /api/v1/custom-fields. The id field in each result is what you pass as customFieldId.

Overview

Contacts

Custom Fields

Tags

Flows & Sequences

Broadcasts & Channels

Workspace

AI Agents

Contact Custom Fields: Read and Write Custom Data

Get All Custom Fields for a Contact

Path Parameters

Code Examples

Response Fields

Example Response

Set a Single Custom Field Value

Path Parameters

Request Body

Code Examples

Response

​Get All Custom Fields for a Contact

​Path Parameters

​Code Examples

​Response Fields

​Example Response

​Set a Single Custom Field Value

​Path Parameters

​Request Body

​Code Examples

​Response

Get All Custom Fields for a Contact

Path Parameters

Code Examples

Response Fields

Example Response

Set a Single Custom Field Value

Path Parameters

Request Body

Code Examples

Response