Location Operator
Authenticate, retrieve Goods Load data and documents, and send match events back to TWIN.
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.
Goods Load and consignment refer to the same entity. TWIN's schema and API use "consignment"; this guide uses "Goods Load", the term freight forwarders use day to day.
Authenticate
Exchange your email and password for a session cookie.
POST /authentication/login
Content-Type: application/json{
"email": "[email protected]",
"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 MATCH system event back to TWIN to confirm.
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",
"https://schema.twindev.org/supply-chain/"
],
"type": "SystemEvent",
"typeCode": "MATCH",
"date": "2026-03-19T00:00:08.000Z",
"source": {
"id": "app:YourSystem",
"type": "SoftwareApplication",
"name": "Your System"
},
"object": {
"id": "urn:match:property:utilizedTransportEquipment",
"type": "LogisticsTransportEquipment"
}
},
"target": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "Consignment",
"globalId": "<goods-load-globalId-from-notification>"
}
}| Field | Required | Description |
|---|---|---|
object.typeCode | Yes | Must be MATCH |
object.date | Yes | ISO 8601 timestamp — use the current time |
object.source.id | Yes | A URI identifying your system, e.g. app:YourSystem |
object.source.name | Yes | Human-readable name of your system |
object.object.id | Yes | Must be urn:match:property:utilizedTransportEquipment |
object.object.type | Yes | Must be LogisticsTransportEquipment |
target.globalId | Yes | The Goods Load globalId from the notification |
generator | Yes | Your organisation ID |
actor.registeredId.@value | Yes | Your organisation ID |
Returns 200 OK or 201 Created on success.
| Status | Cause |
|---|---|
400 | Malformed payload or missing required field |
401 | Missing or invalid session cookie |
422 | Payload failed schema validation |
If the Goods Load does not correspond to a goods movement at one of your locations, do not send a MATCH event. No response is required — the Goods Load continues its lifecycle without location operator confirmation.