Developer documentation · v1

Build with your organization’s employee identities.

Connect the tools your teams already use. Start with a work number, resolve the employee, and keep your application’s own accounts and permissions.

Create an integration

An organization administrator opens Developers and reviews coverage and agreed terms, enables access, then creates a named test integration.

Call from your backend

Keep the credential in a secret manager. Test against fictional employees before requesting live access.

Record the identity

Keep the source, environment, organization and employee record ID with the name/number snapshot.

Access belongs to the organization

Each credential is bound to one organization, one environment and employee identification. It returns a record ID, work number, display name and employment status. The organization limits live access by department, position scope and location. Personal accounts are optional. Photos, personal contact details, PINs, documents and payroll amounts are excluded.

A matched roster entry does not authenticate the person entering the number. Your app still decides who may use a route, device or function. Sign-on, personal verification and broader data access are separate future capabilities.

Request

POST /api/integrations/v1/employees/resolve
Authorization: Bearer <backend credential>
Content-Type: application/json

{
  "organizationId": "<your organization>",
  "environment": "test",
  "payrollNumber": "0012",
  "operationId": "<persisted UUID for this identification>"
}

Matched response

{
  "schemaVersion": 1,
  "requestId": "<lookup request ID>",
  "identitySource": "kaaziai",
  "organizationId": "<your organization>",
  "environment": "test",
  "resolution": "matched",
  "metering": {
    "operationId": "<persisted UUID for this identification>",
    "duplicateOperation": false
  },
  "employee": {
    "employeeRecordId": "test-employee-0012",
    "payrollNumber": "0012",
    "displayName": "Example Employee",
    "employmentStatus": "active"
  },
  "identityEvidence": {
    "level": "roster_matched",
    "checkedAt": "<ISO timestamp>",
    "recordVersion": "<opaque revision>",
    "freshness": "online",
    "cachePolicy": "no-store",
    "reusableForNewDuty": false
  }
}

Test fixtures

Test keys never read the live employee roster.

0012: Active employee without a personal account
INACTIVE: inactive
DUPLICATE: ambiguous
INVALID: invalid_employee_record
MISSING: not_found

Freshness and limits

Request a fresh lookup for every new duty or handover. Do not reuse a previous match to authorize a new duty.
Keep the original identity and evidence on actions queued during an existing duty. Reconnect must not relabel historical work.
Per client: burst of 10; refill of 60 requests per minute. Honor Retry-After on 429 or 503.
Server lookup deadline: 8 seconds. Retry transient errors at most once with bounded jitter; unavailable identity stays unverified.
Persist a unique operationId for each identification and reuse it for all retries. Successful retries are resolved fresh but counted once.
Payroll is a string. Preserve leading zeros and let KaaziAI resolve canonical spelling and legacy aliases.

Errors your app must handle

400 / 413 / 415 · invalid_request

Correct request fields, body size or JSON content type.

401 / 403 · not_authorized

Check developer enablement, employee coverage, backend credential, employer, environment, grant and expiry.

404 · not_found

No match in the authorized employer. Do not search another employer.

409 · ambiguous / inactive

Require employer review; never pick a duplicate or silently activate a former employee.

422 · invalid_employee_record

The employer must correct missing fields or a recreated identity.

429 / 503 · rate_limited / unavailable

Honor Retry-After. Keep current operations available under your explicit unverified fallback policy.

Errors contain schemaVersion, requestId and error: code, message, retryable. Treat the code as the contract; do not parse message text.