Card holders

A card holder is a person who needs a card.

The card holder object

Field	Type	Notes
`id`	uuid	Assigned by CardOffice
`externalId`	string, max 64	Your identifier for the person. Unique within the organisation
`firstName`	string, required, max 120
`lastName`	string, required, max 120
`preferredName`	string, max 120	Used on cards and verification when set
`holderType`	enum, required	`student`, `staff`, `contractor`, `visitor`, `access`
`department`	string, max 160
`campus`	string, max 120
`email`	string
`phone`	string, max 40
`expiryDate`	`YYYY-MM-DD`	When the card stops being valid
`status`	enum, default `active`	`active`, `inactive`, `archived`
`notes`	string, max 2000	Accepted on write
`customFields`	object	Free-form key/value data, available to card designs
`currentPhotoId`	uuid or null	Read-only. The approved photo, if any
`version`	integer	Read-only. Increments on each change
`createdAt`, `updatedAt`	timestamp	Read-only

List card holders

GET/card-holdersscope: card_holders:read

Query parameter	Description
`page`, `pageSize`	Pagination. `pageSize` maximum 200
`q`	Search across name, external ID and email
`status`	`active`, `inactive` or `archived`
`department`	Exact match

Results are ordered by last name, then first name.

curl -sS "$CARDOFFICE_API/card-holders?status=active&department=Nursing&pageSize=50" \
  -H "Authorization: Bearer $CARDOFFICE_KEY"

{
  "data": [
    {
      "id": "0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10",
      "externalId": "S1024",
      "firstName": "Emma",
      "lastName": "Hall",
      "preferredName": null,
      "holderType": "student",
      "department": "Nursing",
      "campus": null,
      "email": "emma.hall@example.ac.nz",
      "phone": null,
      "expiryDate": "2027-12-31",
      "status": "active",
      "currentPhotoId": null,
      "customFields": {},
      "version": 1,
      "createdAt": "2027-02-01T02:14:09.311Z",
      "updatedAt": "2027-02-01T02:14:09.311Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 50, "total": 1 }
}

Create a card holder

POST/card-holdersscope: card_holders:write

Send the fields above. firstName, lastName and holderType are required. Returns 201 with the new id.

curl -sS -X POST "$CARDOFFICE_API/card-holders" \
  -H "Authorization: Bearer $CARDOFFICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "S1024",
    "firstName": "Emma",
    "lastName": "Hall",
    "holderType": "student",
    "expiryDate": "2027-12-31",
    "customFields": { "course": "BN-NURS" }
  }'

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

Status	When
`409 conflict`	A holder with the same `externalId` already exists
`422 validation_failed`	A field failed validation

Get a card holder

GET/card-holders/{id}scope: card_holders:read

Returns the card holder object, or 404.

Look up by external ID

GET/card-holders/by-external-id/{externalId}scope: card_holders:read

An exact match on your identifier, with none of the fuzzy matching of q. Use it whenever you need to be certain you have the right person, such as when matching files named by student number. URL-encode the value.

Update a card holder

PATCH/card-holders/{id}scope: card_holders:write

Send only the fields to change. Returns the updated card holder object.

curl -sS -X PATCH "$CARDOFFICE_API/card-holders/$ID" \
  -H "Authorization: Bearer $CARDOFFICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department": "Midwifery", "expiryDate": "2028-12-31" }'

An empty body returns 400. Each change is recorded in the audit log with the API key that made it.

cardoffice.nz ·Status ·Security ·Support