TracePass
Get started
Passports

Delete a passport

A passport marked for deletion → soft delete. Deleting a passport that has been published takes two steps: first POST /api/v1/passports/{id}/mark-for-deletion, then this DELETE. Nothing is erased: the passport disappears from the API (every v1 call on it answers 404 from then on) and from every public surface. Scanning its QR code shows a page saying the passport has ended, and its machine-readable formats answer 410 Gone. Returns the passport with status: "deleted" and fires the passport.deleted webhook.

DELETE/api/v1/passports/{id}
Download OpenAPI 3.1
DELETE/api/v1/passports/{id}

Delete a passport

A passport marked for deletion → soft delete. Deleting a passport that has been published takes two steps: first POST /api/v1/passports/{id}/mark-for-deletion, then this DELETE. Nothing is erased: the passport disappears from the API (every v1 call on it answers 404 from then on) and from every public surface. Scanning its QR code shows a page saying the passport has ended, and its machine-readable formats answer 410 Gone. Returns the passport with status: "deleted" and fires the passport.deleted webhook.

A never-published passport → permanent delete. A passport with status draft or in_review and publishedAt: null is removed together with everything that belongs only to it: its AI extractions, scan and service events, ownership transfers, EPCIS event links, and any uploaded documents and stored files no other record uses. Documents shared with other passports or products stay, with the link removed. This is irreversible. No webhook fires; the deletion is recorded in your account's audit trail. On Free plans it returns 403 Forbidden with a reason pointing at POST /api/v1/passports/{id}/archive.

Any other status → 409 Conflict. The body carries a hint ("A published passport is deleted in two steps: mark it for deletion first.") and a reason.

Deletion through the API needs a paid plan. Counts as one v1 write. Honours Idempotency-Key.

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.

Request

curl -sS -X DELETE \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "status": "deleted",
  "deletedAt": "2026-11-02T09:30:00.000Z",
  "deletedReason": "recycled"
}

Related endpoints