TracePass
Get started
Passports

Upsert an economic-operator party

Create or replace the Party for a single role on a passport. The role path segment determines the slot you're writing — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Sending the same role twice is an upsert: the existing block is replaced atomically.

PATCH/api/v1/passports/{id}/parties/{role}
Download OpenAPI 3.1
PATCH/api/v1/passports/{id}/parties/{role}

Upsert an economic-operator party

Create or replace the Party for a single role on a passport. The role path segment determines the slot you're writing — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Sending the same role twice is an upsert: the existing block is replaced atomically.

Identity is fully expressed by the body: `legalName` (required), `gln` (GS1 Global Location Number — strongly recommended for multi-role disambiguation), `country` (ISO 3166-1 alpha-2), `legacyOperatorId` (VAT / EORI / supplier code as a free-text fallback), `url`. At least one of `gln` or `legacyOperatorId` must be set — without an identifier the Party doesn't actually identify anyone. When two roles share the same `gln`, the JSON-LD emission collapses them into one party with multiple roles.

Counts as one v1 write. Honours `Idempotency-Key`. The Battery Regulation requires at least { manufacturer, importer (if applicable), recycler } before a passport is accepted; the platform's regulatory-completeness scorecard surfaces missing roles in the dashboard. The matching `DELETE /api/v1/passports/{id}/parties/{role}` removes a role idempotently.

Path parameters

  • idrequired

    ObjectId

    Passport ID.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

  • rolerequired

    enum

    One of: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Roles outside this list return 400.

    e.g. recycler

Headers

  • Authorizationrequired

    string

    `Bearer <api-key>`.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 per logical operation.

Body fields

  • legalNamerequired

    string (1-200 chars)

    Legal entity name as it appears in the commercial register. Required — a Party with no name doesn't help any procurement reader, regardless of which identifier it carries.

    e.g. EuroBat Recyclers GmbH

  • gln

    string (13 digits)

    GS1 Global Location Number with valid mod-10 check digit. Strongly recommended — when two roles share the same `gln`, the JSON-LD emits a single party with both roles attached. Must validate as a real GLN; partial / digits-only strings return 400.

    e.g. 4012345678901

  • country

    string (ISO 3166-1 alpha-2)

    Two-letter uppercase country code — e.g. `DE`, `BG`, `FR`.

    e.g. DE

  • legacyOperatorId

    string (1-120 chars)

    Free-text fallback identifier for parties that don't have a GLN — VAT number, EORI, supplier code, or any internal ID your ERP carries. Required when `gln` is omitted.

    e.g. DE123456789

  • url

    string (URL, max 500 chars)

    Organisation page — typically the company website or a corporate-info subpage.

    e.g. https://eurobat-recyclers.example

Request

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/parties/recycler \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example"
  }'

Response

{
  "role": "recycler",
  "party": {
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example",
    "status": "active"
  },
  "version": 5
}

Related endpoints