# Custom Fields

## Custom Fields Object

Custom Fields are represented as a JSON object with the following properties

<table data-full-width="true"><thead><tr><th width="145">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>The ID of the custom field.</td></tr><tr><td>entity_type</td><td>enum</td><td>The entity type this custom field belongs to. Can be either <code>request</code> or <code>customer</code>.</td></tr><tr><td>name</td><td>string</td><td>The name of the custom field.</td></tr><tr><td>version</td><td>string</td><td>Version of current data, increments each time we update the custom field object.</td></tr><tr><td>type</td><td>enum</td><td><p>Denotes the type of the custom field. Possible values:</p><ul><li><strong>select:</strong> A custom field that allows a single selection from predefined options.</li><li><strong>multi_select:</strong> A custom field that supports multiple selections from a list of predefined options.</li><li><strong>text:</strong> A custom field for entering freeform text input.</li><li><strong>date:</strong> A custom field for selecting a specific date.</li><li><strong>number:</strong> A custom field for entering numerical values.</li></ul></td></tr><tr><td>config</td><td>object</td><td>Details about the object can be found <a href="#config-object">here</a>.</td></tr><tr><td>created_at</td><td>string</td><td>The creation timestamp of the custom field</td></tr><tr><td>updated_at</td><td>string</td><td>The update timestamp of the custom field</td></tr></tbody></table>

## Config Object

Config is represented as a JSON object with the following properties. It will hold different properties for different types of custom Fields.

### Config Object for Select Custom Field

<table data-full-width="true"><thead><tr><th width="121">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>literal</td><td>Must be exactly: <code>'select'</code></td></tr><tr><td>options</td><td>object array</td><td><p>Array of selection options. Each option object contains:</p><ul><li><strong>id:</strong> (string) Unique identifier for the option</li><li><strong>value:</strong> (string) Display text for the option</li></ul><p>The order of elements in the array determines the sequence in which they are displayed across various user interfaces.</p></td></tr><tr><td>last_option_id</td><td>number</td><td>Represents the highest ID number used for options.</td></tr></tbody></table>

### Config Object for Multi-Select Custom Field

<table data-full-width="true"><thead><tr><th width="166">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>literal</td><td>Must be exactly: <code>'multi_select'</code></td></tr><tr><td>options</td><td>object array</td><td><p>Array of selection options. Each option object contains:</p><ul><li><strong>id:</strong> (string) Unique identifier for the option</li><li><strong>value:</strong> (string) Display text for the option</li></ul><p>The order of elements in the array determines the sequence in which they are displayed across various user interfaces.</p></td></tr><tr><td>last_option_id</td><td>number</td><td>Represents the highest ID number used for options.</td></tr></tbody></table>

### Config Object for Text Custom Field

<table data-full-width="true"><thead><tr><th width="173">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>literal</td><td>Must be exactly: <code>'text'</code></td></tr><tr><td>max_length</td><td>number</td><td>Optional. Maximum number of characters allowed in the text field. Defaults 255</td></tr><tr><td>single_line</td><td>boolean</td><td>Optional. If true, the text field will be displayed as a single-line text field in various user interfaces. If false it will be displayed as a multi-line text field. Default value:</td></tr></tbody></table>

### Config Object for Date

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>literal</td><td>Must be exactly: <code>'date'</code></td></tr></tbody></table>

### Config Object for Number

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="99">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>literal</td><td>Must be exactly: <code>'number'</code></td></tr></tbody></table>

## Get All Custom Fields

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/custom-fields`

Get all custom fields in an account

#### Query Parameters

<table data-full-width="true"><thead><tr><th width="145">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>entity_type</td><td>enum</td><td>Optional. Filter custom fields by entity type. Can be either <code>request</code> or <code>customer</code>. Defaults to <code>request</code> if not provided.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
  "custom_fields": [
    {
      "id": 1,
      "entity_type": "request",
      "name": "player select",
      "version": 0,
      "type": "select",
      "config": {
        "type": "select",
        "options": [
          {
            "id": "1",
            "value": "joel"
          },
          {
            "id": "2",
            "value": "ellie"
          }
        ],
        "last_option_id": 2
      },
      "created_at": "2024-10-30T18:18:10.839Z",
      "updated_at": "2024-10-30T18:18:10.839Z"
    }
  ]
}
```

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}

