> ## 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.

# List All Contact Custom Fields via the ChatbotX API

> Use GET /api/v1/custom-fields to retrieve all custom field definitions in your ChatbotX workspace, with optional keyword filtering to narrow results.

Custom fields let you store structured data against your contacts — such as short text, numbers, dates, or booleans. Use this endpoint to retrieve all custom fields defined in your workspace. You can paginate through results and search by keyword to find specific fields quickly.

<Info>
  **GET** `/api/v1/custom-fields`
</Info>

## Query Parameters

<ParamField query="page" type="integer">
  The page number to retrieve. Must be `1` or greater. Defaults to `1`.
</ParamField>

<ParamField query="perPage" type="integer">
  Number of custom fields to return per page. Must be `1` or greater.
</ParamField>

<ParamField query="keyword" type="string">
  Filter custom fields by name. Returns all fields whose name contains the provided keyword (case-insensitive).
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://app.chatbotx.io/api/v1/custom-fields?page=1&perPage=20' \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.chatbotx.io/api/v1/custom-fields"

  params = {"page": 1, "perPage": 20}
  headers = {"Authorization": "Bearer <token>"}

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

  ```javascript JavaScript theme={null}
  const options = {
    method: 'GET',
    headers: { Authorization: 'Bearer <token>' }
  };

  fetch('https://app.chatbotx.io/api/v1/custom-fields?page=1&perPage=20', options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.error(err));
  ```
</CodeGroup>

## Response

Returns a `200 OK` with a `data` array of custom field objects.

### Response Fields

<ResponseField name="data" type="array" required>
  Array of custom field objects belonging to the workspace.

  <Expandable title="data item fields">
    <ResponseField name="id" type="string" required>
      Unique identifier for the custom field.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the custom field.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The data type of the field. One of `shortText`, `longText`, `number`, `date`, `datetime`, `boolean`, `email`, or `phoneNumber`.
    </ResponseField>

    <ResponseField name="workspaceId" type="string" required>
      The ID of the workspace this field belongs to.
    </ResponseField>

    <ResponseField name="folderId" type="string | null">
      The folder this field is organised into, or `null` if it is not in a folder.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      An optional description of the custom field's purpose.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "101",
      "name": "Favourite Colour",
      "type": "shortText",
      "workspaceId": "42",
      "folderId": null,
      "description": "The contact's self-reported favourite colour."
    },
    {
      "id": "102",
      "name": "Date of Birth",
      "type": "date",
      "workspaceId": "42",
      "folderId": "7",
      "description": null
    }
  ]
}
```