- List the fields and their dropdown options with
GET /v1/payable-custom-fields. - Keep a dropdown’s options in step with your own system with
PUT /v1/payable-custom-fields/{fieldId}/options. - Answer fields when you create or submit a bill. See Write answers.
- Read each bill’s answers in
customFields, on payables and on their line items. - List the bills that chose one option with the
customFieldIdandcustomFieldValuefilter.
The field object
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
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 incustomFields has this shape:
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.
optionIdis the option’sid. It isnullonly for an answer saved before options had ids, whose option no longer exists.externalIdis the option’s currentexternalId, ornull.labelis 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.
fieldId, not by their position in the array.
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:
An option key is matched against option
id first, then externalId, then value.
422 validation_error, with a message that names the field:
- A
valueof 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_GROUPfield. - The same field answered twice in one list.
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.
A missing answer fails with
422 validation_error, and the message names every missing field by label and id:
Scopes
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.