Location Operator
Authenticate, retrieve Goods Load data and documents, and send match events back to TWIN.
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.
When a carrier booking event is published for a Goods Load routed through one of your registered locations, TWIN sends a notification to your endpoint. You can then retrieve the Goods Load data, inspect the documents, and send a match event back to confirm.
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 notification does not by itself grant access to the data. Goods Load data and
documents are only readable if the freight forwarder has registered a data-sharing policy covering
your role and locations. Without it, 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 notification contains the Goods Load globalId. Use it to fetch the full Goods Load — parties, transport details, equipment, and events.
GET /supply-chain/data-space/consignments/<globalId>
Cookie: access_token=<jwt>See Get a Consignment for the full response shape.
Read Goods Load documents
Fetch all 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>Send a match event
Once you have verified the Goods Load, send a twin:locationOperatorMatch event back to TWIN to confirm. It joins the Goods Load's event list and advances its status.
POST /supply-chain/data-space/inbox
Cookie: access_token=<jwt>
Content-Type: application/json{
"@context": ["https://www.w3.org/ns/activitystreams"],
"type": "Add",
"generator": "<your-organisation-id>",
"actor": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "TradeParty",
"registeredId": {
"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
"@value": "<your-organisation-id>"
}
},
"object": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "SupplyChainEvent",
"typeCode": "twin:locationOperatorMatch",
"occurrenceDateTime": "2026-03-19T00:00:08.000Z"
},
"target": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "Consignment",
"globalId": "<goods-load-globalId-from-notification>",
"identifier": "<goods-load-identifier>"
}
}| Field | Required | Description |
|---|---|---|
object.typeCode | Yes | Must be twin:locationOperatorMatch |
object.occurrenceDateTime | No | ISO 8601 timestamp — use the current time. Omit it and TWIN dates the confirmation on arrival |
target.globalId | Yes | The Goods Load globalId from the notification |
target.identifier | Yes | The Goods Load identifier. target is rejected without it |
actor.registeredId.@value | Yes | Your organisation ID |
generator | No | Ignored here — the node replaces it with the session it resolved for you |
Returns 200 OK with an activity-log entry. Acceptance is not the same as success: a failure while processing the event is reported in the body, so check status and tasks[].error rather than relying on the HTTP status.
Only failures raised before the activity is handed to the supply chain app surface as HTTP errors — anything the app itself rejects, schema validation included, is reported on the task instead.
| Status | Cause |
|---|---|
400 | Malformed activity — not an object, or no type |
401 | Missing or invalid session cookie |
500 | The activity could not be submitted to the data space |
If the Goods Load does not correspond to a goods movement at one of your locations, do not send the event. No response is required — the Goods Load continues its lifecycle without location operator confirmation.