Skip to main content

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 systemImplementsITS calls it to
National customs systemPOST {base_url}/v1/etd/notificationsAnnounce that a declaration your country is party to has a new version
Guarantee platformGET {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:

FieldMeaning
base_urlYour host and any path prefix, not one operation's path. ITS appends the contract's paths to it.
auth_modeOIDC_CLIENT_CREDENTIALS or NONE
client_idThe client ID you issued to ITS. Required for OIDC_CLIENT_CREDENTIALS.
token_urlYour token endpoint itself, not an issuer. ITS does not run OIDC discovery. Required for OIDC_CLIENT_CREDENTIALS.
contract_versionv1. Omitted or blank also means v1. Any other value is refused with 400.
note

Move to production walks through declaring a receiving address and having it approved.

  • NONE requests 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 your token_url with the client ID you issued it, and sends it as a bearer token. Both client_id and token_url are required, or the declaration is refused with VAL-ETD-065.
  • No secret travels with the declaration, and none is returned.
  • The Secretariat approves it. Your endpoint's status moves from DECLARED to APPROVED. 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": {}, "...": {} }
}
FieldMeaning
serial_noThe declaration. Fetch it with GET /etd/{serial_no}.
version_noThe 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_hashThat version's hash. It tells a version you have from one you need, and it is the If-Match for an amendment.
prev_hashThe 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_typeISSUANCE, AMENDMENT, ENDORSEMENT, STATE_CHANGE or ATTACHMENT. Not a state: read the document for that.
change_categoriesFor an amendment, the sections it touched, such as ABD. Absent otherwise.
verification_codeThe declaration's public verification code. Constant across versions.
acting_countryThe country the act was performed for. Never your own. Absent when ITS itself closed a transit whose destination is not on ITS.
occurred_atWhen 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:

FieldMeaning
attestationITS'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.
documentThe 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:

  1. Canonicalise document with RFC 8785 (JCS). It arrives canonical, so this returns the exact bytes that were signed.
  2. Check that their SHA-256 is content_hash.
  3. Verify attestation.signature over those bytes with the key attestation.key_id names in GET /.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 the kairos-ledger-verifier image (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 answerITS does
2xx, ideally 202Records the announcement as sent. A Location header is kept as your receipt.
408 or 429Retries with backoff
Any other 4xxStops. The announcement will never be accepted in this shape.
5xx, a timeout or a refused connectionRetries 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:acknowledge permission and an Idempotency-Key.
  • Who is acknowledging comes from your token. There is no recipient field in the request.
  • ack_ref is 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 200 with already_acknowledged: true and 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 404 RES-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"
}
}
  • valid is the verdict and must be present. A 200 without it counts as no answer.
  • 404 means you never issued this reference. ITS records the guarantee as INVALID, which is a reason to stop a consignment.
  • 503 means you cannot answer right now. Never use 404 for "my database is unreachable".
  • surety_name is 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.