> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuahr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leave

> Manage time-off types, requests, balances, and allocations via the API.

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

<Note>
  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).
</Note>

## Leave types

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kuahr.com/v1/leave/types \
    -H "X-Api-Key: kua_live_your_key_here"
  ```

  ```ts Node theme={null}
  const types = await kua.leave.listTypes();
  ```

  ```python Python theme={null}
  types = kua.leave.list_types()
  ```
</CodeGroup>

Create one (`leave:write`):

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

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

  ```python Python theme={null}
  leave_type = kua.leave.create_type(
      name="Annual leave", default_days_per_year=20, is_paid=True, max_carryover_days=5
  )
  ```
</CodeGroup>

## Leave requests

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

<CodeGroup>
  ```bash cURL theme={null}
  # 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" }'
  ```

  ```ts Node theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Balances & allocations

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

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

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

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Events

You can also react to leave changes via [webhooks](/webhooks/events): `leave_request.submitted`,
`leave_request.approved`, `leave_request.rejected`.