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

# List custom fields

> GET /v1/payable-custom-fields lists the business's bill and line-item custom fields, with every dropdown option, archived ones included.

```
GET /v1/payable-custom-fields
```

**Scope:** `custom-fields:read`

Lists the business's custom fields that are turned on, grouped by scope, in the order set in the Cleo web app. The request takes no parameters, and the list is not paged.

```bash theme={null}
curl https://api.stg.cleo-pay.com/v1/payable-custom-fields \
  --header "Authorization: Bearer $CLEO_API_KEY"
```

## Response

`200` with `{ items }`. Each item is a [custom field](https://docs.cleo-pay.com/concepts/custom-fields.md#the-field-object).

**id** `string`

The field id.

**label** `string | null`

The question.

**description** `string | null`

Help text.

**scope** `string`

`ROOT` (once per bill) or `INVOICE_ITEM` (on each line item). `INVOICE_EXPENSE`, `INVOICE_DEDUCTION` and `ATTACHMENT` can also appear.

**type** `string`

`DROPDOWN`, `MULTIPLE_CHOICE`, `SHORT_TEXT`, `LONG_TEXT`, `DATE`, `NUMERIC` or `NUMERIC_GROUP`.

**required** `boolean`

Whether a bill must answer it in the Cleo web app.

**options** `array`

Choices of a `DROPDOWN` or `MULTIPLE_CHOICE` field, archived ones included: `id`, `value`, `label`, `externalId`, `archived`, `archivedAt`. Empty for other types.

```json theme={null}
{
  "items": [
    {
      "id": "8d4f2c1a-6b3e-4a7d-9c5f-0e1b2a3c4d5e",
      "label": "Event",
      "description": "The event this bill is for",
      "scope": "ROOT",
      "type": "DROPDOWN",
      "required": true,
      "options": [
        {
          "id": "2a7c9e1f-4b6d-4c8e-a0f2-3b5d7e9f1a2c",
          "value": "spring_gala_2027",
          "label": "Spring Gala 2027",
          "externalId": "evt-100",
          "archived": false,
          "archivedAt": null
        },
        {
          "id": "5e1a3c7f-9b2d-4f6a-8c0e-1d3f5a7b9c2e",
          "value": "fall_expo",
          "label": "Fall Expo",
          "externalId": null,
          "archived": true,
          "archivedAt": "2026-10-01T00:00:00.000Z"
        }
      ]
    },
    {
      "id": "c3d5e7f9-1a2b-4c4d-8e6f-7a8b9c0d1e2f",
      "label": "Crew size",
      "description": null,
      "scope": "INVOICE_ITEM",
      "type": "NUMERIC",
      "required": false,
      "options": []
    }
  ]
}
```

Fields that were turned off or deleted are left out, but bills keep their answers to them. See [Old and deleted answers](https://docs.cleo-pay.com/concepts/custom-fields.md#old-and-deleted-answers).

## Errors

| Code | When |
| - | - |
| `forbidden_scope` | The key lacks `custom-fields:read`, or its member cannot view bills. |


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