Skip to main content
Custom fields let you collect additional information from vendors when they submit an invoice. You define the fields, their types, and any conditions that control when each field is shown. Vendors see your custom fields as part of the invoice submission form. Common uses include capturing a purchase order number, a cost center code, a project name, or any internal reference your accounts payable team needs for routing and approval.

​
Field types

TypeDescription
TEXTFree-form text input
DROPDOWNSingle-select from a predefined list of options
MULTIPLE_CHOICEMulti-select from a predefined list of options
DATEDate picker
NUMERICNumeric input
NUMERIC_GROUPA group of numeric fields with a calculated result (for example, quantity × rate = total)

​
Create a custom field

1

Define the field

Call the create endpoint with a name, type, and whether the field is required. For DROPDOWN and MULTIPLE_CHOICE fields, include an options array.The example below creates a required text field for a purchase order number:
curl --request POST \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Purchase order number",
    "type": "TEXT",
    "required": true,
    "placeholder": "e.g. PO-2024-001"
  }'
The response includes the new field’s id, which you need for subsequent update, delete, and reorder operations.
2

Add visibility conditions (optional)

You can configure a field so it only appears when another field has a specific value. For example, show a “Project code” text field only when a “Department” dropdown is set to “Engineering”.Pass a visibilityCondition object when creating or updating a field:
curl --request PUT \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields/{id} \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "visibilityCondition": {
      "fieldId": "PARENT_FIELD_ID",
      "value": "Engineering"
    }
  }'
The field is hidden from vendors unless the parent field has the specified value.
3

Reorder fields

Control the order in which fields appear in the submission form. Pass an array of field IDs in the desired display order:
curl --request PUT \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields/reorder \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderedIds": ["FIELD_ID_1", "FIELD_ID_2", "FIELD_ID_3"]
  }'

​
Manage existing fields

List all fields: 
curl --request GET \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields \
  --header 'Authorization: Bearer YOUR_TOKEN'
Update a field (change name, type, options, or visibility conditions): 
curl --request PUT \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields/{id} \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated field name",
    "required": false
  }'
Delete a field (soft delete — the field is deactivated and hidden from new submissions, but historical data is preserved): 
curl --request DELETE \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields/{id} \
  --header 'Authorization: Bearer YOUR_TOKEN'
Deleting a field is a soft delete. The field is removed from the submission form immediately, but responses already collected from previous invoices are not affected.

​
View active fields

To see exactly which fields vendors will encounter during invoice submission, retrieve the active fields list: 
curl --request GET \
  --url https://api.cleo-pay.com/api/businesses/{businessId}/payable-custom-fields/active \
  --header 'Authorization: Bearer YOUR_TOKEN'
This returns only fields that are currently enabled and visible — the same set shown to vendors in the submission form.

​
API reference

MethodEndpointDescription
POST/api/businesses/{businessId}/payable-custom-fieldsCreate a custom field
GET/api/businesses/{businessId}/payable-custom-fieldsList all custom fields
PUT/api/businesses/{businessId}/payable-custom-fields/{id}Update a custom field
DELETE/api/businesses/{businessId}/payable-custom-fields/{id}Delete a custom field (soft delete)
GET/api/businesses/{businessId}/payable-custom-fields/activeGet active fields
PUT/api/businesses/{businessId}/payable-custom-fields/reorderReorder fields