# Kua API

> Build on Kua — payroll, wallets, and payments for African businesses.

## Docs

- [Salary advances](https://docs.kuahr.com/addons/advances.md): Read, request, approve, and reject salary advances via the API.
- [Leave](https://docs.kuahr.com/addons/leave.md): Manage time-off types, requests, balances, and allocations via the API.
- [Performance](https://docs.kuahr.com/addons/performance.md): Manage OKRs, appraisals, and promotions via the API.
- [Approve a salary advance](https://docs.kuahr.com/api-reference/advances/approve-a-salary-advance.md): Approves a pending advance — **this disburses funds** from the company wallet to the employee. Requires `advances:write`.
- [List salary advances](https://docs.kuahr.com/api-reference/advances/list-salary-advances.md): The company's salary advances. Filter with `employeeId`. Requires the `advances:read` scope.
- [Reject a salary advance](https://docs.kuahr.com/api-reference/advances/reject-a-salary-advance.md): Rejects a pending advance. Requires `advances:write`.
- [Request a salary advance](https://docs.kuahr.com/api-reference/advances/request-a-salary-advance.md): Requests an advance for an employee (starts Pending). Requires `advances:write`.
- [Add an employee](https://docs.kuahr.com/api-reference/employees/add-an-employee.md): Adds an employee to your company. Requires the `employees:write` scope. Send an `Idempotency-Key` header to make retries safe.
- [List events](https://docs.kuahr.com/api-reference/events/list-events.md): The company's event timeline in chronological order. Poll incrementally with `since=` (an ISO-8601 timestamp), optionally filter by `eventType`, and cap the page with `limit` (1–500, default 100). This is the pull equivalent of webhooks.
- [Approve a leave request](https://docs.kuahr.com/api-reference/leave/approve-a-leave-request.md): Approves a submitted leave request. Requires `leave:write`.
- [Cancel a leave request](https://docs.kuahr.com/api-reference/leave/cancel-a-leave-request.md): Cancels a leave request. Requires `leave:write`.
- [Create a leave type](https://docs.kuahr.com/api-reference/leave/create-a-leave-type.md): Adds a leave type. Requires the `leave:write` scope.
- [Get leave balances](https://docs.kuahr.com/api-reference/leave/get-leave-balances.md): An employee's remaining balance per active leave type, for a year (defaults to the current year). Requires `leave:read`.
- [Grant a leave allocation](https://docs.kuahr.com/api-reference/leave/grant-a-leave-allocation.md): Grants an employee a number of days of a leave type for a year (idempotent per employee+type+year). Requires `leave:write`.
- [List leave requests](https://docs.kuahr.com/api-reference/leave/list-leave-requests.md): The company's leave requests, newest first. Filter with `status` (Submitted/Approved/Rejected/Cancelled) and/or `employeeId`. Requires `leave:read`.
- [List leave types](https://docs.kuahr.com/api-reference/leave/list-leave-types.md): The types of leave the company offers (Annual, Sick, …). Requires the `leave:read` scope.
- [Reject a leave request](https://docs.kuahr.com/api-reference/leave/reject-a-leave-request.md): Rejects a submitted leave request. A `comment` explaining why is required. Requires `leave:write`.
- [Submit a leave request](https://docs.kuahr.com/api-reference/leave/submit-a-leave-request.md): Creates a leave request for an employee. Requires `leave:write`.
- [Create a payroll run](https://docs.kuahr.com/api-reference/payroll/create-a-payroll-run.md): Builds a **draft** payroll run for the given month from the company's current roster. Approval and disbursement remain separate, deliberate steps. Requires the `payroll:write` scope; a test-mode key rosters only test employees.
- [List payroll runs](https://docs.kuahr.com/api-reference/payroll/list-payroll-runs.md): Returns the company's payroll runs, most recent first. A test-mode key returns only test-mode runs.
- [Add a check-in](https://docs.kuahr.com/api-reference/performance/add-a-check-in.md): Adds a progress note to an objective. Requires `performance:write`.
- [Create an appraisal cycle](https://docs.kuahr.com/api-reference/performance/create-an-appraisal-cycle.md): Opens a cycle and seeds a review for every active employee. Requires `performance:write`.
- [Create an objective](https://docs.kuahr.com/api-reference/performance/create-an-objective.md): Creates an objective with its key results. Requires `performance:write`.
- [Get an objective](https://docs.kuahr.com/api-reference/performance/get-an-objective.md): An objective with its key results and recent check-ins. Requires `performance:read`.
- [List an employee's promotions](https://docs.kuahr.com/api-reference/performance/list-an-employees-promotions.md): Promotion history for an employee, most recent first. Requires `performance:read`.
- [List appraisal cycles](https://docs.kuahr.com/api-reference/performance/list-appraisal-cycles.md): The company's appraisal cycles, newest first. Requires `performance:read`.
- [List cycle reviews](https://docs.kuahr.com/api-reference/performance/list-cycle-reviews.md): Every employee's review within a cycle, with names resolved. Requires `performance:read`.
- [List objectives](https://docs.kuahr.com/api-reference/performance/list-objectives.md): Company OKRs, newest first. Filter by `cycleLabel` and/or `ownerEmployeeId`. Requires `performance:read`.
- [Record a promotion](https://docs.kuahr.com/api-reference/performance/record-a-promotion.md): Records a promotion / role or salary change for an employee. Requires `performance:write`.
- [Submit a manager review](https://docs.kuahr.com/api-reference/performance/submit-a-manager-review.md): Submits the manager review + an overall rating (1–5), completing the review. Requires `performance:write`.
- [Submit a self review](https://docs.kuahr.com/api-reference/performance/submit-a-self-review.md): Submits the employee's self review. Requires `performance:write`.
- [Update a key result](https://docs.kuahr.com/api-reference/performance/update-a-key-result.md): Updates a key result's current value and/or confidence (0–1). Requires `performance:write`.
- [Clear sandbox data](https://docs.kuahr.com/api-reference/test-data/clear-sandbox-data.md): Deletes all of this company's test-mode data immediately (the same data auto-purges after 14 days). Live data is never affected.
- [Delete a webhook endpoint](https://docs.kuahr.com/api-reference/webhooks/delete-a-webhook-endpoint.md): Permanently removes a webhook endpoint. Kua stops delivering events to it immediately.
- [List delivery attempts](https://docs.kuahr.com/api-reference/webhooks/list-delivery-attempts.md): Returns recent delivery attempts for an endpoint — status, attempt count, the HTTP code your server returned, and the last error. Cap the page with `limit` (default 50).
- [List webhook endpoints](https://docs.kuahr.com/api-reference/webhooks/list-webhook-endpoints.md): Returns your registered webhook endpoints (without their secrets).
- [Register a webhook endpoint](https://docs.kuahr.com/api-reference/webhooks/register-a-webhook-endpoint.md): Registers a URL to receive events. The response includes the signing `secret` (`whsec_…`) **once** — store it to verify signatures. Set `eventTypes` to a comma-separated list, or `*` for all events.
- [Send a test event](https://docs.kuahr.com/api-reference/webhooks/send-a-test-event.md): Queues a `webhook.ping` event to this endpoint so you can verify your receiver end-to-end. Inspect the result via the deliveries endpoint.
- [Authentication](https://docs.kuahr.com/authentication.md): Authenticate requests with an API key.
- [Changelog](https://docs.kuahr.com/changelog.md): Notable additions and changes to the Kua API.
- [Data model](https://docs.kuahr.com/concepts/data-model.md): How companies, employees, payroll runs, wallets, and events fit together.
- [Pagination](https://docs.kuahr.com/concepts/pagination.md): How to page through list endpoints.
- [Rate limits](https://docs.kuahr.com/concepts/rate-limits.md): Staying within the API's request limits.
- [Versioning](https://docs.kuahr.com/concepts/versioning.md): How the API evolves without breaking your integration.
- [Errors](https://docs.kuahr.com/errors.md): How the API reports failures.
- [Idempotency](https://docs.kuahr.com/idempotency.md): Safely retry write requests without creating duplicates.
- [Kua API](https://docs.kuahr.com/introduction.md): Integrate payroll, wallets, and payments into your own systems.
- [Quickstart](https://docs.kuahr.com/quickstart.md): Make your first Kua API call in a few minutes.
- [Node.js SDK](https://docs.kuahr.com/sdks/node.md): The official @kua/node client for TypeScript and JavaScript.
- [SDKs](https://docs.kuahr.com/sdks/overview.md): Official client libraries for the Kua API.
- [Python SDK](https://docs.kuahr.com/sdks/python.md): The official kua client for Python.
- [Pay your first employee](https://docs.kuahr.com/tutorials/pay-your-first-employee.md): An end-to-end walkthrough: add an employee, run payroll, and receive the event.
- [Event types & payload](https://docs.kuahr.com/webhooks/events.md): The events Kua emits and the shape of each delivery.
- [Webhooks overview](https://docs.kuahr.com/webhooks/overview.md): Receive Kua events at your own endpoint in real time.
- [Verifying signatures](https://docs.kuahr.com/webhooks/verifying-signatures.md): Confirm a webhook really came from Kua.

## OpenAPI Specs

- [v1](https://api.kuahr.com/openapi/v1.json)