Pay your first employee

This tutorial takes you through a full loop with the Kua API — from an empty sandbox to a disbursed payroll run you observe via a webhook. Use a kua_test_… key so nothing moves real money.

Everything here runs in test mode. Test data is isolated and auto-purges after 14 days, so experiment freely.

Before you start

A kua_test_… API key with the employees:write and payroll:write scopes (or *).
An employment type to place the employee in. Employment types are created in the dashboard; grab its id from Settings → Employment types. We’ll call it EMPLOYMENT_TYPE_ID below.
Optionally, an SDK installed (npm install @kua/node or pip install kua).

Add an employee

Create the person you’re going to pay. Send an Idempotency-Key so a retry can’t add them twice.

curl https://api.kuahr.com/v1/employees \
  -X POST \
  -H "X-Api-Key: kua_test_your_key_here" \
  -H "Idempotency-Key: tutorial-employee-jane" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "employmentTypeId": "EMPLOYMENT_TYPE_ID",
    "employedAt": "2026-07-01"
  }'

import { Kua } from "@kua/node";
const kua = new Kua({ apiKey: process.env.KUA_API_KEY! });

const employee = await kua.employees.create(
  {
    firstName: "Jane",
    lastName: "Doe",
    email: "[email protected]",
    employmentTypeId: process.env.EMPLOYMENT_TYPE_ID!,
    employedAt: "2026-07-01",
  },
  { idempotencyKey: "tutorial-employee-jane" },
);
console.log("Created employee", employee.id);

import os
from kua import Kua

kua = Kua(api_key=os.environ["KUA_API_KEY"])

employee = kua.employees.create(
    first_name="Jane",
    last_name="Doe",
    email="[email protected]",
    employment_type_id=os.environ["EMPLOYMENT_TYPE_ID"],
    employed_at="2026-07-01",
    idempotency_key="tutorial-employee-jane",
)
print("Created employee", employee.id)

You get back the new employee’s id. Set their salary structure in the dashboard so they’re included in payroll (or via your normal onboarding flow).

Create a payroll run

Build a draft run for the month from your current roster. This does not move money — it stages payroll for approval.

curl https://api.kuahr.com/v1/payroll/runs \
  -X POST \
  -H "X-Api-Key: kua_test_your_key_here" \
  -H "Idempotency-Key: tutorial-run-2026-07" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "month": 7 }'

const run = await kua.payrollRuns.create(
  { year: 2026, month: 7 },
  { idempotencyKey: "tutorial-run-2026-07" },
);
console.log("Draft run", run.id, run.status); // -> "Draft"

run = kua.payroll_runs.create(
    year=2026, month=7, idempotency_key="tutorial-run-2026-07"
)
print("Draft run", run.id, run.status)  # -> "Draft"

The run comes back with status: "Draft".

Approve and disburse

Approval and disbursement are deliberate, owner-gated steps — done from the dashboard (or an owner-authorized flow), not with a scoped API key. This keeps an integration from releasing funds on its own. Approve and disburse the draft run there.As it progresses, Kua emits events: payroll.run.hr_approved, payroll.run.disbursement_started, payroll.line.settled (per employee), and finally payroll.run.disbursed.

Receive the event

Rather than polling, let Kua tell you when the run settles. Register a webhook (once), then handle the delivery.

curl https://api.kuahr.com/v1/webhooks \
  -X POST \
  -H "X-Api-Key: kua_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/kua/webhooks",
    "eventTypes": "payroll.run.disbursed"
  }'

The response includes a signing secret (whsec_…) — store it. Now handle deliveries, verifying each one:

import express from "express";
import { verifySignature } from "@kua/node";

const app = express();
app.post("/kua/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifySignature(req.body, req.header("X-Kua-Signature"), process.env.KUA_WEBHOOK_SECRET!);
  if (!ok) return res.status(400).end();

  const event = JSON.parse(req.body.toString());
  if (event.type === "payroll.run.disbursed") {
    console.log("Run settled:", event.data.runId, "→", event.data.settled, "paid");
  }
  res.status(200).end();
});

import os
from flask import Flask, request, abort
from kua import verify_signature

app = Flask(__name__)

@app.post("/kua/webhooks")
def receive():
    if not verify_signature(request.get_data(), request.headers.get("X-Kua-Signature"), os.environ["KUA_WEBHOOK_SECRET"]):
        abort(400)
    event = request.get_json()
    if event["type"] == "payroll.run.disbursed":
        print("Run settled:", event["data"]["runId"], "→", event["data"]["settled"], "paid")
    return "", 200

Not ready to stand up a public endpoint? Fire a test delivery at your handler with POST /v1/webhooks/{id}/ping, or just poll GET /v1/events.

What you built

You added an employee, staged a payroll run, and wired up a verified, real-time event handler — the backbone of any Kua integration. From here:

Webhooks overview

Delivery, retries, and the full event catalog.

API reference

Every endpoint with a live playground.

​Before you start

​What you built

Webhooks overview

API reference

Before you start

What you built