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

# Data model

> How companies, employees, payroll runs, wallets, and events fit together.

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

<CardGroup cols={2}>
  <Card title="Company" icon="building">
    Your business. The API key is scoped to exactly one company; every object
    below belongs to it.
  </Card>

  <Card title="Employment type" icon="tag">
    A payroll template (e.g. *Full-time*, *Contractor*) that decides whether PAYE,
    pension, and NHF apply. Employees reference one.
  </Card>

  <Card title="Employee" icon="user">
    A person on your payroll, tied to an employment type.
  </Card>

  <Card title="Payroll run" icon="money-check-dollar">
    A month's payroll for the company, built from the current roster. Moves
    through *Draft → HR-approved → Disbursed*.
  </Card>

  <Card title="Wallet" icon="wallet">
    Where money sits — a company funding wallet, and one wallet per employee that
    net pay lands in.
  </Card>

  <Card title="Event" icon="clock-rotate-left">
    An immutable record of something that happened (a run disbursed, an employee
    was added). Delivered via webhooks and queryable at `/v1/events`.
  </Card>
</CardGroup>

## 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](/webhooks/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](/quickstart); 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.