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.

An LEI (iso6523 with ICD 0199) is verified against the GLEIF register. If GLEIF does not know it, or reports it ANNULLED or DUPLICATE, the response is 400 (for a duplicate, the message names the LEI to use). A LAPSED, RETIRED or inactive LEI, or a legalName that matches none of GLEIF's names for it, is saved and reported in a warnings array on the response.

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.

Once a battery passport is placed on the market, a write that would change a stored operatorIdentifier or facilityIdentifier answers 409 operator_locked (keys names the <role>.<field>); other party edits stay allowed. To correct a locked identifier, mark the passport for deletion and create a new one.

Path parameters

  • idrequired

    string (24 hex chars)

    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

  • tradeName

    string (max 200 chars)

    Registered trade name or registered trade mark. For a battery importer this is one of the details it must mark on the battery (Battery Regulation Art. 41(3)); the compliance check warns when the importer that places the battery on the market lacks it. Shown on the public passport.

    e.g. EuroBat

  • postalAddress

    string (max 500 chars)

    Postal address with a single contact point, as one line. Shown on the public passport.

    e.g. Industriestraße 42, 80339 Munich, Germany

  • email

    string (email)

    Contact e-mail address. Shown on the public passport, so use a company contact address, not a person's.

    e.g. compliance@example.com

  • 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