Skip to main content
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: The API does not create fields. See Sync a dropdown and group bills for the full flow.

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 in customFields 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.
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.

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.
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. A missing answer fails with 422 validation_error, and the message names every missing field by label and id:
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, 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

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.