Create an employee

Before you start

Use a company Test key at https://api.kuahr.com with employees:write. You need an employment type belonging to that company, provided by an authorised administrator. Employment-type setup is outside the public /v1 API. Use synthetic employee details and an address you control; do not use a real worker’s data for this tutorial.

The company must satisfy workspace and country-specific eligibility. Scope permission is not a substitute for these checks.

Create one employee

Generate and persist an operation-specific idempotency key before sending this write. Set EMPLOYMENT_TYPE_ID to the actual company employment type, EMPLOYEE_EMAIL to your controlled synthetic address, and OPERATION_KEY to the persisted key. Keep the exact request body for retries.

curl --fail-with-body https://api.kuahr.com/v1/employees \
  -X POST -H "X-Api-Key: $KUA_API_KEY" \
  -H "Idempotency-Key: $OPERATION_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"firstName\":\"Test\",\"lastName\":\"Employee\",\"email\":\"$EMPLOYEE_EMAIL\",\"employmentTypeId\":\"$EMPLOYMENT_TYPE_ID\",\"employedAt\":\"2026-11-01\"}"

Verify the outcome

HTTP 201 returns the created employee’s id, firstName, lastName and email. Retain that ID with your own source-record ID, key mode, company and operation key. Employee creation does not set a salary, create a payment or grant Kola consent.

There is no public employee-list, employee-update or salary-setting route in this contract. For onboarding/pay setup, hand the returned ID to an authorised company administrator for that company. Do not invent an employees:read scope or infer a successful salary setup from the creation response.

Recover or stop

• Validation or unknown employment type: correct the supplied company data, then deliberately start a new logical operation if its request body changes.
• Lost response: retry with the same credential, path, key and body bytes; do not create a second operation. A different credential after rotation has a different idempotency namespace.
• 409 IDEMPOTENCY_KEY_MISMATCH: compare the stored original body. A legacy reconciliation conflict requires investigation, not a new key.
• Need to remove fixtures: use Test-data reset only after coordinating with the company’s other testers; it clears company Test data rather than deleting a single employee.

Done when: you have a 201 response or its idempotent replay and have retained the employee ID. Continue to prepare a payroll draft, with the salary/setup handoff completed first.