Leave - Kua API

The Leave endpoints let you read and manage time off programmatically.

Leave is an add-on. The company must have it enabled — otherwise every /v1/leave/* call returns 403 MODULE_NOT_ENABLED (a company admin enables it in Settings → Modules). Calls also need the matching scope: leave:read for reads, leave:write for writes. Writes are not available with a kua_test_ key (add-ons have no sandbox yet).

Leave types

The kinds of leave the company offers (Annual, Sick, …).

curl https://api.kuahr.com/v1/leave/types \
  -H "X-Api-Key: kua_live_your_key_here"

const types = await kua.leave.listTypes();

types = kua.leave.list_types()

Create one (leave:write):

curl https://api.kuahr.com/v1/leave/types \
  -X POST \
  -H "X-Api-Key: kua_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Annual leave", "defaultDaysPerYear": 20, "isPaid": true, "maxCarryoverDays": 5 }'

const type = await kua.leave.createType({
  name: "Annual leave",
  defaultDaysPerYear: 20,
  isPaid: true,
  maxCarryoverDays: 5,
});

leave_type = kua.leave.create_type(
    name="Annual leave", default_days_per_year=20, is_paid=True, max_carryover_days=5
)

Leave requests

List requests (filter by status and/or employeeId), then create, approve, reject, or cancel:

# List pending requests
curl "https://api.kuahr.com/v1/leave/requests?status=Submitted" \
  -H "X-Api-Key: kua_live_your_key_here"

# Submit a request
curl https://api.kuahr.com/v1/leave/requests \
  -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "employeeId": "b2c3…", "leaveTypeId": "5e6f…", "startDate": "2026-08-03", "endDate": "2026-08-07", "reason": "Family trip" }'

# Approve / reject (reject requires a comment) / cancel
curl -X POST https://api.kuahr.com/v1/leave/requests/{id}/approve -H "X-Api-Key: kua_live_your_key_here"
curl -X POST https://api.kuahr.com/v1/leave/requests/{id}/reject -H "X-Api-Key: kua_live_your_key_here" \
  -H "Content-Type: application/json" -d '{ "comment": "Blackout period" }'

const pending = await kua.leave.listRequests({ status: "Submitted" });

const req = await kua.leave.createRequest({
  employeeId: "b2c3…",
  leaveTypeId: "5e6f…",
  startDate: "2026-08-03",
  endDate: "2026-08-07",
  reason: "Family trip",
});

await kua.leave.approveRequest(req.id);
await kua.leave.rejectRequest(req.id, "Blackout period");
await kua.leave.cancelRequest(req.id);

pending = kua.leave.list_requests(status="Submitted")

req = kua.leave.create_request(
    employee_id="b2c3…", leave_type_id="5e6f…",
    start_date="2026-08-03", end_date="2026-08-07", reason="Family trip",
)

kua.leave.approve_request(req.id)
kua.leave.reject_request(req.id, comment="Blackout period")
kua.leave.cancel_request(req.id)

Balances & allocations

Check an employee’s remaining days per type, and grant an allocation:

curl "https://api.kuahr.com/v1/leave/balances?employeeId=b2c3…&year=2026" \
  -H "X-Api-Key: kua_live_your_key_here"

curl https://api.kuahr.com/v1/leave/allocations \
  -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "employeeId": "b2c3…", "leaveTypeId": "5e6f…", "year": 2026, "totalDays": 20 }'

const balances = await kua.leave.balances({ employeeId: "b2c3…", year: 2026 });
await kua.leave.grantAllocation({ employeeId: "b2c3…", leaveTypeId: "5e6f…", year: 2026, totalDays: 20 });

balances = kua.leave.balances(employee_id="b2c3…", year=2026)
kua.leave.grant_allocation(employee_id="b2c3…", leave_type_id="5e6f…", year=2026, total_days=20)

Events

You can also react to leave changes via webhooks: leave_request.submitted, leave_request.approved, leave_request.rejected.

​Leave types

​Leave requests

​Balances & allocations

​Events

Leave types

Leave requests

Balances & allocations

Events