Skip to content
CardOfficeCardOfficeCardOffice Docs

Quickstart

This walks the full path from nothing to a card order using curl. You need an organisation administrator account on CardOffice.

  1. Create an API key

    In the portal open Settings → Integrations, under API keys, choose New key, and give it these scopes: card_holders:read, card_holders:write, photos:write, orders:read, orders:write.

    The full key is shown once. Store it as a secret, then export it:

    Terminal window
    export CARDOFFICE_KEY="idp_..."
    export CARDOFFICE_API="https://app.cardoffice.nz/api/v1"

  2. Create a card holder

    Terminal window
    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",
        "department": "Nursing",
        "email": "emma.hall@example.ac.nz",
        "expiryDate": "2027-12-31"
      }'
    { "data": { "id": "0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10" } }

  3. Request a photo upload URL

    Terminal window
    curl -sS -X POST "$CARDOFFICE_API/photos" \
      -H "Authorization: Bearer $CARDOFFICE_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "cardHolderId": "0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10",
        "contentType": "image/jpeg",
        "contentLength": 482113
      }'

    The response holds a short-lived uploadUrl and the headers you must send with it.

  4. Upload the file, then finalise

    Send the bytes to uploadUrl with a plain PUT, using exactly the returned headers, then tell CardOffice the file has landed:

    Terminal window
    curl -sS -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" \
      --data-binary @emma.jpg
    

    curl -sS -X POST "$CARDOFFICE_API/photos/$PHOTO_ID/finalize" \
      -H "Authorization: Bearer $CARDOFFICE_KEY"

    The photo is screened automatically and then waits in the staff review queue. An order can only include holders whose photo is approved.

  5. Place an order

    Terminal window
    curl -sS -X POST "$CARDOFFICE_API/orders" \
      -H "Authorization: Bearer $CARDOFFICE_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "cardHolderIds": ["0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10"],
        "idempotencyKey": "enrol-2027-intake-0001"
      }'

    The order is created as a draft. Submit it with PATCH /orders/{id} and {"status": "submitted"}.

© 2026 Secure ID Ltd. All rights reserved.Documentation licence and terms