## Create Custom Field

<mark style="color:green;">`POST`</mark> `https://api.clearfeed.app/v1/rest/custom-fields`

Create a custom field to use them in forms.

#### Request Body

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>name*</td><td>string</td><td>Name of the custom field</td></tr><tr><td>entity_type</td><td>enum</td><td>Optional. The entity type this custom field belongs to. Can be either <code>request</code> or <code>customer</code>. Defaults to <code>request</code> if not provided.</td></tr><tr><td>type*</td><td>enum</td><td>Type of the custom field. Must be one of: <code>select</code>, <code>multi_select</code>, <code>text</code>, <code>date</code>, <code>number</code></td></tr><tr><td>config</td><td>object</td><td>Config object for the custom field. Required structure depends on the field type. See <a href="#config-object">Config Object</a> for type-specific details.</td></tr></tbody></table>

Example request body:

```json
{
  "name": "player select",
  "entity_type": "request",
  "type": "select",
  "config": {
    "options": [
      {
        "value": "joel"
      },
      {
        "value": "ellie"
      }
    ]
  }
}
```

{% tabs %}
{% tab title="201" %}

```json
{
  "id": 1,
  "entity_type": "request",
  "name": "player select",
  "version": 0,
  "type": "select",
  "config": {
    "type": "select",
    "options": [
      {
        "id": "1",
        "value": "joel"
      },
      {
        "id": "2",
        "value": "ellie"
      }
    ],
    "last_option_id": 3
  },
  "created_at": "2024-10-30T18:18:10.839Z",
  "updated_at": "2024-10-30T18:18:10.839Z"
}
```

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}
{% endtabs %}

## Update Custom Field

<mark style="color:yellow;">`PUT`</mark> `https://api.clearfeed.app/v1/rest/custom-fields/:id`

Update an existing custom field.

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id*</td><td>integer</td><td>The ID of the custom field to update</td></tr></tbody></table>

#### Request Body

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>name*</td><td>string</td><td>Name of the custom field</td></tr><tr><td>type*</td><td>enum</td><td>Type of the custom field. Must be one of: <code>select</code>, <code>multi_select</code>, <code>text</code>, <code>date</code>, <code>number</code></td></tr><tr><td>config</td><td>object</td><td>Configuration object for the custom field. Required structure depends on the field type. See <a href="#config-object">Config Object</a> for type-specific details.</td></tr></tbody></table>

> **Important:** Once created, a custom field's type and entity\_type cannot be modified. However, you can:
>
> * For `select` and `multi_select` fields: add, remove, or modify the available options
> * For `text` fields: adjust the character limit

Example request body:

```json
{
  "name": "character select",
  "config": {
    "options": [
      {
        "id": 2,
        "value": "ellie-renamed"
      },
      {
        "id": 1,
        "value": "joel"
      },
      {
        "value": "tommy"
      },
      {
        "value": "harry"
      }
    ]
  }
}
```

{% tabs %}
{% tab title="200: Success" %}

```json
{
  "id": 1,
  "entity_type": "request",
  "name": "character select",
  "version": 1,
  "type": "select",
  "config": {
    "type": "select",
    "options": [
      {
        "id": "2",
        "value": "ellie-renamed"
      },
      {
        "id": "1",
        "value": "joel"
      },
      {
        "id": "3",
        "value": "tommy"
      },
      {
        "id": "3",
        "value": "harry"
      }
    ],
    "last_option_id": 3
  },
  "created_at": "2024-10-30T18:18:10.839Z",
  "updated_at": "2024-10-30T18:20:15.122Z"
}
```

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}

{% tab title="404: Not Found" %}

{% endtab %}
{% endtabs %}

## Delete Custom Field

<mark style="color:red;">`DELETE`</mark> `https://api.clearfeed.app/v1/rest/custom-fields/:id`

Delete a custom field.

#### Request Parameters

<table data-full-width="true"><thead><tr><th width="100">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>id*</td><td>integer</td><td>The ID of the custom field to delete</td></tr></tbody></table>

{% tabs %}
{% tab title="200: Success" %}

{% endtab %}

{% tab title="403: Forbidden Permission denied" %}

{% endtab %}

{% tab title="404: Not Found" %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clearfeed.ai/api/reference/api-reference/custom-fields.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.