> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Custom Fields: Read and Write Custom Data

> Use GET and POST on /api/v1/contacts/{identifier}/custom-fields to retrieve all custom field values or set a single field value on a ChatbotX contact.

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.

<Info>
  **GET** `/api/v1/contacts/{identifier}/custom-fields`
</Info>

### Path Parameters

<ParamField path="identifier" type="string" required>
  Contact lookup string (`id:<value>`, `email:<value>`, or `phone:<value>`). Minimum length: 1 character.
</ParamField>

### Code Examples

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url "https://app.chatbotx.io/api/v1/contacts/email:user@example.com/custom-fields" \
    --header "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### Response Fields

<ResponseField name="data" type="array" required>
  Array of custom field value objects.

  <Expandable title="Custom field object">
    <ResponseField name="id" type="string" required>The custom field definition ID.</ResponseField>
    <ResponseField name="name" type="string" required>Human-readable field name.</ResponseField>
    <ResponseField name="description" type="string" required>Field description.</ResponseField>
    <ResponseField name="value" type="string" required>Current value set on this contact for this field.</ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "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`.

<Info>
  **POST** `/api/v1/contacts/{identifier}/custom-fields/{customFieldId}`
</Info>

### Path Parameters

<ParamField path="identifier" type="string" required>
  Contact lookup string. Minimum length: 1 character.
</ParamField>

<ParamField path="customFieldId" type="string" required>
  The numeric ID of the custom field to update. Must match the pattern `\d+`.
</ParamField>

### Request Body

<ParamField body="value" type="string" required>
  The new value to set for this custom field on the contact.
</ParamField>

### Code Examples

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### Response

```
HTTP/1.1 200 OK
```

<Tip>
  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`.
</Tip>