SD Migration: V3 to V4¶
Detailed field-by-field mapping
For a complete field-level mapping with types, constraints, and the new fields introduced in V4, see SD V3 → V4 Field-Level Mapping.
V4 introduces a small set of focused changes to the Simplified Declaration service: declaration detail is no longer retrievable over the API, Member States can now submit Simplified Declarations, overviews carry a human-readable reference-number status, a summary address was added, and the internal reference type was widened.
SD: EUDRSimplifiedDeclarationServiceV3 → EUDRSimplifiedDeclarationServiceV4
Namespace changes¶
| Namespace | V3 | V4 |
|---|---|---|
| SD service | .../certificate/eudr/simplified-declaration/v3 |
.../certificate/eudr/simplified-declaration/v4 |
| EUDR common model | .../certificate/eudr/common/v3 |
.../certificate/eudr/common/v4 |
| Body header | .../tracesnt/body/v3 |
.../tracesnt/body/v4 |
Base header namespace is unchanged
The WS-Security / WebServiceClientId base header namespace stays at http://ec.europa.eu/sanco/tracesnt/base/v4 in both V3 and V4. Only the body namespace (which carries BodyIdentity) moves from /body/v3 to /body/v4. Update your BodyIdentity header namespace accordingly when calling V4.
Operation changes¶
Two operations change in V4:
| Operation | Change in V4 |
|---|---|
submitSd |
Adds Member State submission (see below) |
getSdByIdentifiers |
Behaviour changed — see below |
Behaviour change: declaration detail is no longer retrievable over the API¶
In V3, getSdByIdentifiers returned the full declaration content. In V4 this operation no longer returns content — every call returns a NotFoundException fault: "Declaration detail access is possible only over UI".
The operation remains defined in the WSDL so existing bindings still compile, but detail retrieval is now available only through the web UI. Use the overview operations (getSd, getSdByInternalReference) for API-based lookups.
Action required
If your integration relied on getSdByIdentifiers to read back declaration content, update your error handling to treat it as unavailable, and move detail access to the UI.
SD: internal reference type widened¶
The SD internalReferenceNumber type widens from ReferenceNumberType (max length 14) to InternalReferenceNumberType (max length 50), allowing longer operator-defined references.
New: reference-number status on overview responses¶
OverviewType (returned by all get* overview operations) gains an optional referenceNumberInfo field. It carries a human-readable status that explains the current state of the reference number in every lifecycle stage:
- Under system analysis — automated risk analysis has not concluded; no reference number assigned yet.
- Under Competent Authority review (Article 17) — the submission was profiled as high risk and is pending manual review.
- Assigned — the reference number has been released (status
AVAILABLE).
The field is optional and additive — existing clients that ignore it are unaffected.
New: summary address on operator identification¶
EconomicOperatorIdentificationType gains an optional summaryAddress element (SummaryAddressType, carrying name and country) alongside the existing operatorAddress. In SD responses, the represented operator is returned with this abbreviated address — operator name and country only. The element is optional and additive, and is not required on submission.
New: user information messages¶
Responses carry an optional EudrUserMessage header (EudrUserMessageType, max 2000 characters) used for EUDR announcements. It is populated from translatable content and is not present in V3 responses. Clients may read it to surface announcements, or ignore it. See User information messages on the home page.