EUDR TRACES NT API Integration: SOAP, DDS Submission, and Error Handling

What is the EUDR TRACES NT API?

The EUDR TRACES NT API is the European Commission's machine-to-machine interface for managing Due Diligence Statements and Simplified Declarations in bulk. It connects an operator's system to the EUDR Information System without requiring staff to enter every statement through the web interface.

The Commission's due diligence registry page links to the API documentation and advises users to check it regularly because specifications are revised. The interface uses SOAP web services, WSDL and XSD definitions, and WS-Security. It is not a public JSON REST endpoint.

That distinction matters. A vendor may offer a REST wrapper around its own platform, but the underlying EU interface still has its own authentication, schemas, conformance tests, responses, and lifecycle rules.

Account setup remains a separate concern: production and acceptance require their own TRACES NT registration. This article covers the integration itself.

What must the integration control?

An API connection is only the submission edge. A reliable EUDR integration must also control the data required for an EUDR due diligence statement before submission and the record after the Commission responds.

It needs to:

• accept data from defined source systems
• validate required fields and permitted formats
• transform approved data into the Commission schema
• authenticate without exposing the application key
• submit and retrieve reference numbers
• classify errors without retrying invalid data indefinitely
• preserve every request, response, correction, and approval
• send the accepted reference number to the downstream customs process where required

The integration may sit between an ERP, supplier-data store, internal approval workflow, and TRACES NT. Its job is to make those handoffs explicit and recoverable.

The three integration boundaries

The pipeline connects three surfaces:

• Client surface: email attachments, CSV files, ERP exports, spreadsheets
• Operational surface: CRM, shared folders, ticketing, internal dashboards
• Regulatory surface: the EUDR Information System, SOAP services, schema-bound requests, and returned identifiers

The integration does not need to replace these tools. It needs a controlled communication model between them.

Why SOAP and WS-Security change the build

The Commission's operator API specification requires SOAP web-service calls and supplies WSDL and XSD files for the services. Authentication uses an EU Login username and a separate Authentication Key generated in the Information System. The WS-Security policy uses username-with-digest-password credentials over HTTPS and includes non-replay controls.

Treat the Authentication Key as a production credential. Keep it outside workflow definitions and logs, restrict access, and rotate it through a controlled process. A successful HTTPS connection does not prove that the SOAP message, security header, or DDS payload is valid.

The practical result is a layered failure surface:

• transport and availability failures
• authentication or WS-Security failures
• malformed SOAP envelopes
• XSD validation failures
• valid messages containing unacceptable business data
• lifecycle failures, such as attempting an amendment after it is no longer permitted

Do not collapse these into one generic "API failed" state. Each requires a different operational response.

How DDS submission actually completes

Submission and acceptance are not one event. In the Commission's published conformance material, the submission call returns an HTTP success code and a generated UUID. That UUID identifies the statement in later web-service calls. Retrieving the DDS reference number is tested separately.

A production workflow therefore needs at least these local states:

These are recommended internal states, not status names prescribed by the Commission. Keep the EU response alongside the local classification so a reviewer can distinguish what TRACES reported from what your system decided to do next.

When is a retry safe?

The Commission requires error handling as part of conformance testing, but its public materials do not provide a universal retry policy for every SOAP fault. Your integration has to make that policy explicit.

Retry only when repeating the operation cannot conceal a data problem or create an unresolved duplicate. A connection timeout or temporary service failure may be transient. An XSD validation error, rejected field value, expired amendment window, or invalid credential will not become valid because the same request is sent again.

The difficult case is an ambiguous timeout after submission. The request may have reached TRACES even though your application did not receive the response. Do not assume failure and immediately create another statement. Keep the exact outbound request and internal reference, then reconcile against the retrieval service before deciding whether a new submission is necessary.

The API material describes identifiers and retrieval operations, but it does not promise a general idempotency key for submission. Any deduplication rule in your application is therefore an internal control and should be labelled as such.

Conformance testing is part of access

The Commission requires systems connecting to the central EUDR service to pass conformance tests in the acceptance environment before production access. The published operator material describes four minimum tests:

1. establish a basic authenticated connection;
2. submit a DDS;
3. retrieve the reference number for a submitted DDS;
4. handle submission errors.

It also describes tests for amendment, retraction, and retrieving another operator's DDS using its reference and verification numbers. Together these are commonly referred to as CF1 through CF7.

Acceptance and production require separate registration. A successful acceptance test does not create production access, and acceptance submissions have no legal value. Keep environment credentials, endpoints, data, and monitoring separate so a test request cannot be mistaken for a filing.

The Commission explicitly tells API developers to monitor its documentation folder for revisions. Generate clients and validation code from the version of the WSDL and XSD approved for your connection, and treat a specification change as a controlled release rather than silently replacing schemas in production.

