Compliance API

Check whether a worker is currently compliant before placing a shift. Designed for scheduling systems to block non-compliant placements at the source.

Authentication

Every request requires an API key. Generate one in API Access. Pass it as a Bearer token:

curl https://yourapp.com/api/v1/compliance/check \
  -G \
  -H "Authorization: Bearer ck_live_xxx" \
  --data-urlencode "worker_id=00000000-0000-0000-0000-000000000000" \
  --data-urlencode "agency_id=00000000-0000-0000-0000-000000000000"

Alternatively, send the key in the x-api-key header.

Rate limiting

Each API key is limited to 120 requests per minute on a sliding window. Successful responses include:

X-RateLimit-Limit — the max requests in the window
X-RateLimit-Remaining — how many remain in the current window
X-RateLimit-Reset — UNIX ms timestamp when the window resets

When exhausted, responses return 429 with the same headers.

GET /api/v1/compliance/check

Check whether a worker is compliant.

Query parameters

Name	Type	Description
`worker_id`required	uuid	ID of the worker to check.
`agency_id`required	uuid	Your agency's ID. Must match the agency tied to your API key.

Response — 200 OK (compliant)

{
  "compliant": true,
  "worker_id": "55e5a3d4-...",
  "worker_name": "Alice Anderson",
  "worker_active": true,
  "checked_at": "2026-05-18T19:14:02.341Z",
  "issues": [],
  "expiring_soon": [
    {
      "credential_type": "BLS Certification",
      "status": "expiring_soon",
      "expiry_date": "2026-07-04"
    }
  ]
}

Response — 200 OK (non-compliant)

A non-compliant worker still returns 200, with compliant: false and details of the failing credentials. This lets clients log every check without exception handling.

{
  "compliant": false,
  "worker_id": "55e5a3d4-...",
  "worker_name": "Bob Brown",
  "worker_active": true,
  "checked_at": "2026-05-18T19:14:02.341Z",
  "issues": [
    {
      "credential_type": "RN License",
      "status": "expired",
      "expiry_date": "2026-04-30"
    },
    {
      "credential_type": "TB Test",
      "status": "missing",
      "expiry_date": null
    }
  ],
  "expiring_soon": []
}

Error responses

Name	Type	Description
`400`	Bad Request	Invalid worker_id or agency_id.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	API key not authorized for the requested agency.
`404`	Not Found	Worker does not exist in this agency.
`429`	Too Many Requests	Rate limit exceeded.

Example: blocking placement

A scheduling system calling CredChain before assigning a shift:

async function canPlace(workerId: string, agencyId: string): Promise<boolean> {
  const res = await fetch(
    `https://yourapp.com/api/v1/compliance/check?worker_id=${workerId}&agency_id=${agencyId}`,
    { headers: { Authorization: `Bearer ${process.env.CREDCHAIN_API_KEY}` } },
  );
  if (!res.ok) throw new Error(`CredChain returned ${res.status}`);
  const { compliant } = await res.json();
  return compliant;
}