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

# Custom fields

> Custom fields are the business's own questions on bills and line items. Learn the field and option shapes, how to send and read answers on payables, required fields, and what happens to old and deleted answers.

A custom field is a question the business asks on its bills, such as "Event" or "Cost center". The business creates fields in the Cleo web app. Through the API you can:

* List the fields and their dropdown options with [`GET /v1/payable-custom-fields`](https://docs.cleo-pay.com/api-reference/payable-custom-fields/list).
* Keep a dropdown's options in step with your own system with [`PUT /v1/payable-custom-fields/{fieldId}/options`](https://docs.cleo-pay.com/api-reference/payable-custom-fields/sync-options).
* Answer fields when you [create](https://docs.cleo-pay.com/api-reference/payables/create.md) or [submit](https://docs.cleo-pay.com/api-reference/payables/submit.md) a bill. See [Write answers](#write-answers).
* Read each bill's answers in `customFields`, on [payables](https://docs.cleo-pay.com/concepts/payables.md) and on their line items.
* List the bills that chose one option with the [`customFieldId` and `customFieldValue` filter](https://docs.cleo-pay.com/api-reference/payables/list).

The API does not create fields. See [Sync a dropdown and group bills](https://docs.cleo-pay.com/guides/sync-dropdown-options.md) for the full flow.

## The field object

| Field | Meaning |
| - | - |
| `id` | The field id. Use it in the option sync path, in the payables filter, and to find the field's answers on a bill. |
| `label` | The question, or `null`. |
| `description` | Help text, or `null`. |
| `scope` | Where the question is asked. See below. |
| `type` | `DROPDOWN`, `MULTIPLE_CHOICE`, `SHORT_TEXT`, `LONG_TEXT`, `DATE`, `NUMERIC` or `NUMERIC_GROUP`. |
| `required` | Whether a bill must answer it. See [Required fields](#required-fields). |
| `options` | The choices of a `DROPDOWN` or `MULTIPLE_CHOICE` field, archived ones included. Empty for other types. |

| `scope` | Asked |
| - | - |
| `ROOT` | Once per bill. Answers appear in the bill's `customFields`. |
| `INVOICE_ITEM` | On each line item. Answers appear in each item's `customFields`. |

`INVOICE_EXPENSE`, `INVOICE_DEDUCTION` and `ATTACHMENT` can also appear. Their answers are not returned on payables. Cleo adds values over time, so accept a `scope` or `type` you do not know.

## Options

| Field | Meaning |
| - | - |
| `id` | Stable option id. It never changes, even when the option is renamed. |
| `value` | Internal value, generated from the label when the option is created. It never changes either. |
| `label` | The text people choose from. Two options can share a label. |
| `externalId` | Your key for the option, set through the option sync. `null` for options added in the Cleo web app. |
| `archived` | `true` when the option can no longer be chosen on new bills. Bills that already chose it keep it. |
| `archivedAt` | When it was archived, or `null`. |

Options keep their `id` and `value` for life, so a rename changes only the `label`. Prefer `externalId` or `id` over the label whenever you match an option.

## Answers on bills

Each answer in `customFields` has this shape:

| Field | Meaning |
| - | - |
| `fieldId` | The field it answers. |
| `label` | The field's label. See [Old and deleted answers](#old-and-deleted-answers). |
| `type` | The field's type. |
| `value` | The answer. Its shape depends on `type`. |

| `type` | `value` |
| - | - |
| `DROPDOWN` | One option: `{ optionId, externalId, label }`. |
| `MULTIPLE_CHOICE` | An array of options, each `{ optionId, externalId, label }`. |
| `SHORT_TEXT`, `LONG_TEXT` | A string. |
| `DATE` | A date string, `YYYY-MM-DD`. |
| `NUMERIC` | A number. |
| `NUMERIC_GROUP` | A number: the group's calculated total. |

Two more rules apply to every type:

* An answer saved as free text comes back as a string, whatever the field's type.
* An answer that holds no value comes back as `null`.

In an answer's option:

* `optionId` is the option's `id`. It is `null` only for an answer saved before options had ids, whose option no longer exists.
* `externalId` is the option's current `externalId`, or `null`.
* `label` is the option's current label, so a renamed option shows its new name on old bills. When the option no longer exists, it is the label saved with the answer.

Match answers by `fieldId`, not by their position in the array.

```json theme={null}
"customFields": [
  {
    "fieldId": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e",
    "label": "Event",
    "type": "DROPDOWN",
    "value": {
      "optionId": "2a7c9e1f-4b6d-4c8e-a0f2-3b5d7e9f1a2c",
      "externalId": "evt-100",
      "label": "Spring Gala 2027"
    }
  },
  {
    "fieldId": "d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f0a",
    "label": "Event worked",
    "type": "SHORT_TEXT",
    "value": "spring gala 27"
  }
]
```

## Write answers

`POST /v1/payables` and `POST /v1/payables/{payableId}/submit` take answers as `customFields: [{ fieldId, value }]`, on the bill for `ROOT` fields and on each line item for `INVOICE_ITEM` fields. `value` uses the same choices you read back:

| `type` | `value` you send |
| - | - |
| `DROPDOWN` | One option, as its `id`, `externalId` or `value`. |
| `MULTIPLE_CHOICE` | An array of options, each as its `id`, `externalId` or `value`. |
| `SHORT_TEXT`, `LONG_TEXT` | A string. |
| `DATE` | A date string, `YYYY-MM-DD`. |
| `NUMERIC` | A number. |
| `NUMERIC_GROUP` | Not accepted. Someone at the business answers it in the Cleo web app. |

An option key is matched against option `id` first, then `externalId`, then `value`.

```json theme={null}
"customFields": [
  { "fieldId": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e", "value": "evt-100" },
  { "fieldId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "value": ["proj-7", "proj-9"] },
  { "fieldId": "f5a6b7c8-d9e0-4f1a-9b2c-3d4e5f6a7b8c", "value": "2027-04-12" }
]
```

Answers are checked against the field before anything is written. These answer `422 validation_error`, with a message that names the field:

* A `value` of the wrong type for the field.
* An option the field does not have, or an archived option. On submit, an archived option the bill already holds is accepted.
* A field that is unknown, turned off or deleted.
* A field sent at the wrong level: a line-level field on the bill, or a bill-level field on a line.
* A `NUMERIC_GROUP` field.
* The same field answered twice in one list.

Answers need a linked vendor. A create that names the vendor with a free-text `contact` and sends answers fails with `400 validation_error`. Use `contactId`.

On submit, each answer you send replaces the stored answer to the same field. Answers you do not send stay as they are.

## Old and deleted answers

A bill keeps every answer it was saved with.

* **Free-text answers.** When a business replaces a free-text question with a dropdown, bills answered before the change keep their text answers under the old field's `fieldId`. They come back as strings. Cleo does not convert them to options, so map them on your side.
* **Fields turned off or deleted.** Their answers are still returned, with the label the field had when it was turned off or deleted. These fields no longer appear in `GET /v1/payable-custom-fields`.
* **Another business's fields.** A bill can carry answers to fields that belong to another business on the bill. Those answers carry the field label saved with the answer, and their options have `externalId: null`.

## Required fields

On a bill-level (`ROOT`) field, `required: true` means a bill needs an answer before it is created submitted or a draft is submitted. The Cleo web app and the API both check it. Only turned-on fields count, and a field the business shows only after another answer counts only when it is shown.

| Call | Required bill-level fields |
| - | - |
| `POST /v1/payables` with `submit: true` | Checked. Send every answer in `customFields`. |
| `POST /v1/payables` as a draft, with no bill-level answers | Not checked. |
| `POST /v1/payables` as a draft, with any bill-level answer | Checked, as on the Cleo web app's bill form. |
| `POST /v1/payables/{payableId}/submit` | Checked against the stored answers merged with the ones you send. |

A missing answer fails with `422 validation_error`, and the message names every missing field by label and id:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Required custom fields have no answer: \"Event\" (8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e)",
    "requestId": "6f1c2a9e-0b4d-4c55-9e1a-2f7d8b3c4a10"
  }
}
```

> [!WARNING]
>
> **Behavior change.** The API used to skip required fields on both routes. If the business marks a bill-level field required, `submit: true` creates and submits without its answer now fail with `422`. Read the fields with [`GET /v1/payable-custom-fields`](https://docs.cleo-pay.com/api-reference/payable-custom-fields/list), check `required`, and send the answers. A required `NUMERIC_GROUP` field cannot be answered through the API, so someone at the business answers it in the Cleo web app before you submit.

Line-level required fields are checked only on a line that carries answers in the request. Such a line must answer every required line-level field, counting the line's stored answers on submit. A line you send no answers for is not checked.

## Scopes

| Scope | Grants |
| - | - |
| `custom-fields:read` | `GET /v1/payable-custom-fields`. |
| `custom-fields:write` | `PUT /v1/payable-custom-fields/{fieldId}/options`. Does not include reads. |

Neither scope opens the bill routes. Reading answers on bills needs `payables:read`, and sending them with a create or submit needs `payables:write`. See [Scopes](https://docs.cleo-pay.com/authentication.md#scopes).

## Related

* [List custom fields](https://docs.cleo-pay.com/api-reference/payable-custom-fields/list.md)
* [Sync dropdown options](https://docs.cleo-pay.com/api-reference/payable-custom-fields/sync-options.md)
* [Sync a dropdown and group bills](https://docs.cleo-pay.com/guides/sync-dropdown-options.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.