Skip to main content

​
Overview

This page documents how approvers take action on items awaiting their approval. While there’s no dedicated “update approval” endpoint, approval actions are taken through entity-specific endpoints.
There is no direct PATCH /approval-workflows/{id} endpoint. To modify a workflow, create a new workflow and deactivate the old one by setting isActive: false.

​
Taking Approval Actions

Approvers take actions on specific entities (leave requests, memos) rather than on approval workflows directly. The approval system tracks these actions in the approval history.

​
Available Actions

When reviewing an item, approvers can take one of three actions:

Approve

Accept the request and advance to the next approval step. If this is the final step, the request becomes fully approved.

Reject

Deny the request. This ends the approval process and sets the request status to rejected.

Request Changes

Ask the submitter to modify the request before it can be approved. The submitter must update and resubmit.

​
Approval Workflow Process

1

Submission

An employee submits a leave request or memo that requires approval
2

Workflow Assignment

The system identifies the appropriate approval workflow based on:
  • Entity type (leave/memo/expense)
  • Employee’s department (department-specific or company-wide workflow)
  • Workflow active status
3

Step 1 Approval

The first approver (based on workflow step 1) receives the item for review and can approve, reject, or request changes
4

Subsequent Steps

If approved, the item moves to step 2, then step 3, etc., until all workflow steps are completed
5

Final Status

Once all approvers approve, the request status becomes “approved”. If any approver rejects, the status becomes “rejected”.

​
Entity-Specific Approval Endpoints

Approval actions are taken through the specific entity endpoints:

​
Leave Requests

PATCH /leave-requests/{id}/approve
PATCH /leave-requests/{id}/reject

​
Memos

PATCH /memos/{id}/approve
PATCH /memos/{id}/reject
See the respective entity documentation (Leave Requests API, Memos API) for detailed request/response schemas for approval actions.

​
Modifying Approval Workflows

To update an existing approval workflow:
1

Create New Workflow

Use the Create Approval Workflow endpoint to create a new workflow with the updated configuration
2

Test New Workflow

Verify the new workflow works correctly with test submissions
3

Deactivate Old Workflow

Once confirmed, you can deactivate the old workflow by creating a new one with the same parameters but isActive: false, or by implementing a deactivation endpoint
Existing in-progress approvals continue using the workflow they started with. Only new submissions use the newly activated workflow.

​
Status Transitions

Entities flow through these statuses during the approval process:
Initial status when an employee is preparing a request but hasn’t submitted it yet. Not yet in the approval workflow.
Submitted and awaiting approval. The current_step field indicates which approval step it’s at.
All required approvers have approved the request. It has completed the full workflow successfully.
At least one approver rejected the request. Depending on business rules, it may be resubmitted (returning to Pending).
The request is complete and has been archived for record-keeping. Typically applied to approved requests after completion.

​
Current Step Tracking

Entities in approval workflows have a current_step field that indicates:
  • Step 1: Awaiting first approver
  • Step 2: First approval complete, awaiting second approver
  • Step N: Awaiting Nth approver
Query the entity to see its current step and compare against the workflow definition to determine who the current pending approver is.

​
Approval Permissions

Who can approve depends on the workflow step configuration: 
{
  "step": 1,
  "role_id": "manager-role-uuid",
  "approver_id": null
}
// Any user with the manager role can approve

​
Best Practices

Track approval history: Use the Get Approval History endpoint to display who approved what and when
Provide clear comments: Encourage approvers to add comments explaining their decision, especially when rejecting or requesting changes
Set reasonable workflow lengths: Too many approval steps slow down processes. 2-3 steps is typical for most workflows
Use role-based approvals: Prefer role-based approval (null approver_id) over specific approvers for flexibility when employees change roles

Create Workflow

Set up new approval workflows for your company

List Workflows

View all configured approval workflows

Approval History

Review complete approval audit trail

Leave Requests

Manage leave request approvals

Build docs developers (and LLMs) love

Get started for freeTalk to us