Data model - Kua API

Everything in the Kua API hangs off a single company — the one that owns your API key. You never see or touch another business’s data.

The core objects

Company

Your business. The API key is scoped to exactly one company; every object below belongs to it.

Employment type

A payroll template (e.g. Full-time, Contractor) that decides whether PAYE, pension, and NHF apply. Employees reference one.

Employee

A person on your payroll, tied to an employment type.

Payroll run

A month’s payroll for the company, built from the current roster. Moves through Draft → HR-approved → Disbursed.

Wallet

Where money sits — a company funding wallet, and one wallet per employee that net pay lands in.

Event

An immutable record of something that happened (a run disbursed, an employee was added). Delivered via webhooks and queryable at /v1/events.

How they relate

Company
├── Employment types
├── Employees ───────────── (each references an employment type)
├── Payroll runs ────────── (built from the roster of active employees)
│     └── settles into ──── Employee wallets
├── Wallets (company + per-employee)
└── Events ──────────────── (emitted as things happen → webhooks)

Identifiers

Every object has a stable, unique id (a UUID string). IDs are safe to store and reference. Timestamps are ISO-8601 in UTC (e.g. 2026-07-25T10:30:00+00:00), and money is expressed in the object’s currency (currencyIsoCode, e.g. NGN).

The payroll lifecycle

Creating a run gives you a draft — nothing moves money yet. Approval and disbursement are deliberate, separate steps (handled in the dashboard or via owner-gated flows), so an API integration can prepare payroll without being able to release funds on its own. You observe each transition through events: payroll.run.hr_approved, payroll.run.disbursed, and so on.

Test mode

A kua_test_… key operates in a sandbox that mirrors the live API but never moves real money. Test data is isolated from live data and auto-purges after 14 days; you can also wipe it on demand with POST /v1/test-data/clear. Build and test against kua_test_…, then switch to kua_live_… when you’re ready.

​The core objects