Data Provider (Freight Forwarder)
Authenticate, publish consignments, add events, and read your data back.
Data Providers (Freight Forwarders) publish consignment data to TWIN via the Dataspace Connector. Once published, TWIN automatically routes notifications to the relevant parties — border agencies, location operators — based on the consignment's route. You stay in control: no point-to-point integrations needed.
Authenticate
Exchange your email and password for a session cookie. You'll need the x-api-key provided by your node operator.
POST /authentication/login
Content-Type: application/json
x-api-key: <your-api-key>{
"email": "you@example.com",
"password": "your-password"
}The JWT arrives via Set-Cookie. Include this cookie on every subsequent request.
See the Authentication reference for full details.
Publish a consignment
Send a Create activity to the DSC inbox. The object field contains the consignment payload — see the Consignment Data Model for all available fields.
POST /supply-chain/data-space/inbox
Cookie: access_token=<jwt>
x-api-key: <your-api-key>
Content-Type: application/json{
"@context": ["https://www.w3.org/ns/activitystreams"],
"type": "Create",
"actor": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "TradeParty",
"registeredId": {
"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
"@value": "did:web:your-org.example.com"
}
},
"object": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "Consignment",
"identifier": "MYREF-001",
"globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}Returns 201 Created. The response body includes the activity ID and a tasks array with processing status.
See the API reference for full request details and more examples.
Add events (optional)
If you want to notify TWIN of status changes, send an Add activity with a SupplyChainEvent object. Reference the consignment by its globalId in the target field.
POST /supply-chain/data-space/inbox
Cookie: access_token=<jwt>
x-api-key: <your-api-key>
Content-Type: application/jsonThe following example uses twin:despatched to signal that the consignment has been dispatched:
{
"@context": ["https://www.w3.org/ns/activitystreams"],
"type": "Add",
"actor": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "TradeParty",
"registeredId": {
"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
"@value": "did:web:your-org.example.com"
}
},
"object": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "SupplyChainEvent",
"typeCode": "twin:despatched",
"occurrenceDateTime": "2026-06-02T09:00:00.000Z"
},
"target": {
"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
"type": "Consignment",
"globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}Other available type codes: twin:preNotification, twin:carrierBooking, twin:atLocationOfExit, twin:leftLocationOfExit, twin:atLocationOfEntry, twin:leftLocationOfEntry, twin:arrivedAtFinalDestination.
Read your consignments
List all consignments published by your organisation:
GET /supply-chain/data-space/consignments
Cookie: access_token=<jwt>
x-api-key: <your-api-key>Returns a paginated list of ConsignmentView objects. Use cursor and limit to page through results.
To retrieve a specific consignment with its events and documents, use the globalId from your original publish:
GET /supply-chain/data-space/consignments/<globalId>
Cookie: access_token=<jwt>
x-api-key: <your-api-key>