TracePass
Get started
Passports

Get a single passport

Read one passport by ID. Default response includes the full passport — translatable fields carry their sourceLocale and a per-locale translations map. Pass ?lang=<locale> to have the server resolve every field through the public-viewer chain (viewer-locale translation → source-locale value → English → first-applied → universal source) and return one resolved value per field; the translations map is dropped from lang-resolved responses.

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

Get a single passport

Read one passport by ID. Default response includes the full passport — translatable fields carry their sourceLocale and a per-locale translations map. Pass ?lang=<locale> to have the server resolve every field through the public-viewer chain (viewer-locale translation → source-locale value → English → first-applied → universal source) and return one resolved value per field; the translations map is dropped from lang-resolved responses.

Pass ?format=full to additionally include template-derived field labels, units, and access levels alongside each value — useful for building a custom viewer or audit report. The two query params combine: ?format=full&lang=de returns the labels in DE plus values resolved to DE.

Alternate addressing: GET /api/v1/passports/by-serial/{serial} returns the same shape and accepts the same query params. There's also a GET /api/v1/passports/{id}/qr endpoint that returns a freshly-rendered SVG / PNG of the QR code (or a Data Matrix with symbology=datamatrix) — useful when you want our renderer instead of encoding gs1.digitalLinkUri yourself.

Path parameters

  • idrequired

    string (24 hex chars)

    Passport ID.

Query parameters

  • format

    string

    Set to full to include template field labels, units, and access levels.

  • lang

    string (ISO 639-1)

    Resolve field values to a single locale server-side. One of the 24 EU locales.

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

Request

# Default response — full data, consumer resolves locales itself
curl -sS https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

# Single-locale response with template labels
curl -sS \
  "https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1?format=full&lang=de" \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "gs1": {
    "gtin": "04012345000016",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
  },
  "status": "published",
  "completionPercentage": 87,
  "fields": {
    "batteryChemistry": {
      "value": "NMC",
      "source": "manual",
      "status": "approved",
      "accessLevel": "public",
      "sourceLocale": "en",
      "translations": {
        "de": { "value": "NMC", "source": "ai-haiku-4.5", "generatedAt": "2026-05-02T10:00:00.000Z" }
      }
    }
  }
}

Related endpoints