FairCheck API

The FairCheck API lets you submit payslips for Australian payroll-compliance
evaluation and read back the results. Payslips are checked against the relevant
modern award — or an enterprise agreement (EBA), where one applies — and every
evaluation produces an immutable, auditable compliance run.

• Base URL: https://<your-host>/api/v1
• Format: JSON in, JSON out (Content-Type: application/json)
• Authentication: bearer ApiToken — see Authentication
• Model: submissions are accepted immediately (202 Accepted) and evaluated asynchronously. Poll the payslip to read the result, or configure a completion webhook.

Response envelope

Every response uses the same envelope:

{
  "data": { },
  "errors": null,
  "meta": { }
}

• data — the resource(s) for the request (object or array), or null on error.
• errors — an array of human-readable strings, or null on success.
• meta — pagination and counts (e.g. { "page": 1, "pages": 4, "count": 80 }, or { "count": 3, "created": 2 } on a bulk create).

Async evaluation

A successful POST /payslips returns 202 Accepted — the payslip is
persisted and queued, not yet evaluated. Poll the payslip (or configure a
webhook) to read the verdict:

sequenceDiagram
    participant C as Your client
    participant API as FairCheck API
    participant W as Worker
    C->>API: POST /payslips
    API-->>C: 202 Accepted { status: "pending", links.self }
    API->>W: enqueue evaluation
    W->>W: extract → normalize → evaluate
    Note over W: status: processing → completed
    C->>API: GET /payslips/:id
    API-->>C: 200 { status: "completed", compliance: { … } }
    opt webhook configured
        W-->>C: POST payslip.completed (signed, non-PII)
    end

The data for each submission carries a status and a links.self you can poll:

{
  "data": [
    { "id": "payslip_abc123", "status": "pending",
      "links": { "self": "/api/v1/payslips/payslip_abc123" } }
  ],
  "meta": { "count": 1, "created": 1 }
}

status moves through pending → processing → completed (or failed). The
compliance verdict is present once status is completed — see
Payslips.

Tenant scoping

Every request is scoped to one account (tenant). The account is resolved
server-side from your token's user and its memberships — a client-supplied id
is honoured only if the user belongs to that account. To target a specific
account when your user belongs to several, send either:

• an account_id query parameter, or
• an X-Account-Id request header

with the account's prefixed id. Otherwise the request defaults to the user's
personal account, then their lowest-id account.

Idempotency

For a single POST /payslips, send an Idempotency-Key header to make retries
safe — a repeat with the same key returns the existing payslip instead of
creating a duplicate (meta.created will be 0). Bulk submissions derive their
own per-item keys from the payload, so the header is ignored for batches.

Status codes

Endpoints

• Authentication — obtaining and using a token
• Payslips — submit and read payslip compliance
• Timesheets — upload hours worked as dated shifts
• Webhooks — inbound push + outbound completion
• Accounts & users — supporting endpoints