TracePass
Get started
Passports

Suspend a passport

Reversible suspend. The public viewer flips to the suspended state page (HTTP 423 with structured body); QR scans effectively die without the URL going to 404. Use for recalls, disputes, internal holds, or product-quality investigations. Republish from the dashboard once resolved.

POST/api/v1/passports/{id}/suspend
Download OpenAPI 3.1
POST/api/v1/passports/{id}/suspend

Suspend a passport

Reversible suspend. The public viewer flips to the suspended state page (HTTP 423 with structured body); QR scans effectively die without the URL going to 404. Use for recalls, disputes, internal holds, or product-quality investigations. Republish from the dashboard once resolved.

Optional body { reason: string } — surfaces in the passport.suspended webhook payload and the dashboard audit trail (truncated at 500 chars). Empty body is fine; the suspend still fires the webhook. Counts as one v1 write. Honours Idempotency-Key. The matching POST /api/v1/passports/by-serial/{serial}/suspend is the by-serial alternate.

Refused once placed on the market. A passport registered as placed on the market, or with its registration under way, answers 409 passport_placed_on_market: it must stay public, so correct its data instead.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID.

Headers

  • Authorizationrequired

    string

    Bearer <token> — either a tp_ API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4.

Body fields

  • reason

    string (≤ 500)

    Free-text suspension reason.

    e.g. Quality investigation pending — batch BB-2026-04-12.

Request

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/suspend \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Quality investigation pending — batch BB-2026-04-12." }'

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "suspended",
  "suspendedAt": "2026-05-09T16:00:00.000Z",
  "suspensionReason": "Quality investigation pending — batch BB-2026-04-12."
}

Related endpoints