Border Agency
Authenticate and retrieve Goods Load data and documents shared with your organisation.
Want to see the whole lifecycle? Your role only receives — you never publish a Goods Load yourself, so nothing reaches you until a freight forwarder publishes one. To drive the flow end to end on staging, run the sandbox scripts: the Freight Forwarder script publishes a full consignment, and the notifications land on your endpoint as they would in production.
TWIN sends you two ISN signals automatically, at your registered endpoint: a Pre-Notification when a freight forwarder creates or updates a Goods Load, and a Despatch when they add a twin:despatched event. You can then query TWIN directly to retrieve the full Goods Load data and any attached documents.
Throughout this guide, Goods Load means the same thing as consignment — TWIN's schema and API say "consignment", while freight forwarders say "Goods Load" day to day.
Receiving a signal does not by itself grant access to the data. Goods Load data is only readable
if the freight forwarder has registered a data-sharing policy covering your role and country.
Without it, all read requests return 404 Not Found.
Authenticate
Exchange your email and password for a session cookie.
POST /authentication/login
Content-Type: application/json{
"email": "you@example.com",
"password": "your-password"
}The JWT arrives via Set-Cookie. Include it on every subsequent request.
See Authentication for full details.
Read the Goods Load
The signal contains the Goods Load globalId and originRecordID — the freight forwarder's internal reference. Use the globalId to fetch the full Goods Load — parties, transport details, events, and any TWIN-resolved fields.
GET /supply-chain/data-space/consignments/<globalId>
Cookie: access_token=<jwt>See Get a Consignment for the full response shape.
List Goods Load documents
Fetch the list of documents attached to the Goods Load:
GET /supply-chain/data-space/consignments/<globalId>/documents
Cookie: access_token=<jwt>Returns a list of DocumentAttachment objects — see List Consignment Documents for the full response shape.
To download a specific document, use the href from the response directly, or fetch it by ID:
GET /supply-chain/data-space/consignments/<globalId>/documents/<documentId>
Cookie: access_token=<jwt>