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

# Create a Contact Custom Field via the ChatbotX API

> Use POST /api/v1/custom-fields to add a new custom field to your ChatbotX workspace. Provide a unique name and a data type such as shortText or date.

Custom fields extend the default contact profile with the data that matters most to your business. Use this endpoint to create a new custom field in your workspace. You must supply a unique `name` and a `type` that matches the kind of data you want to store. Optionally, you can assign the field to an existing folder to keep things organised.

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

## Request Body

<ParamField body="name" type="string" required>
  A unique name for the custom field. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="type" type="string" required>
  The data type for the field. Accepted values: `shortText`, `longText`, `number`, `date`, `datetime`, `boolean`, `email`, `phoneNumber`.
</ParamField>

<ParamField body="folderId" type="string | null">
  The ID of the folder to place this field in. Pass `null` or omit to leave the field unorganised.
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://app.chatbotx.io/api/v1/custom-fields \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Account Tier",
      "type": "shortText",
      "folderId": null
    }'
  ```

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

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

  payload = {
      "name": "Account Tier",
      "type": "shortText",
      "folderId": None
  }
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Account Tier',
      type: 'shortText',
      folderId: null
    })
  };

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

## Response

Returns `201 Created` with the newly created custom field object.

### Response Fields

<ResponseField name="id" type="string" required>
  The unique identifier for the created custom field.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the newly created 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="description" type="string | null" required>
  An optional description, or `null` if none was provided.
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "103",
  "name": "Account Tier",
  "type": "shortText",
  "description": null
}
```