Skip to main content
This guide keeps a business’s Event dropdown in step with the events in your own system, so every bill names an event you know. You then read each bill’s event and group bills by it. The same steps work for any list: projects, jobs, cost centers. You need a key with custom-fields:read and custom-fields:write to sync, payables:read to read bills, and payables:write to create or submit bills with an event.
1

Create the field in the Cleo web app

An admin adds an Invoice-level question of type Dropdown, named “Event”, under Settings > Invoices > Custom Questions. Leave it optional for now. The API cannot create fields.The web app saves a dropdown only with at least one option. That first option has no externalId, so a sync never changes it. If it is not one of your events, archive it in the web app after your first sync.
2

Find the field id

Call GET /v1/payable-custom-fields and find the field with "label": "Event", "scope": "ROOT" and "type": "DROPDOWN". Store its id. It does not change.
3

Push your events

Send your events to PUT /v1/payable-custom-fields/{fieldId}/options, with your event id as externalId and the event name as label.
4

Send the event on bills you create

When your integration creates or submits a bill, send the event’s externalId as the field’s answer in customFields.
5

Mark the field required

Call GET /v1/payable-custom-fields and check that the field lists your events. Then an admin marks it required, so the Cleo web app asks for an event when a vendor sends a bill through Cleo or someone at the business enters one. Before your events are synced, a required field makes vendors pick an option that is not one of your events, or refuses their bills when it has no options.A required field applies to the API too. Once it is required, a bill you create with submit: true, and every bill you submit, must name an event. That is why your integration sends the event first.
6

Read and group bills

Read each bill’s answer by the field id, and map its externalId back to your event. Or list one event’s bills with the customFieldId filter.

Push your events

Run the sync on a schedule, or whenever an event changes. Each run can send your whole list:
  • A new event gets a new option.
  • A renamed event keeps its option. Send the same externalId with the new label. Bills that already chose it show the new name.
  • A finished or cancelled event is archived. Send it with "archived": true. Vendors can no longer pick it, and its bills keep it.
  • A restored event is sent with "archived": false.
  • An unchanged event is not written again, so resending the whole list is cheap and safe.
Events you leave out of a request are not changed, and no option is ever deleted. Send up to 500 options per request. For a longer list, send it in several requests. Labels do not need to be unique. Two events with the same name stay separate options because their externalId values differ.

Send the event on a bill

Answer the Event field by its fieldId, with your event id as value. Cleo matches it against each option’s id, then externalId, then value.
To set the event on a draft before it goes for approval, send the same customFields to POST /v1/payables/{payableId}/submit. Your answer replaces any event already on the draft. An event id the field does not have, or an archived event, fails with 422 validation_error. Sync your events first.

Read each bill’s event

Every bill carries its answers in customFields. Find the answer whose fieldId is the Event field:
Map value.externalId to your event. Do not match on label: it changes when an event is renamed, and two events can share one. An option someone added in the Cleo web app has externalId: null. Match it by optionId instead. A bill with no answer has no entry for the field, or an entry whose value is null. A required field still leaves gaps: bills created before it was required, and drafts, can have no event.

List one event’s bills

Pass the field id and your event id to GET /v1/payables:
customFieldValue also takes the option’s id or value. Archived events still match. Walk the pages until you have totalCount bills. See Pagination. To total an event’s cost, add up totalAmountCents, or amountPaidCents for what has been paid. For per-line detail, read each bill with GET /v1/payables/{payableId}: its line items carry their own category and line-level customFields.

Bills from before the dropdown

If the business used a free-text question for events before, its old bills keep those text answers under the old field’s fieldId, as plain strings. Cleo does not convert them to options, and the filter does not match them. Map them to your events on your side, for example by reading each bill once and matching the text. The old field stays on those bills even after it is turned off or deleted, with the label it had then. See Old and deleted answers.