# 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 %}