Workflows & Approvals

Configure multi-step approval workflows for invoices, purchase bills, expenses, and other documents. When a document triggers a workflow, it enters a pending state until approved by the designated approvers.

Workflow configuration

List workflows

Returns all workflow definitions for your organization. Each workflow is tied to a document type (e.g., invoices, purchase bills, expenses).

{
  "success": true,
  "message": "Workflows retrieved",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Purchase Bill Approval",
      "documentType": "PURCHASE_BILL",
      "enabled": true,
      "steps": [
        {
          "stepOrder": 1,
          "approverRole": "ACCOUNTANT",
          "threshold": 50000.00,
          "description": "Bills above ₹50,000 need accountant approval"
        },
        {
          "stepOrder": 2,
          "approverRole": "OWNER",
          "threshold": 200000.00,
          "description": "Bills above ₹2,00,000 need owner approval"
        }
      ]
    }
  ],
  "errors": null
}

Update workflow

Enable, disable, or rename a workflow. Requires OWNER or ADMIN role.

Replace workflow steps

Replace all steps in a workflow. Send the complete list of steps — existing steps are removed and replaced. Requires OWNER or ADMIN role.

Approval requests

List approval requests

Returns paginated approval requests. Filter by status to see pending items that need your attention.

Query parameters

Approve or reject

Approve or reject a pending approval request. Optionally include a comment:

curl -X POST https://api.katixo.com/api/v1/workflow/approval-requests/{id}/approve \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Verified against PO. Approved." }'

Requires OWNER, ADMIN, or ACCOUNTANT role. When all required steps are approved, the underlying document transitions to its next status (e.g., a purchase bill moves from PENDING_APPROVAL to POSTED).

Get approval for a document

Look up the approval request for a specific document. For example, to check the approval status of a purchase bill:

curl https://api.katixo.com/api/v1/workflow/approval-requests/document/PURCHASE_BILL/c3d4e5f6-... \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."