Skip to main content
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

​
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

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 workflows: Use when different departments have different approval requirements
  • Company-wide workflows: Leave departmentId as null to apply the same workflow across all departments
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us