Skip to main content
Approval workflows let you require one or more people to review and approve a payable before payment is initiated. Use them to enforce spending controls, separate duties, or meet internal compliance requirements.

​
How workflows work

When a payable matches an active workflow’s conditions, it enters an approval queue. Each step in the workflow must be completed in order before the payable can be paid. If any approver declines, the payable is rejected and returned for correction. Workflows can trigger based on:
  • Amount threshold — any payable over a specified dollar amount
  • Vendor — payables from a specific connection or vendor
  • All payables — every payable requires approval

​
Create a workflow

1

Define your workflow conditions and steps

Plan your workflow before calling the API:
  • Trigger condition — what makes a payable require approval
  • Steps — the ordered sequence of approvals required
  • Approvers per step — which members or roles must approve at each step
2

Create the workflow via API

Call POST /api/approval-workflow with your workflow definition:
curl -X POST https://api.cleo-pay.com/api/approval-workflow \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-value payment approval",
    "type": "amount_threshold",
    "amountThreshold": 500000,
    "steps": [
      {
        "order": 1,
        "name": "Manager review",
        "requireAll": false,
        "approvers": [
          {
            "type": "member",
            "memberId": "mem_manager123"
          },
          {
            "type": "member",
            "memberId": "mem_manager456"
          }
        ]
      },
      {
        "order": 2,
        "name": "Finance director sign-off",
        "requireAll": true,
        "approvers": [
          {
            "type": "role",
            "roleId": "role_finance_director"
          }
        ]
      }
    ]
  }'
Key fields:
FieldDescription
typeamount_threshold, vendor, or all
amountThresholdMinimum amount in cents that triggers the workflow
steps[].requireAlltrue = all approvers in the step must approve; false = any one approver is sufficient
steps[].approvers[].typemember to assign a specific person, role to assign anyone with a given role
Amounts are in cents. 500000 = $5,000.00.
3

Verify the workflow is active

List all active workflows to confirm yours was created:
curl https://api.cleo-pay.com/api/approval-workflow \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Assign approvers by role

Instead of assigning specific members, you can assign a role. Any member with that role can complete the approval step. This is useful when you want approvals handled by a team rather than a specific individual. 
{
  "approvers": [
    {
      "type": "role",
      "roleId": "role_finance_director"
    }
  ]
}
See Team Management for how to create and assign roles.

​
How approvers approve or decline

Approvers receive a notification when a payable enters their approval step. They can review the payable and take action: Approve a payable: 
curl -X POST https://api.cleo-pay.com/api/businesses/biz_abc123/payables/pay_xyz789/approve \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Approved — matches PO #4521"
  }'
Decline a payable: 
curl -X POST https://api.cleo-pay.com/api/businesses/biz_abc123/payables/pay_xyz789/decline \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Amount exceeds budgeted amount for this vendor"
  }'

​
Reset approval on a payable

If a payable needs to go back through the approval process — for example, after the amount is corrected — reset its approval state: 
curl -X POST https://api.cleo-pay.com/api/businesses/biz_abc123/payables/pay_xyz789/reset-approval \
  -H "Authorization: Bearer YOUR_TOKEN"
This clears all existing approvals and returns the payable to the first workflow step.

​
Update a workflow

Modify an existing workflow’s name, conditions, or steps: 
curl -X PATCH https://api.cleo-pay.com/api/approval-workflow/wf_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountThreshold": 1000000,
    "steps": [
      {
        "order": 1,
        "name": "Finance team review",
        "requireAll": false,
        "approvers": [
          {
            "type": "role",
            "roleId": "role_finance"
          }
        ]
      }
    ]
  }'
Updating a workflow does not affect payables already in progress through the old workflow. Only new payables use the updated configuration.

​
Delete a workflow

curl -X DELETE https://api.cleo-pay.com/api/approval-workflow/wf_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"
After deletion, payables that would have matched this workflow are subject to your business’s default behavior for payables with no matching workflow.