TracePass
Get started
Passports

Create a passport

Create a single Digital Product Passport. The passport is bound to a product (productId) and identified by a GS1 GTIN + serial number that's unique within that GTIN. New passports start in `draft` status — fields are populated via subsequent PATCH calls and the passport is published from the dashboard once review is complete.

POST/api/v1/passports
Download OpenAPI 3.1
POST/api/v1/passports

Create a passport

Create a single Digital Product Passport. The passport is bound to a product (productId) and identified by a GS1 GTIN + serial number that's unique within that GTIN. New passports start in `draft` status — fields are populated via subsequent PATCH calls and the passport is published from the dashboard once review is complete.

GTIN must be 14 digits (or a 13-digit EAN, padded to 14) with a valid GS1 check digit and not yet registered to another tenant. Counts as one v1 write AND consumes one DPP slot from your plan's `maxDpps` quota — when that quota is exhausted and your plan supports overage, the call returns 402 with an `overage_required` body; retry with `confirmOverage: true` to accept the per-passport charge.

Honours the optional `Idempotency-Key` header — the platform replays the original 201 response for 24 hours on the same key, so a network retry is safe.

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 (or any opaque string ≤ 64 chars) per logical operation. The first response is replayed for 24 hours.

Body fields

  • productIdrequired

    ObjectId

    ID of the product the passport belongs to. Must belong to the API key's company.

    e.g. 6650a1b2c3d4e5f6a7b8c9d0

  • identifier

    ProductIdentifier

    EN 18219 scheme-tagged identifier. Exactly one of `identifier` or the legacy `gs1` block is required. Accepts five schemes: `gs1` (GTIN + serial), `iso15459` (non-GS1 agency ID), `iec61406` (IEC Identification Link URI), `did` (W3C DID), `doi` (Digital Object Identifier). For `doi`, `granularity` is REQUIRED — must be `"model"`, `"batch"`, or `"item"` (EN 18219 §5.6.2(b): a DOI must declare whether it identifies the product model, a production batch, or an individual item). Battery passports accept `gs1` and `iso15459` only; `iec61406`, `did`, and `doi` are rejected per Battery Regulation Art. 77(3), which requires an ISO/IEC 15459-based identifier.

  • gs1.gtin

    string (14 digits, or 13-digit EAN)

    GTIN-14 with a valid GS1 check digit. Part of the legacy `gs1` block — prefer `identifier` with `scheme: "gs1"` for new integrations. Must not already be registered by another tenant.

    e.g. 04012345000016

  • gs1.serialNumber

    string (1-100 chars)

    Serial unique within the GTIN. The most common pattern is the product model + a sequence (BP-48V-100-000001).

    e.g. BP-48V-100-000001

  • parties

    Record<role, Party>

    Optional structural parties block. A map keyed by role — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Each value is a Party. See the Upsert party endpoint for the per-Party body shape. Roles can also be added or replaced after creation via PATCH /api/v1/passports/{id}/parties/{role}.

  • lineage

    LineageInput

    Battery passports only. A battery that has been prepared for re-use, prepared for repurposing, repurposed or remanufactured needs a new battery passport linked to the passport(s) of the original battery (Battery Regulation Art. 77(7)). Send `{ predecessors: [ { internalPassportId | identifier, trigger } ] }` with up to 10 predecessors: `internalPassportId` for one of your own passports, `identifier` (its resolvable URI) for any other. `trigger` is `preparation_for_reuse`, `preparation_for_repurposing`, `repurposing` or `remanufacturing`. `batteryStatus` is derived from the triggers, the block is immutable after create, and your own originals gain a `successors` link. A battery placed on the market before 18 February 2027 has no original passport: send an empty list with `noPredecessorReason`. Rule violations return 422 with the rule code in `error`, e.g. `duplicate_predecessor`, `predecessor_not_found`, `status_trigger_mismatch`.

  • confirmOverage

    boolean

    Accept the per-passport overage charge when the plan's `maxDpps` quota is already exhausted. Required only after a 402 response on a previous attempt.

Request

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000016",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Response

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "companyId": "6650a0b1c2d3e4f5a6b7c8d9",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "gs1": {
    "gtin": "04012345000016",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
  },
  "status": "draft",
  "completionPercentage": 32,
  "fieldCounts": {
    "total": 52,
    "empty": 35,
    "approved": 17,
    "pendingReview": 0,
    "flagged": 0
  },
  "fields": { "...": "...seeded from product defaults + template defaults + company prefill..." },
  "createdAt": "2026-05-09T10:00:00.000Z"
}

Related endpoints