API overview

The REST API lets another system manage card holders, photographs and orders, and read issued cards. It is JSON over HTTPS.

Base URL

https://app.cardoffice.nz/api/v1

A self-hosted deployment uses its own host with the same /api/v1 prefix.

Requests

• Send Content-Type: application/json on requests with a body.
• Authenticate every request except card verification with a bearer token. See Authentication.
• Identifiers are UUIDs. Dates are YYYY-MM-DD; timestamps are ISO 8601.
• Unknown fields in a request body are ignored.

Responses

A successful response wraps its payload in data:

{ "data": { "id": "0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10" } }

Lists add a meta object:

{
  "data": [ { "...": "..." } ],
  "meta": { "page": 1, "pageSize": 25, "total": 312 }
}

Failures use a consistent shape. See Errors.

Pagination

List endpoints take page (from 1) and pageSize (default 25, maximum 200). meta.total is the number of matching records.

Feeds designed for incremental synchronisation use a keyset cursor instead of page numbers. See Sync feeds.

Rate limits

Each API key is limited to 120 requests per minute by default. Beyond that the API returns 429 with a Retry-After header giving the seconds to wait. Self-hosted deployments can change the ceiling with RATE_LIMIT_API_PER_MIN.

The public verification endpoint is limited per caller IP address instead, at 120 requests per minute.

Idempotency and retries

• POST /orders accepts an idempotencyKey. A repeat with the same key returns the original result with 200 instead of creating a second order.
• POST /photos/{id}/finalize can be repeated safely.
• Read requests can always be retried.

Endpoints

Area	Endpoints
Card holders	List, create, get, update, look up by external ID
Photos	Request an upload URL, finalise an upload
Cards	List issued cards
Orders	List, create, get, submit, cancel
Verification	Check a card by its verification code (no key needed)
Sync feeds	Cursor feeds and write-back endpoints for legacy-database bridges

The full description is available as OpenAPI 3.1.