Python

Install

Use Python 3.9 or later. The distribution is kuahr; application imports remain kua. The unrelated PyPI project named kua is not this SDK.

python -m venv .venv
source .venv/bin/activate
python -m pip install kuahr==0.3.3

On Windows, activate with .venv\Scripts\activate instead. Pin dependencies in your application. View the public source.

Make a Test request

Create a Test key with payroll:read as described in quickstart, and set KUA_API_KEY in your runtime environment.

import os
from kua import Kua
with Kua(
    api_key=os.environ["KUA_API_KEY"],
) as kua:
    runs = kua.payroll_runs.list()
    print(runs)

Expected: an array, including [] for an empty Test roster. The context manager closes the HTTP connection. The client uses api.kuahr.com for both Test and Live keys.

Choose a task

• Create an employee: kua.employees.create(..., idempotency_key=key) with employees:write.
• Prepare a payroll draft: kua.payroll_runs.create(year=..., month=..., idempotency_key=key) with payroll:write; list with payroll:read.
• Receive webhooks: separate authorised Live key and webhook grants.
• Poll events: separate Live key, events:read, exact timestamp/ID cursor and durable checkpoints.
• Workforce: leave, advances and performance, all Live-key only.

Handle errors and retries

from kua import KuaError
try:
    with Kua(api_key=os.environ["KUA_API_KEY"]) as kua:
        runs = kua.payroll_runs.list()
except KuaError as error:
    print(error.status, error.code)  # Redacted operational log only.

The client does not automatically retry. Transport errors are distinct from an HTTP KuaError; an interrupted write may already have succeeded. Follow retry guidance and troubleshooting before generating a new key or replaying a decision.

Verify webhook signatures

The helper is named verify_signature, with tolerance_seconds=300 by default. Pass raw request bytes and the signature header. Signature verification shows the receiver responsibilities.

Use kua.webhooks.history(endpoint_id, delivery_id) to inspect attempts. Replay is kua.webhooks.replay(endpoint_id, delivery_id, request_key=key, reason=reason). Keep the same persisted key and reason after an interrupted response; Pending is queued, not delivered. Follow webhook recovery. Signing-secret rotation is a dashboard action.

Done when: the official distribution is installed in the application environment and the Test list request succeeds at api.kuahr.com. Continue with the selected task and go-live readiness.

Recovery availability

Webhook delivery-history and manual-replay methods are available at api.kuahr.com. Use an authorised Live key and recovery prerequisites. SDK installation does not grant replay permission.