--- title: "Upsert an economic-operator party." method: PATCH path: "/api/v1/passports/{id}/parties/{role}" tags: ["Passports"] --- # Upsert an economic-operator party. `PATCH /api/v1/passports/{id}/parties/{role}` ## Request - Base URL: `https://app.tracepass.eu` - URL: `https://app.tracepass.eu/api/v1/passports/{id}/parties/{role}` - 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`) Create or replace the Party for one role on a passport. 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 in the body — without an identifier the Party doesn't actually identify anyone. If both `gln` and `operatorIdentifier` (scheme `gln`) are set they must match (400). An `operatorIdentifier` of scheme `gln` also fills `gln`. When two roles share the same `gln`, the JSON-LD emission collapses them into a single party with multiple roles attached. An LEI (`operatorIdentifier` or `facilityIdentifier` with scheme `iso6523`, icd `0199`) is verified against the GLEIF register. Rejected (400): not in the GLEIF index, ANNULLED, DUPLICATE (the message names the LEI to use), CANCELLED. Saved with a `warnings` entry: LAPSED (not renewed; still the entity), RETIRED or an inactive entity, or a `legalName` that matches none of GLEIF's names for that LEI. ## Request body - Party: Economic-operator party. At least one of `gln`, `legacyOperatorId`, or `operatorIdentifier` must be set — without an identifier the Party doesn't actually identify anyone. If both `gln` and `operatorIdentifier` (scheme `gln`) are present they must carry the same 13-digit value; a mismatch returns 400 with `path: operatorIdentifier`. An `operatorIdentifier` of scheme `gln` also fills the top-level `gln` field. `facilityIdentifier` never fills `gln`. Typed identifiers are not populated by AI extraction or CSV import. - `gln` string: GS1 Global Location Number (13 digits, mod-10). - `legalName` string, required - `country` string: ISO 3166-1 alpha-2 country code. - `legacyOperatorId` string: Free-text fallback identifier (VAT, EORI, supplier code) for parties without a GLN. - `url` string, uri - `status` string: Server-side status (active, etc.). Returned but ignored on write. - `operatorIdentifier` union: Structured operator identifier per EN 18219 §6.2–6.5. One of four schemes: iso6523, gln, did, doi. When scheme is `gln` this also fills the top-level `gln` field; they must match if both are set (400 with path `operatorIdentifier`). An LEI (iso6523, icd `0199`) is also verified against the GLEIF register (see `upsertParty`). Not populated by AI extraction or CSV import. - OperatorIdentifierISO6523: ISO/IEC 6523 operator identifier. ICD 0199 = LEI (ISO 17442 check digits), 0088 = GLN, 0060 = DUNS. EN 18219 §6.2. - `scheme` 'iso6523', required - `icd` string, required: 4-digit ISO/IEC 6523 ICD (International Code Designator). - `value` string, required: The identifier value within the specified ICD scheme. - OperatorIdentifierGLN: GS1 GLN operator identifier. Also fills the Party's top-level `gln` field; they must agree if both are set. EN 18219 §6.3. - `scheme` 'gln', required - `gln` string, required: 13-digit GS1 Global Location Number. - OperatorIdentifierDID: W3C DID (Decentralised Identifier). Syntax-checked only per EN 18219 §6.4.2(b) — it becomes a verifiable operator identifier when an authorised register issues a VC; the platform does not perform VC verification. EN 18219 §6.4. - `scheme` 'did', required - `did` string, required: Decentralised Identifier matching did::. W3C DID Core requires the method to be lowercase alphanumerics only. - OperatorIdentifierDOI: ISO 26324 DOI operator identifier. A `doi:` or `https://doi.org/` / `https://dx.doi.org/` prefix is accepted on input and stripped; stored bare. EN 18219 §6.5. - `scheme` 'doi', required - `doi` string, required: Digital Object Identifier. Bare `10.<4–9 digit registrant>/` form, or with an accepted prefix (`doi:` / `https://doi.org/` / `https://dx.doi.org/`) which is stripped before storage. - `facilityIdentifier` union: Structured facility identifier per EN 18219 §6.2–6.5. Same four schemes as `operatorIdentifier`; the `gln` variant also accepts an optional `extension` (GS1 SGLN sub-location code). Never fills the top-level `gln` field. Not populated by AI extraction or CSV import. - OperatorIdentifierISO6523: ISO/IEC 6523 operator identifier. ICD 0199 = LEI (ISO 17442 check digits), 0088 = GLN, 0060 = DUNS. EN 18219 §6.2. - `scheme` 'iso6523', required - `icd` string, required: 4-digit ISO/IEC 6523 ICD (International Code Designator). - `value` string, required: The identifier value within the specified ICD scheme. - FacilityIdentifierGLN: GS1 GLN facility identifier. Optionally carries a GS1 SGLN sub-location extension. Does not fill the Party's top-level `gln` field. EN 18219 §6.3. - `scheme` 'gln', required - `gln` string, required: 13-digit GS1 Global Location Number. - `extension` string: GS1 SGLN sub-location extension (identifies a specific location within the GLN). - OperatorIdentifierDID: W3C DID (Decentralised Identifier). Syntax-checked only per EN 18219 §6.4.2(b) — it becomes a verifiable operator identifier when an authorised register issues a VC; the platform does not perform VC verification. EN 18219 §6.4. - `scheme` 'did', required - `did` string, required: Decentralised Identifier matching did::. W3C DID Core requires the method to be lowercase alphanumerics only. - OperatorIdentifierDOI: ISO 26324 DOI operator identifier. A `doi:` or `https://doi.org/` / `https://dx.doi.org/` prefix is accepted on input and stripped; stored bare. EN 18219 §6.5. - `scheme` 'doi', required - `doi` string, required: Digital Object Identifier. Bare `10.<4–9 digit registrant>/` form, or with an accepted prefix (`doi:` / `https://doi.org/` / `https://dx.doi.org/`) which is stripped before storage. ## Response `200` Party upserted. - object - `role` 'manufacturer' | 'importer' | 'authorisedRepresentative' | 'distributor' | 'recycler' | 'producerResponsibilityOrg', required - `party` Party, required: Economic-operator party. At least one of `gln`, `legacyOperatorId`, or `operatorIdentifier` must be set — without an identifier the Party doesn't actually identify anyone. If both `gln` and `operatorIdentifier` (scheme `gln`) are present they must carry the same 13-digit value; a mismatch returns 400 with `path: operatorIdentifier`. An `operatorIdentifier` of scheme `gln` also fills the top-level `gln` field. `facilityIdentifier` never fills `gln`. Typed identifiers are not populated by AI extraction or CSV import. - `gln` string: GS1 Global Location Number (13 digits, mod-10). - `legalName` string, required - `country` string: ISO 3166-1 alpha-2 country code. - `legacyOperatorId` string: Free-text fallback identifier (VAT, EORI, supplier code) for parties without a GLN. - `url` string, uri - `status` string: Server-side status (active, etc.). Returned but ignored on write. - `operatorIdentifier` union: Structured operator identifier per EN 18219 §6.2–6.5. One of four schemes: iso6523, gln, did, doi. When scheme is `gln` this also fills the top-level `gln` field; they must match if both are set (400 with path `operatorIdentifier`). An LEI (iso6523, icd `0199`) is also verified against the GLEIF register (see `upsertParty`). Not populated by AI extraction or CSV import. - OperatorIdentifierISO6523: ISO/IEC 6523 operator identifier. ICD 0199 = LEI (ISO 17442 check digits), 0088 = GLN, 0060 = DUNS. EN 18219 §6.2. - `scheme` 'iso6523', required - `icd` string, required: 4-digit ISO/IEC 6523 ICD (International Code Designator). - `value` string, required: The identifier value within the specified ICD scheme. - OperatorIdentifierGLN: GS1 GLN operator identifier. Also fills the Party's top-level `gln` field; they must agree if both are set. EN 18219 §6.3. - `scheme` 'gln', required - `gln` string, required: 13-digit GS1 Global Location Number. - OperatorIdentifierDID: W3C DID (Decentralised Identifier). Syntax-checked only per EN 18219 §6.4.2(b) — it becomes a verifiable operator identifier when an authorised register issues a VC; the platform does not perform VC verification. EN 18219 §6.4. - `scheme` 'did', required - `did` string, required: Decentralised Identifier matching did::. W3C DID Core requires the method to be lowercase alphanumerics only. - OperatorIdentifierDOI: ISO 26324 DOI operator identifier. A `doi:` or `https://doi.org/` / `https://dx.doi.org/` prefix is accepted on input and stripped; stored bare. EN 18219 §6.5. - `scheme` 'doi', required - `doi` string, required: Digital Object Identifier. Bare `10.<4–9 digit registrant>/` form, or with an accepted prefix (`doi:` / `https://doi.org/` / `https://dx.doi.org/`) which is stripped before storage. - `facilityIdentifier` union: Structured facility identifier per EN 18219 §6.2–6.5. Same four schemes as `operatorIdentifier`; the `gln` variant also accepts an optional `extension` (GS1 SGLN sub-location code). Never fills the top-level `gln` field. Not populated by AI extraction or CSV import. - OperatorIdentifierISO6523: ISO/IEC 6523 operator identifier. ICD 0199 = LEI (ISO 17442 check digits), 0088 = GLN, 0060 = DUNS. EN 18219 §6.2. - `scheme` 'iso6523', required - `icd` string, required: 4-digit ISO/IEC 6523 ICD (International Code Designator). - `value` string, required: The identifier value within the specified ICD scheme. - FacilityIdentifierGLN: GS1 GLN facility identifier. Optionally carries a GS1 SGLN sub-location extension. Does not fill the Party's top-level `gln` field. EN 18219 §6.3. - `scheme` 'gln', required - `gln` string, required: 13-digit GS1 Global Location Number. - `extension` string: GS1 SGLN sub-location extension (identifies a specific location within the GLN). - OperatorIdentifierDID: W3C DID (Decentralised Identifier). Syntax-checked only per EN 18219 §6.4.2(b) — it becomes a verifiable operator identifier when an authorised register issues a VC; the platform does not perform VC verification. EN 18219 §6.4. - `scheme` 'did', required - `did` string, required: Decentralised Identifier matching did::. W3C DID Core requires the method to be lowercase alphanumerics only. - OperatorIdentifierDOI: ISO 26324 DOI operator identifier. A `doi:` or `https://doi.org/` / `https://dx.doi.org/` prefix is accepted on input and stripped; stored bare. EN 18219 §6.5. - `scheme` 'doi', required - `doi` string, required: Digital Object Identifier. Bare `10.<4–9 digit registrant>/` form, or with an accepted prefix (`doi:` / `https://doi.org/` / `https://dx.doi.org/`) which is stripped before storage. - `version` integer, required - `warnings` object[]: Non-blocking findings from the GLEIF check of an LEI the write set (see `upsertParty`). Present only when non-empty. The value was saved; the warning says what GLEIF reports about it. - `role` 'manufacturer' | 'importer' | 'authorisedRepresentative' | 'distributor' | 'recycler' | 'producerResponsibilityOrg' - `path` string[], required - `message` string, required ## Other responses - `400`: Validation error or malformed request. - `401`: Missing or invalid API key. - `403`: Plan-gate or workspace permission denied. - `404`: Resource doesn't exist or is in a different workspace. - `422`: Idempotency-Key reused with a different request body. Use a new key for the new request, or reuse the original body. - `429`: Daily v1 write or passport-read budget exhausted. Resets at 00:00 UTC. --- [API](https://skmtc.dev/tracepass/apis/tracepass-api.md) · [All operations](https://skmtc.dev/tracepass/apis/tracepass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracepass/apis/tracepass-api/revisions/60ddeb25638b?raw)