Location Operator

Authenticate, retrieve consignment documents, and send match events back to TWIN.

When a carrier booking event is published for a consignment routed through one of your registered locations, TWIN sends an notification to your endpoint. You can then retrieve the relevant documents and send a match event back to confirm the match.

Authenticate

Exchange your email and password for a session cookie. You'll need the x-api-key provided by your node operator.

Request

POST /authentication/login
Content-Type: application/json
x-api-key: <your-api-key>

Body

{
  "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.

Retrieve documents

The notification contains the consignment globalId. Use it to fetch only the documents relevant to that consignment.

See the API reference for all available read endpoints.

GET /supply-chain/data-space/consignments/:id/documents
Cookie: access_token=<jwt>
x-api-key: <your-api-key>

Returns a list of DocumentAttachment objects. Replace :id with the globalId from the notification.

To download a specific document:

GET /supply-chain/data-space/documents/:documentId
Cookie: access_token=<jwt>
x-api-key: <your-api-key>

To list all documents shared with your organisation (not scoped to a consignment):

GET /supply-chain/data-space/documents
Cookie: access_token=<jwt>
x-api-key: <your-api-key>

Send a match event

When TWIN routes a consignment through one of your locations, send a MATCH event back to confirm.

This endpoint uses Authorization: Bearer instead of a cookie. The Bearer token is the JWT value from the access_token cookie — take the cookie value and pass it directly as Authorization: Bearer <value>.

POST /data-space-connector/notify
Authorization: Bearer <access-token>
x-api-key: <your-api-key>
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": "<consignment-globalId-from-notification>"
  }
}

Field	Required	Description
`object.typeCode`	Yes	Must be exactly `MATCH`
`object.date`	Yes	ISO 8601 timestamp of the match — 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	URN identifying the matched property — use `urn:match:property:utilizedTransportEquipment`
`object.object.type`	Yes	Must be `LogisticsTransportEquipment`
`target.globalId`	Yes	The consignment `globalId` from the notification
`generator`	Yes	Your organisation ID
`actor.registeredId.@value`	Yes	Your organisation ID

Your payload is validated against the official SystemEvent schema.

Returns 200 OK or 201 Created on success.

Status	Cause
`400`	Malformed payload or missing required field
`401`	Missing or invalid Bearer token
`422`	Payload failed schema validation

Location Operator

Authenticate

Retrieve documents

Send a match event

On this page