Developers

Read-only API

Pull your workspace's documents, records and compliance status into dashboards, HR systems or spreadsheets. The API is read-only; changes are made in the app or arrive through document requests.

Available on the Pro and Business plans in business workspaces. Owners and admins create up to 5 keys under Settings → Integrations. For push-style notifications see outgoing webhooks. This page is in English only.

Authentication

Send the key as a bearer token. Keys start with esk_, are shown once when created and can be revoked at any time. Only HTTPS. Requests without a valid key answer 401; a key of a workspace whose plan does not include the API answers 403.

curl -H "Authorization: Bearer esk_…" \
  "https://expirysuite.com/api/v1/documents?status=expiring&limit=50"

Endpoints

• GET /api/v1/documents

  Active documents, soonest expiry first. Filters: status (valid | expiring | expired | missing), subject (record id). Paging: limit (default 50, max 200), offset.

• GET /api/v1/documents/{id}

  One document, including archived ones. Documents of other workspaces answer 404.

• GET /api/v1/subjects

  Records (people, vehicles, equipment…) with document counts (total, expired, expiring, missing). Filter: kind. Same paging.

• GET /api/v1/compliance

  The Compliance page as data: workspace summary, per-record states and every requirement with its state, coverage, covered-until date and pending review. Filter: subject.

Response

JSON with a data field; list endpoints add total, limit and offset. Dates are ISO 8601 (YYYY-MM-DDfor document dates). status is expired when the expiry date has passed, expiring within 30 days, valid otherwise and missing for a required document that has no date yet. Responses never include files, e-mail addresses or upload links.

{
  "data": [
    {
      "id": "8a2b6d10-7c7e-4f4a-9d3c-1e2f3a4b5c6d",
      "title": "Health certificate",
      "type": "health-certificate",
      "subject": {
        "id": "da9f137b-0084-493b-b1c6-df8cdddde223",
        "name": "Ayşe Yılmaz",
        "kind": "person"
      },
      "issueDate": "2025-10-20",
      "expiryDate": "2026-10-15",
      "status": "expiring",
      "daysLeft": 17,
      "createdAt": "2025-10-21T09:12:44.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Limits and errors

300 requests per minute per workspace; above that the API answers 429 with a Retry-After header. Errors are { "error": "…" } with a stable machine-readable code (invalid_api_key, plan_does_not_include_api, invalid_status, not_found, rate_limited). Every key's creation and revocation is written to the workspace audit log.