Documentation

Leave

Sync leave types and leave requests, and apply, approve, or reject leave from your app.

Requires scope: leave

Apply requires employeeId, leaveTypeId (or leaveType name), startDate, endDate, and reason (min 10 chars).

Approve/reject require approverId — a manager, HR, org-admin, or it-admin in the same organization.

Leave balances: GET /integrations/leave-balances/:employeeId?year=2026

Endpoints

GET/api/v1/integrations/leave-typesBearer auth

List leave types

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "leaveTypes": [
      {
        "id": "665f1a2b3c4d5e6f7a8b9c33",
        "name": "Casual Leave",
        "daysPerYear": 12,
        "isActive": true,
        "color": "#3B82F6"
      }
    ]
  }
}

GET/api/v1/integrations/leavesBearer auth

List leave requests

Query: from, to, status, employeeId, page, limit

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "leaves": [
      {
        "id": "665f1a2b3c4d5e6f7a8b9c44",
        "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
        "leaveType": "Casual Leave",
        "status": "pending",
        "startDate": "2026-11-20T00:00:00.000Z",
        "endDate": "2026-11-21T00:00:00.000Z",
        "days": 2,
        "reason": "Family function attendance"
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1 }
  }
}

GET/api/v1/integrations/leave-balances/:employeeIdBearer auth

Get leave balances for an employee

Query: year (defaults to current year)

GET/api/v1/integrations/leaves/:idBearer auth

Get one leave request

Example response

{
  "success": true,
  "status": 200,
  "data": {
    "leave": {
      "id": "665f1a2b3c4d5e6f7a8b9c44",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "leaveType": "Casual Leave",
      "leaveTypeId": "665f1a2b3c4d5e6f7a8b9c33",
      "status": "pending",
      "startDate": "2026-11-20T00:00:00.000Z",
      "endDate": "2026-11-21T00:00:00.000Z",
      "days": 2,
      "reason": "Family function attendance",
      "isHalfDay": false,
      "notes": null
    }
  }
}

POST/api/v1/integrations/leavesBearer auth

Apply for leave on behalf of an employee

Alias: POST /integrations/leaves/apply

Request body

{
  "employeeId": "<employeeId>",
  "leaveTypeId": "<leaveTypeId>",
  "startDate": "2026-11-20",
  "endDate": "2026-11-21",
  "reason": "Family function attendance",
  "isHalfDay": false,
  "notes": "optional"
}

Example response

{
  "success": true,
  "status": 201,
  "message": "Leave request submitted",
  "data": {
    "leave": {
      "id": "665f1a2b3c4d5e6f7a8b9c44",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "leaveType": "Casual Leave",
      "status": "pending",
      "startDate": "2026-11-20T00:00:00.000Z",
      "endDate": "2026-11-21T00:00:00.000Z",
      "days": 2,
      "reason": "Family function attendance"
    }
  }
}

POST/api/v1/integrations/leaves/:id/approveBearer auth

Approve a leave request

Request body

{
  "approverId": "<managerOrHrUserId>",
  "notes": "Approved"
}

Example response

{
  "success": true,
  "status": 200,
  "message": "Leave request approved",
  "data": {
    "leave": {
      "id": "665f1a2b3c4d5e6f7a8b9c44",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "leaveType": "Casual Leave",
      "status": "approved",
      "startDate": "2026-11-20T00:00:00.000Z",
      "endDate": "2026-11-21T00:00:00.000Z",
      "days": 2
    }
  }
}

POST/api/v1/integrations/leaves/:id/rejectBearer auth

Reject a leave request

Request body

{
  "approverId": "<managerOrHrUserId>",
  "reason": "Insufficient notice period"
}

Example response

{
  "success": true,
  "status": 200,
  "message": "Leave request rejected",
  "data": {
    "leave": {
      "id": "665f1a2b3c4d5e6f7a8b9c44",
      "employeeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "leaveType": "Casual Leave",
      "status": "rejected",
      "startDate": "2026-11-20T00:00:00.000Z",
      "endDate": "2026-11-21T00:00:00.000Z",
      "days": 2,
      "reason": "Family function attendance"
    }
  }
}