Create Approval Workflow

Create an approval workflow for leave requests, memos, or expenses

POST /approval-workflows

{
  "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
}

{
  "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"
  }
}

Overview

Approval workflows define multi-step approval processes for different entity types within your company. Each workflow consists of sequential steps where approvers review and take action on submissions.

Only users with Super Admin or HR Manager roles can create approval workflows.

Request Body

workflowType · string · required

Type of workflow to create. Must be one of:

• leave - For leave requests
• memo - For company memos
• expense - For expense claims

companyId · uuid

Company ID for the workflow. If not provided, uses the authenticated user’s company ID.

departmentId · uuid

Optional department ID to restrict this workflow to a specific department. If null, the workflow applies company-wide.

steps · array · required

Array of approval steps. Each step is processed sequentially.

Example structure:

[
  {
    "step": 1,
    "role_id": "123e4567-e89b-12d3-a456-426614174000",
    "approver_id": null
  },
  {
    "step": 2,
    "role_id": "223e4567-e89b-12d3-a456-426614174000"
  }
]

• step (integer): Step sequence number
• role_id (uuid): Required role for this approval step
• approver_id (uuid, optional): Specific approver, or null for any user with the role

isActive · boolean · default: "true"

Whether the workflow is active. Inactive workflows are not used for new submissions.

Response

success · boolean

Indicates if the request was successful

data · object

The created approval workflow object

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

isActive · boolean

Whether this workflow is currently active

createdAt · timestamp

When the workflow was created

Example Request

curl -X POST https://api.companyflow.com/approval-workflows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowType": "leave",
    "departmentId": "123e4567-e89b-12d3-a456-426614174000",
    "steps": [
      {
        "step": 1,
        "role_id": "manager-role-id",
        "approver_id": null
      },
      {
        "step": 2,
        "role_id": "hr-manager-role-id",
        "approver_id": null
      }
    ],
    "isActive": true
  }'

{
  "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
}

{
  "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"
  }
}

Workflow Design Best Practices

Sequential vs Parallel Approvals

Currently, approval workflows are sequential - each step must be completed before the next begins. Design your steps accordingly, with the most critical approver first.

Department-Specific vs Company-Wide

• Department-specific workflows: Use when different departments have different approval requirements
• Company-wide workflows: Leave departmentId as null to apply the same workflow across all departments

Role-Based vs Specific Approvers

• Set approver_id to null to allow any user with the specified role to approve
• Set a specific approver_id to require approval from a particular person

Error Responses

400 Bad Request

Invalid request body or workflow configuration

401 Unauthorized

Missing or invalid authentication token, or insufficient permissions

500 Internal Server Error

Server error while creating the workflow