Passports

Create a single passport.

Create a single Digital Product Passport. The passport is bound to a product (productId) and identified by a GS1 GTIN + serial 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.

Counts as one v1 write AND consumes one DPP slot from the plan's maxDpps quota — when that quota is exhausted and the plan supports overage, returns 402 with an overage_required body. Retry with confirmOverage: true to accept the per-passport charge.

Second-life batteries (Art. 77(7) of Regulation (EU) 2023/1542). A battery that is repurposed, remanufactured or prepared for reuse gets a new passport linked to the original one(s). Send a lineage block naming each predecessor, either by internalPassportId (one of your own passports) or by its resolvable identifier. The platform derives batteryStatus from the triggers, stores the block immutably, and adds a successors link on your own predecessor passports. A rule violation returns 422 with a code-style error (see PassportCreateUnprocessable).

post/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:write)

Headers

Idempotency-Keystring

UUID v4 (or any opaque string ≤ 64 chars) per logical operation. The platform stores the first response for 24 hours and replays it on the same key + same workspace. Reusing the same key with a different request body returns 422.

Request body

productIdstring required

MongoDB ObjectId hex string (24 chars).

partiesPartyMap

Map of role → Party. Each role appears at most once.

confirmOverageboolean

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.

Example request

{
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "identifier": {
    "gtin": "04012345000015"
  },
  "gs1": {
    "gtin": "04012345000015"
  },
  "lineage": {
    "predecessors": [
      {
        "internalPassportId": "6650a1b2c3d4e5f6a7b8c9d0"
      }
    ]
  }
}

Response

Passport created. When the parties block carries an LEI that GLEIF reports as lapsed, retired or inactive, or whose legal name differs, the response adds warnings; an LEI GLEIF does not know, or reports as annulled or duplicate, is a 400 instead (see upsertParty).

_idstring

MongoDB ObjectId hex string (24 chars).

companyIdstring

MongoDB ObjectId hex string (24 chars).

productIdstring

MongoDB ObjectId hex string (24 chars).

templateIdstring

MongoDB ObjectId hex string (24 chars).

identifierKeystring

Canonical dedup key in <scheme>:<parts> form, e.g. gs1:00012345678905:SN-001 or did:did:example:123. Globally unique (sparse index) — the same identifier cannot exist across different accounts.

status'draft' | 'in_review' | 'approved' | 'published' | 'suspended' | 'expired' | 'archived'
completionPercentageinteger
fieldsobject
partiesPartyMap

Map of role → Party. Each role appears at most once.

dynamicDataAsOfstring date-time nullable

measuredAt of the newest battery measurement applied to this passport; null before the first one. Returned with format=full.

publishedAtstring date-time
suspendedAtstring date-time
suspensionReasonstring
archivedAtstring date-time
createdAtstring date-time
updatedAtstring date-time

Example response

{
  "_id": "6650a1b2c3d4e5f6a7b8c9d0",
  "companyId": "6650a1b2c3d4e5f6a7b8c9d0",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d0",
  "identifier": {
    "gtin": "04012345000015"
  },
  "gs1": {
    "gtin": "04012345000015",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000015/21/BP-48V-100-000001"
  },
  "lineage": {
    "predecessors": [
      {
        "internalPassportId": "6650a1b2c3d4e5f6a7b8c9d0"
      }
    ]
  },
  "successors": [
    {
      "passportId": "6650a1b2c3d4e5f6a7b8c9d0"
    }
  ],
  "warnings": [
    {
      "path": [
        "operatorIdentifier"
      ],
      "message": "LEI 353800SZHNPYLZTIX835 has lapsed: its GLEIF record has not been renewed. It still identifies the entity."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.