Data Provider (Freight Forwarder)

Authenticate, publish Goods Loads, add events and documents, and read your data back.

Data Providers publish Goods Load data to TWIN via the Dataspace Connector. Once published, TWIN automatically routes notifications to the relevant parties — border agencies, location operators — based on the Goods Load's route.

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.

TWIN sends two ISN signals to registered Border Agencies automatically: a Pre-Notification signal when you Create or Update a Goods Load, and a Despatch signal when you add a twin:despatched event (see Add an event below).

Authenticate

Exchange your email and password for a session cookie.

Request

POST /authentication/login
Content-Type: application/json

Body

{
  "email": "[email protected]",
  "password": "your-password"
}

The JWT arrives via Set-Cookie. Include it on every subsequent request.

See Authentication for full details.

Publish a Goods Load

Send a Create activity to the inbox. The object field contains the Goods Load payload.

POST /supply-chain/data-space/inbox
Content-Type: application/json
Cookie: access_token=<jwt>

{
  "@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"
  }
}

This example shows the minimum required fields — a real Goods Load payload will include many more. See Publish Data for all available options.

Returns 201 Created.

Update a Goods Load

Send an Update activity to modify an existing Goods Load. Only include the fields you want to change — TWIN merges them into the existing record.

POST /supply-chain/data-space/inbox
Content-Type: application/json
Cookie: access_token=<jwt>

{
  "@context": ["https://www.w3.org/ns/activitystreams"],
  "type": "Update",
  "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",
    "summaryDescription": "Updated description"
  }
}

TWIN matches the Goods Load by globalId or identifier. Returns 201 Created.

Add an event

Send an Add activity with a SupplyChainEvent to record a status update. Reference the Goods Load in target using both globalId and identifier.

POST /supply-chain/data-space/inbox
Content-Type: application/json
Cookie: access_token=<jwt>

{
  "@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",
    "identifier": "MYREF-001",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

See Event types for all available typeCode values.

Add a document

Send an Add activity with a Document to attach a file to the Goods Load.

POST /supply-chain/data-space/inbox
Content-Type: application/json
Cookie: access_token=<jwt>

{
  "@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": "Document",
    "documentTypeCode": "unece:DocumentCodeList#271",
    "identifier": "DOC-001",
    "versionId": "v1",
    "issueDateTime": "2026-06-01T14:00:00.000Z",
    "uRIId": "https://docs.your-org.example.com/DOC-001.pdf"
  },
  "target": {
    "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
    "type": "Consignment",
    "identifier": "MYREF-001",
    "globalId": "urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

See Add a document for all required fields.

Read your Goods Loads

List all Goods Loads visible to your organisation:

GET /supply-chain/data-space/consignments
Cookie: access_token=<jwt>

Returns a paginated list. Use cursor and limit to page through results. To retrieve a specific Goods Load with its events and documents:

GET /supply-chain/data-space/consignments/<globalId>
Cookie: access_token=<jwt>

See Read Consignments for all available endpoints and response shapes.