---
title: "List passports."
method: GET
path: "/api/v1/passports"
tags: ["Passports"]
---

# List passports.

`GET /api/v1/passports`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.tracepass.eu/api/oauth/authorize`, token URL `https://app.tracepass.eu/api/oauth/token`, scopes: `passports:read`)

Paginated list of passports the workspace owns. Filter by
product, status, or a free-text search across GTIN and
serial.

## Query parameters

- `page` integer
- `limit` integer
- `productId` string: MongoDB ObjectId hex string (24 chars).
- `status` 'draft' | 'in_review' | 'approved' | 'published' | 'suspended' | 'expired' | 'archived'
- `search` string

## Response `200`

Paginated passport list.

- PaginatedPassports
  - `total` integer, required
  - `page` integer, required
  - `limit` integer, required
  - `totalPages` integer, required
  - `items` PassportSummary[], required
    - `_id` string: MongoDB ObjectId hex string (24 chars).
    - `productId` string: MongoDB ObjectId hex string (24 chars).
    - `identifier` union
      - object: GS1 GTIN + serial number (scheme "gs1"). Required for battery passports.
        - `scheme` 'gs1', required
        - `gtin` string, required: GS1 GTIN with a valid check digit. Accepts 8 digits (GTIN-8), 12 digits (GTIN-12/UPC-A), 13 digits (GTIN-13/EAN-13), or 14 digits (GTIN-14). All forms are left-padded to 14 digits before storage; stored and returned values are always 14 digits.
        - `serialNumber` string, required
        - `digitalLinkUri` string, uri
      - object: ISO/IEC 15459 identifier (scheme "iso15459"). Also valid for battery passports.
        - `scheme` 'iso15459', required
        - `issuingAgencyCode` string, required
        - `primaryId` string, required
        - `serial` string
        - `raw` string: The ISO/IEC 15459 unique identifier: issuing agency code + primary id + serial, concatenated. Always derived by the server from the parts; a value sent on create is ignored. Present on every read.
        - `uri` string, uri: The ISO/IEC 18975 Data-Identifier query-form resolver URL generated by the server, following EN 18219 Table B.12: `https://id.tracepass.eu/?.25P=<IAC><primaryId>&.S=<serial>` (`.S` component omitted when there is no serial; parameter values are percent-encoded). Always derived by the server from the identifier parts; present on every read.
      - object: IEC 61406 Identification Link — an https URI (scheme "iec61406"). Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
        - `scheme` 'iec61406', required
        - `uri` string, uri, required
      - object: W3C DID Core identifier (scheme "did"). Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
        - `scheme` 'did', required
        - `did` string, required
        - `method` string, required
      - object: Digital Object Identifier — ISO 26324 (scheme "doi"). Stored as bare `10.<registrant>/<suffix>`. Any `https://doi.org/` or `doi:` prefix is stripped on input; the DOI resolves as `https://doi.org/<doi>`. `granularity` is REQUIRED per EN 18219 §5.6.2(b): a DOI product identifier must declare whether it identifies the product model, a production batch, or an individual item. Not valid for battery passports (Battery Regulation Art. 77(3) requires gs1 or iso15459).
        - `scheme` 'doi', required
        - `doi` string, required
        - `granularity` 'model' | 'batch' | 'item', required: Whether the DOI identifies the product model, a production batch, or an individual item (EN 18219 §5.6.2(b)). Must be supplied on create; returned unchanged on read.
    - `identifierKey` string: Canonical dedup key in `<scheme>:<parts>` form.
    - `gs1` GS1Block
      - `gtin` string, required: GS1 GTIN with a valid check digit. Accepts 8 digits (GTIN-8), 12 digits (GTIN-12/UPC-A), 13 digits (GTIN-13/EAN-13), or 14 digits (GTIN-14). All forms are left-padded to 14 digits before storage; stored and returned values are always 14 digits.
      - `serialNumber` string, required
      - `digitalLinkUri` string, uri
    - `status` 'draft' | 'in_review' | 'approved' | 'published' | 'suspended' | 'expired' | 'archived'
    - `completionPercentage` integer
    - `publishedAt` string, date-time

## Other responses

- `401`: Missing or invalid API key.
- `403`: Plan-gate or workspace permission denied.
- `429`: Daily v1 write or passport-read budget exhausted. Resets at 00:00 UTC.

---

[API](https://skmtc.dev/tracepass/apis/tracepass-api.md) · [All operations](https://skmtc.dev/tracepass/apis/tracepass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracepass/apis/tracepass-api/revisions/60ddeb25638b?raw)