Receiving announcements
Most of these docs describe endpoints ITS publishes. This guide covers the other direction: the endpoints your systems publish so that ITS can call them. The partner contract is the full specification, with every schema.
What ITS calls
| Your system | Implements | ITS calls it to |
|---|---|---|
| National customs system | POST {base_url}/v1/etd/notifications | Announce that a declaration your country is party to has a new version |
| Guarantee platform | GET {base_url}/v1/guarantee/{reference} | Ask whether a guarantee reference is good |
Implement only the paths that belong to your system. A guarantee platform does not receive declarations. If both systems share one national entry, route each path to the correct service. ITS records one base URL per country.
There is nothing to implement for cargo tracking. ITS never asks your systems about an electronic seal. It reads seal positions from the integrated cargo tracking system. See Where are the goods?
The partner contract has one version, v1, and it is the first path segment of every path ITS calls: {base_url}/v1/etd/notifications, {base_url}/v1/guarantee/{reference} and so on. There are no later levels to opt into. The version stays in the path so that a future breaking change can be published beside v1, not in place of it.
Declare your receiving endpoint
This is the one thing ITS cannot find out for itself. Until you declare it, announcements about your declarations wait, visibly, as NO_ENDPOINT.
Declare it in the ITS portal's System integration workspace:
| Field | Meaning |
|---|---|
base_url | Your host and any path prefix, not one operation's path. ITS appends the contract's paths to it. |
auth_mode | OIDC_CLIENT_CREDENTIALS or NONE |
client_id | The client ID you issued to ITS. Required for OIDC_CLIENT_CREDENTIALS. |
token_url | Your token endpoint itself, not an issuer. ITS does not run OIDC discovery. Required for OIDC_CLIENT_CREDENTIALS. |
contract_version | v1. Omitted or blank also means v1. Any other value is refused with 400. |
Move to production walks through declaring a receiving address and having it approved.
NONErequests no bearer token from ITS. Your organisation must agree the receiving endpoint protection with the Secretariat.- With
OIDC_CLIENT_CREDENTIALS, ITS gets a token from yourtoken_urlwith the client ID you issued it, and sends it as a bearer token. Bothclient_idandtoken_urlare required, or the declaration is refused withVAL-ETD-065. - No secret travels with the declaration, and none is returned.
- The Secretariat approves it. Your endpoint's status moves from
DECLAREDtoAPPROVED. ITS calls only an approved endpoint. - A replacement supersedes the old one. It never edits it, so there is always a record of where ITS was calling at any past moment.
- A REC can receive for the members it files for. The recipient is still the country. Only the address belongs to the REC.
The address you declare is where ITS announces declarations and checks guarantees. ITS posts announcements to {base_url}/v1/etd/notifications and asks about a guarantee at {base_url}/v1/guarantee/{reference}, on the same base URL. It is never used to ask about seals.
Announcements
ITS announces every change to a declaration — lodgement, each stamp, each amendment, each attachment, a cancellation — to the countries the declaration concerns. Those are the departure and destination countries, every country that has stamped it, and the country named next.
- A country is never told about its own acts. It already has the response to its own request.
- A REC is never a recipient. The country is the party and is who gets told.
- Every connected country concerned is told. No country is left out because of the contract version it declared. A version nobody else is concerned by is still recorded, by reference, with no recipients.
- An announcement is always signed, and always over HTTPS. It carries the signed version itself, so you need no read (see The signed document). It goes only to the countries a read of the declaration would be served to.
What ITS sends
POST {base_url}/v1/etd/notifications
Content-Type: application/json
X-Correlation-ID: <the correlation id of the act, where there is one>
The body names the version, carries ITS's signature over it, and carries the version itself:
{
"serial_no": "UGEBBTD2608151",
"version_no": 3,
"content_hash": "9f2c8b1e04a7...",
"prev_hash": "3c7592e24dd6...",
"change_type": "ENDORSEMENT",
"verification_code": "0J73MNK1M7Y2BJPG7BDPH6GM8R",
"acting_country": "UG",
"occurred_at": "2026-08-15T08:15:30.123456Z",
"attestation": {
"signature_status": "SIGNED",
"key_id": "9DqHrTmZOBI8oHX7q-V0uP",
"signed_at": "2026-08-15T08:15:30.101223Z",
"signature": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFUzI1NiJ9..MEUCIQ..."
},
"document": { "envelope": {}, "general_information": {}, "...": {} }
}
| Field | Meaning |
|---|---|
serial_no | The declaration. Fetch it with GET /etd/{serial_no}. |
version_no | The version this announcement is about. After a retry, announcements can arrive out of order: treat a version lower than one you hold as old news. |
content_hash | That version's hash. It tells a version you have from one you need, and it is the If-Match for an amendment. |
prev_hash | The content_hash of the version this one follows. Absent on version 1. If the hash you hold for the previous version is not this value, you missed a version or hold a different one: fetch the history rather than trust your copy. |
change_type | ISSUANCE, AMENDMENT, ENDORSEMENT, STATE_CHANGE or ATTACHMENT. Not a state: read the document for that. |
change_categories | For an amendment, the sections it touched, such as ABD. Absent otherwise. |
verification_code | The declaration's public verification code. Constant across versions. |
acting_country | The country the act was performed for. Never your own. Absent when ITS itself closed a transit whose destination is not on ITS. |
occurred_at | When ITS recorded the act, in UTC |
When acting_country is absent, ITS closed the transit itself. Read the declaration and check discharge_kind before you act. Never acquit a guarantee on a SYSTEM_DESTINATION_NOT_ONBOARDED closure. See Reading and searching.
The signed document
Two more fields carry the version and ITS's signature over it:
| Field | Meaning |
|---|---|
attestation | ITS's signature over document: signature_status (SIGNED, or UNSIGNED on a deployment with no signing key, when the other three are absent), key_id, signed_at and signature, a detached JWS. The same keys as a read's envelope.attestation, less content_hash. |
document | The declaration at version_no, exactly the content ITS hashed and signed, in RFC 8785 canonical form. It has the shape of the eTD document in the ITS API and no envelope.attestation. |
To check the body:
- Canonicalise
documentwith RFC 8785 (JCS). It arrives canonical, so this returns the exact bytes that were signed. - Check that their SHA-256 is
content_hash. - Verify
attestation.signatureover those bytes with the keyattestation.key_idnames inGET /.well-known/jwks.json. See Verify a signature for where the key set is served.
- Accept large bodies. A signed document is about 3 KiB with one commodity line and grows by about 280 bytes per further line, to roughly 2.7 MiB at the 9,999-line ceiling. A gateway left at a 1 MiB limit answers the largest declarations
413, which ITS treats as final. - There is one body,
ETD_DOCUMENT_V1. Every announcement is the signed document, sent over HTTPS to your approved receiving endpoint. The partner contract has its schema,EtdDocumentAnnouncement. The consortium ledger anchors ITS's records; it does not carry announcements. A State Party that runs a ledger peer can verify those anchors on its own peer with thekairos-ledger-verifierimage (GET /verify/{serial}/{version}). - The earlier pointer is retired.
ETD_VERSION_NOTIFICATION_V1, which said only that a version existed, is no longer sent to anyone. If your system handled only the pointer, implement the signed document.
How to answer
Answer quickly, then do the work. ITS allows a generous read timeout for this call, but a system that processes the whole declaration before answering will eventually be retried while it is still working on the first copy.
| You answer | ITS does |
|---|---|
2xx, ideally 202 | Records the announcement as sent. A Location header is kept as your receipt. |
408 or 429 | Retries with backoff |
Any other 4xx | Stops. The announcement will never be accepted in this shape. |
5xx, a timeout or a refused connection | Retries with backoff, up to its attempt budget, then marks the announcement DEAD |
Use X-Correlation-ID to tie a redelivery to the first one. A retry is not a new act.
Acknowledge what you processed
Answering 2xx says you received the announcement. Acknowledging says you processed it. Your delivery cursor moves only when you acknowledge.
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ITS_TOKEN" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: 0f4b2c6e-1d8a-4e37-b5f9-7a3c2e1d0b94" \
--data '{ "data": { "version_no": 3, "ack_ref": "KRA-INT-99213" } }' \
"$ITS_PARTNER_URL/etd/UGEBBTD2608151/deliveries/ack"
{
"data": {
"serial_no": "UGEBBTD2608151",
"version_no": 3,
"recipient": "KE",
"already_acknowledged": false,
"acknowledged_at": "2026-08-15T08:19:02.88Z",
"cursor": 3,
"ack_ref": "KRA-INT-99213"
}
}
- It needs the
etd:acknowledgepermission and anIdempotency-Key. - Who is acknowledging comes from your token. There is no
recipientfield in the request. ack_refis your own reference, echoed back. Put your internal message id there, so a support conversation has one identifier both sides can see.- Acknowledging twice answers
200withalready_acknowledged: trueand the first acknowledgement's time. - The cursor only moves forward. An acknowledgement that arrives out of order never rewinds it.
- A REC and the Secretariat cannot acknowledge: neither has a country of its own.
- No announcement of that version for your country is
404RES-ETD-030.
Catch up with the digest
GET /etd/reconciliation/digest?since=2026-08-01T00:00:00Z&limit=200
The digest lists the announcements sent to your country that you have not acknowledged. Run it on a schedule, even with a receiving endpoint. It is the backstop for announcements your system missed, including any marked DEAD.
{
"data": {
"country": "KE",
"outstanding": [
{
"serial_no": "UGEBBTD2608151",
"version_no": 3,
"change_type": "ENDORSEMENT",
"content_hash": "938501f2...",
"sent_at": "2026-08-15T08:15:31.10Z"
}
]
}
}
The digest is measured against what was sent to you, never against what exists. Because you are not told about your own acts, a declaration you acted on is not a gap.
Who has been told
The country that filed a declaration, and the Secretariat, can see how each announcement went:
GET /etd/{serial_no}?include=deliveries
Each row has a recipient, a version_no, a status (PENDING, SENT, ACKED, FAILED or DEAD), attempts, sent_at, acked_at, ack_ref and the last error.
NO_ENDPOINT with attempts: 0 is not a failure. It means that country has not declared a receiving endpoint yet. The announcement waits and is delivered on the day the endpoint is approved. PARTY_SECRET_MISSING waits the same way. Everybody else gets the 404 an unissued serial gets.
Guarantee checks
ITS asks the departure country's guarantee platform whether the reference in field 20 is good, each time someone reads the declaration's guarantee.
GET {base_url}/v1/guarantee/{reference}
{
"status": "success",
"data": {
"guarantee_reference_no": "CTG-KE-2026-0001",
"valid": true,
"amount": 50000.0,
"currency": "USD",
"valid_until": "2026-12-31",
"surety_name": "Example Surety Ltd",
"status": "ACTIVE"
}
}
validis the verdict and must be present. A200without it counts as no answer.404means you never issued this reference. ITS records the guarantee asINVALID, which is a reason to stop a consignment.503means you cannot answer right now. Never use404for "my database is unreachable".surety_nameis shown to customs officers only, never on a public screen.
Until your receiving endpoint is approved, every guarantee on your declarations reads DECLARED_UNVERIFIED.
How ITS calls your guarantee check
The check happens while a truck waits at a barrier, so:
- connect and read timeouts are 2 seconds, with a 2.5-second deadline for the whole call;
- there are no retries: a failed check is reported as a failed check;
- after five consecutive failures, ITS stops calling your system for 30 seconds, then tries once. Your outage never affects another country's answers.
Every failure becomes an honest status, VERIFICATION_UNAVAILABLE. ITS never reports a guarantee as VERIFIED because a call failed.