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.

At least one of `gln`, `legacyOperatorId`, or `operatorIdentifier` must be set — without an identifier the Party doesn't actually identify anyone. `operatorIdentifier` carries a scheme-tagged structured identifier per EN 18219 §6.2–6.5 (iso6523, gln, did, doi). When scheme is `gln` it also fills the top-level `gln` field; if both are provided they must match (400 with path `operatorIdentifier`). `facilityIdentifier` uses the same schemes and identifies where the operator operates — it never fills `gln`. Typed identifiers are not set by AI extraction or CSV import.

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 <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 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

  • operatorIdentifier

    object (EN 18219 §6.2–6.5)

    Structured operator identifier per EN 18219 §6.2–6.5. Requires `scheme` plus scheme-specific fields. Schemes: `iso6523` — ICD (4-digit ISO/IEC 6523 code, e.g. 0199 = LEI, 0088 = GLN, 0060 = DUNS) + `value`; `gln` — 13-digit GLN (also fills the top-level `gln` field; they must match if both are set); `did` — DID URI in `did:<method>:<id>` form (syntax-checked only, EN 18219 §6.4.2(b)); `doi` — DOI in bare `10.<registrant>/<suffix>` form (`doi:` / `https://doi.org/` prefix accepted and stripped). Not populated by AI extraction or CSV import.

    e.g. { "scheme": "iso6523", "icd": "0199", "value": "529900T8BM49AURSDO55" }

  • facilityIdentifier

    object (EN 18219 §6.2–6.5)

    Structured facility identifier per EN 18219 §6.2–6.5 — identifies where the operator operates, not the operator itself. Uses the same four schemes as `operatorIdentifier`; the `gln` variant additionally accepts `extension` (GS1 SGLN sub-location code identifying a specific location within the GLN). Never fills the top-level `gln` field. Not populated by AI extraction or CSV import.

    e.g. { "scheme": "gln", "gln": "4012345678901", "extension": "1" }

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