> ## 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.

# Salary advances

> Read, request, approve, and reject salary advances via the API.

The Advances endpoints let you manage salary advances — early access to earned
wages, repaid from the employee's upcoming pay.

<Note>
  Salary advance is an **add-on**. The company must have it enabled — otherwise
  every `/v1/advances*` call returns `403 MODULE_NOT_ENABLED` (a company admin
  enables it in **Settings → Modules**). Calls need the matching scope:
  `advances:read` for reads, `advances:write` for writes.
</Note>

<Warning>
  **Approving an advance disburses real money** from the company wallet to the
  employee. For that reason, advance **writes are not available with a `kua_test_`
  key** (`400 TEST_MODE_UNSUPPORTED`) — use a live key, and gate the `advances:write`
  scope carefully.
</Warning>

## List advances

Optionally filter by `employeeId`:

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

  ```ts Node theme={null}
  const advances = await kua.advances.list({ employeeId: "b2c3…" });
  ```

  ```python Python theme={null}
  advances = kua.advances.list(employee_id="b2c3…")
  ```
</CodeGroup>

Amounts are in **minor units** (e.g. kobo) — `5000000` is ₦50,000.

## Request an advance

Starts a `Pending` advance for an employee (`advances:write`):

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.kuahr.com/v1/advances \
    -X POST -H "X-Api-Key: kua_live_your_key_here" -H "Content-Type: application/json" \
    -d '{ "employeeId": "b2c3…", "amountMinor": 5000000, "termMonths": 3 }'
  ```

  ```ts Node theme={null}
  const advance = await kua.advances.request({
    employeeId: "b2c3…",
    amountMinor: 5_000_000,
    termMonths: 3,
  });
  ```

  ```python Python theme={null}
  advance = kua.advances.request(employee_id="b2c3…", amount_minor=5_000_000, term_months=3)
  ```
</CodeGroup>

An employee can have only one open advance at a time.

## Approve or reject

Approving disburses funds and builds the repayment schedule; rejecting cancels
the request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kuahr.com/v1/advances/{id}/approve -H "X-Api-Key: kua_live_your_key_here"
  curl -X POST https://api.kuahr.com/v1/advances/{id}/reject  -H "X-Api-Key: kua_live_your_key_here"
  ```

  ```ts Node theme={null}
  await kua.advances.approve(advance.id); // disburses money
  await kua.advances.reject(advance.id);
  ```

  ```python Python theme={null}
  kua.advances.approve(advance.id)  # disburses money
  kua.advances.reject(advance.id)
  ```
</CodeGroup>

## Events

React to the advance lifecycle via [webhooks](/webhooks/events):
`salary_advance.requested`, `salary_advance.approved`, `salary_advance.rejected`.