Skip to main content
GET
/
approval-workflows
List Approval Workflows
curl --request GET \
  --url https://api.example.com/approval-workflows
{
  "success": true,
  "data": [
    {
      "id": "987e4567-e89b-12d3-a456-426614174000",
      "companyId": "111e4567-e89b-12d3-a456-426614174000",
      "workflowType": "leave",
      "departmentId": "123e4567-e89b-12d3-a456-426614174000",
      "steps": [
        {
          "step": 1,
          "role_id": "456e4567-e89b-12d3-a456-426614174000",
          "approver_id": null
        },
        {
          "step": 2,
          "role_id": "789e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "isActive": true,
      "createdAt": "2026-03-03T10:30:00Z"
    },
    {
      "id": "654e4567-e89b-12d3-a456-426614174000",
      "companyId": "111e4567-e89b-12d3-a456-426614174000",
      "workflowType": "memo",
      "departmentId": null,
      "steps": [
        {
          "step": 1,
          "role_id": "456e4567-e89b-12d3-a456-426614174000",
          "approver_id": "999e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "isActive": true,
      "createdAt": "2026-02-28T14:20:00Z"
    }
  ]
}

​
Overview

Retrieve all approval workflows configured for your company. You can filter by workflow type, department, and active status.
Accessible to users with Super Admin, HR Manager, or Manager roles.

​
Query Parameters

​
workflowType
string
Filter by workflow type. Valid values:
  • leave - Leave request workflows
  • memo - Memo approval workflows
  • expense - Expense claim workflows
If not provided, returns workflows of all types.
​
departmentId
uuid
Filter workflows by department ID. Returns workflows specific to this department plus company-wide workflows (where departmentId is null).
​
onlyActive
boolean
default:"true"
When true, returns only active workflows. Set to false to include inactive workflows.Default is true if not specified.

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of approval workflow objects

​
Example Requests

​
Get all active workflows

curl -X GET https://api.companyflow.com/approval-workflows \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get leave workflows only

curl -X GET "https://api.companyflow.com/approval-workflows?workflowType=leave" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get workflows for a specific department

curl -X GET "https://api.companyflow.com/approval-workflows?departmentId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Include inactive workflows

curl -X GET "https://api.companyflow.com/approval-workflows?onlyActive=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "987e4567-e89b-12d3-a456-426614174000",
      "companyId": "111e4567-e89b-12d3-a456-426614174000",
      "workflowType": "leave",
      "departmentId": "123e4567-e89b-12d3-a456-426614174000",
      "steps": [
        {
          "step": 1,
          "role_id": "456e4567-e89b-12d3-a456-426614174000",
          "approver_id": null
        },
        {
          "step": 2,
          "role_id": "789e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "isActive": true,
      "createdAt": "2026-03-03T10:30:00Z"
    },
    {
      "id": "654e4567-e89b-12d3-a456-426614174000",
      "companyId": "111e4567-e89b-12d3-a456-426614174000",
      "workflowType": "memo",
      "departmentId": null,
      "steps": [
        {
          "step": 1,
          "role_id": "456e4567-e89b-12d3-a456-426614174000",
          "approver_id": "999e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "isActive": true,
      "createdAt": "2026-02-28T14:20:00Z"
    }
  ]
}

​
Understanding Workflow Scope

Company-Wide Workflows

Workflows with departmentId: null apply to all departments in the company. These are used when there’s no department-specific workflow configured.

Department-Specific Workflows

Workflows with a specific departmentId take precedence over company-wide workflows for that department. Use these when different departments need different approval processes.

​
Filtering Logic

1

Company Filter

Results are automatically filtered to the authenticated user’s company based on the JWT token.
2

Workflow Type Filter

If workflowType is provided, only workflows of that type are returned.
3

Department Filter

If departmentId is provided, returns both department-specific workflows and company-wide workflows (null departmentId).
4

Active Status Filter

By default, only active workflows are returned unless onlyActive=false is specified.

​
Error Responses

​
400 Bad Request
Invalid query parameters (e.g., malformed UUID for departmentId)
​
401 Unauthorized
Missing or invalid authentication token, or insufficient permissions
​
500 Internal Server Error
Server error while retrieving workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us