List Approval Workflows

Retrieve approval workflows for your company with optional filtering

GET /approval-workflows

List Approval Workflows

cURL

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

Show ApprovalWorkflow properties

id · uuid

Unique identifier for the workflow

companyId · uuid

Company ID this workflow belongs to

workflowType · string

Type of workflow: leave, memo, or expense

departmentId · uuid

Department ID if department-specific, null if company-wide

steps · array

Array of approval steps in sequential order. Each step contains:

• step (integer): Step sequence number
• role_id (uuid): Required role for approval
• approver_id (uuid): Specific approver if set, null otherwise

isActive · boolean

Whether this workflow is currently active

createdAt · timestamp

When the workflow was created

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