Amendments are lifecycle operations, not ordinary retries

Article 5(1) of Commission Implementing Regulation (EU) 2024/3084 generally enables amendment or withdrawal within 72 hours after the reference number becomes available. The window can close sooner when the product has already been placed on the market or exported, the reference has been provided to customs, or the user has been notified of a check.

Implementing Regulation (EU) 2026/1565 adds another blocker once a statement has been referenced in a grouped statement. Article 5(4) permits a competent authority to extend the period by no more than eight calendar days in limited circumstances following an individual and reasoned request.

Your system should calculate an amendment candidate, not declare legal eligibility. Recheck the current statement state, elapsed time, customs handoff, grouping status, and any known check notification immediately before the call. If the operation is no longer permitted, repeated API attempts are not recovery. They are repeated invalid actions.

Reference numbers must reach the right downstream record

Submitting a DDS is not the end of an import or export workflow. Article 26(4) EUDR requires the applicable reference number or simplified-declaration identifier to be made available to customs authorities before release for free circulation or export, subject to the regulation's exceptions.

The integration should therefore bind the returned reference number to the shipment or customs record that caused the statement to be created. A reference stored only in an API log is operationally useless. Record when it was retrieved, which consignment received it, which system consumed it, and whether a later amendment or grouping event changed the identifier that must be communicated.

Under Article 8a introduced in 2026, individual statements can be grouped and replaced. The grouped reference number then represents the underlying statements for the relevant EUDR purposes. Your data model must preserve both the individual relationships and the active grouped reference rather than overwriting the history.

A practical architecture

The implementation does not depend on a specific automation product. It needs clear boundaries:

1. Intake and source preservation. Retain the original ERP export, form, message, or API payload under a stable case identifier.
2. Deterministic validation. Check required data, formats, business rules, GeoJSON constraints, and internal approvals before constructing XML.
3. SOAP adapter. Generate messages from the controlled WSDL and XSD version, apply WS-Security, and keep credentials out of logs.
4. State store. Persist local states, Commission identifiers, attempts, responses, amendments, grouping relationships, and customs handoff.
5. Exception queue. Give each non-transient failure an owner, reason, evidence, and permitted next action.
6. Operational view. Show records awaiting submission, reconciliation, correction, reference retrieval, amendment, or downstream delivery.

Simple orchestration tools can handle notifications and predictable handoffs. Schema construction, security, lifecycle rules, and reconciliation belong in testable code. The database is not just a cache; it is the operational record that connects source data to the regulator response.

This architecture applies the deterministic control model used in regulated workflow automation to the EUDR Compliance Bridge implementation.

When is direct integration worth building?

Direct integration is usually justified when statement volume is recurring, source data already exists in structured systems, manual re-entry causes measurable errors or delay, reference numbers must move into customs or ERP records, and the team can maintain a versioned integration.

It may not be justified when volumes are low, source data is still assembled manually, responsibilities are unresolved, or nobody owns production monitoring and specification changes. In those cases, the Commission web interface may remain the safer option while the operating process matures.

The relevant threshold is not a universal number of statements. Measure submission volume, preparation time, correction rate, time to retrieve and distribute references, and the number of unresolved exceptions. Build when those figures show the failure pattern of manual DDS filing at scale rather than occasional inconvenience.

Technical questions

Does the EUDR TRACES API use REST or SOAP?

The European Commission interface uses SOAP web services defined through WSDL and XSD files with WS-Security. A REST endpoint offered by a software vendor is a wrapper around that vendor's service, not the native Commission interface.

Can a failed DDS submission be retried?

Only after the failure is classified. Temporary transport or availability failures may justify a bounded retry. Validation, authentication, business-rule, and lifecycle failures require correction or escalation. If a timeout leaves the submission outcome unknown, reconcile through retrieval before resubmitting.

Does the submission response contain the DDS reference number?

The Commission's conformance material separates submission from reference retrieval. The submission test returns a generated UUID used in later calls; retrieving the DDS information and reference number is a separate operation.

How do I amend a DDS through the API?

Amendment is a separate conformance-tested capability and is constrained by Article 5 of Implementing Regulation 2024/3084, as amended. Confirm that the amendment remains permitted before calling it; the normal window is 72 hours and can close earlier.

Sources

• European Commission: EUDR Information System and API access
• Commission Implementing Regulation (EU) 2024/3084
• Commission Implementing Regulation (EU) 2026/1565
• European Commission FAQ, fifth iteration

The Commission advises API developers to check its documentation folder regularly. Confirm the current WSDL, XSD, conformance documents, and applicable legal text before implementing a production connection.