Migrate from v1

Publish your existing v1 payloads directly to the standard TWIN Supply Chain API.

This guide explains how to migrate an existing v1 integration to the standard TWIN Supply Chain API.

Starting a new integration? Go directly to Publish Data.

If your integration currently sends data to /data-space-connector/notify, two changes are required:

Send your data to POST /supply-chain/data-space/inbox instead.
Convert your existing v1 payloads to the v2 format expected by the standard API.

The new endpoint does not convert payloads for you: the transformation the adaptor applies internally must now be done on your side.

The endpoint change is below, followed by a complete migration example and the schema changes in detail.

Publish to the new endpoint

Whatever you are publishing, it goes to one endpoint:

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

Consignments, documents, and events are all published to this same endpoint. Authentication works the same way as for /data-space-connector/notify — see Authentication.

For response details and error codes, see Publish Data → Response.

Migration example

The following example shows how a v1 consignment payload is transformed into the v2 format expected by the standard API.

v1 payload

{
	"type": "Create",
	"object": {
		"type": "Consignment",
		"atArrivalTransportMovement": {
			"mode": "RORO",
			"type": "TransportMovement",
			"arrivalEvent": {
				"type": "TransportEvent",
				"occurrenceLogisticsLocation": {
					"name": "Lamu",
					"type": "LogisticsLocation"
				},
				"scheduledOccurrenceDateTime": "2026-02-12T19:17:05.620Z"
			},
			"loadingEvent": null,
			"departureEvent": null,
			"unloadingEvent": null,
			"borderCrossingEvent": null
		},
		"atDepartureTransportMovement": {
			"mode": "RORO",
			"type": "TransportMovement",
			"arrivalEvent": null,
			"loadingEvent": null,
			"departureEvent": {
				"type": "TransportEvent",
				"occurrenceLogisticsLocation": {
					"name": "Dover",
					"type": "LogisticsLocation"
				},
				"scheduledOccurrenceDateTime": "2026-02-12T19:17:21.389Z"
			},
			"unloadingEvent": null,
			"borderCrossingEvent": null
		},
		"consignmentItemQuantity": 1,
		"exporterParty": {
			"name": "ABC Traders Ltd",
			"type": "TradeParty",
			"identificationId": "IMPORT_EORI",
			"identificationType": "EORI"
		},
		"globalId": "5-GB-EXPORT-New-0001",
		"identifier": "TestFreightForwarder-0001",
		"importerParty": {
			"name": "XYZ Importers Association",
			"type": "TradeParty",
			"identificationId": "EXPORT_EORI",
			"identificationType": "EORI"
		},
		"carrierParty": {
			"carrierParty": "Test Carrier",
			"carrierAssignedBookingID": "B0000001",
			"identifier": "Test Vessel",
			"driverAccompaniedIndicator": true
		},
		"items": [
			{
				"type": "ConsignmentItem",
				"information": "Other preserved meat",
				"goodsTypeCode": ["1602"],
				"originCountry": {
					"type": "Country",
					"countryId": "PL"
				},
				"associatedDocument": [
					{
						"href": null,
						"type": "Document",
						"versionId": null,
						"issueDateTime": null,
						"documentTypeCode": "unece:DocumentCodeList#856",
						"identificationId": "TestCHED",
						"identificationType": "Reference"
					}
				]
			}
		],
		"loadingLocation": {
			"name": "Test Exporter Site",
			"type": "LogisticsLocation",
			"postalAddress": {
				"type": "TradeAddress",
				"streetName": "1 Test Street, Test City",
				"tradeAddressCountryId": "PL"
			},
			"physicalGeographicalCoordinate": {
				"type": "GeographicalCoordinate",
				"latitudeMeasure": 52.0,
				"longitudeMeasure": 19.0
			}
		},
		"specifiedTransportMovement": {
			"mode": "RORO",
			"type": "TransportMovement",
			"arrivalEvent": null,
			"loadingEvent": {
				"type": "TransportEvent",
				"occurrenceLogisticsLocation": null,
				"scheduledOccurrenceDateTime": "2026-02-12T19:18:06.625Z"
			},
			"departureEvent": null,
			"unloadingEvent": {
				"type": "TransportEvent",
				"occurrenceLogisticsLocation": null,
				"scheduledOccurrenceDateTime": "2026-02-12T19:18:29.515Z"
			},
			"borderCrossingEvent": null
		},
		"utilizedTransportEquipment": {
			"type": "LogisticsTransportEquipment",
			"identifier": "CHAIR"
		},
		"unloadingLocation": {
			"name": "Test Importer Site",
			"type": "LogisticsLocation",
			"postalAddress": {
				"type": "TradeAddress",
				"streetName": "2 Test Road, Test Town",
				"tradeAddressCountryId": "GB"
			},
			"physicalGeographicalCoordinate": {
				"type": "GeographicalCoordinate",
				"latitudeMeasure": 51.5,
				"longitudeMeasure": -2.1
			}
		}
	},
	"actor": {
		"type": "Organization",
		"identificationId": "GB000000000000",
		"identificationType": "EORI"
	},
	"@context": [
		"https://www.w3.org/ns/activitystreams",
		"https://vocabulary.uncefact.org/unece-context.jsonld",
		"https://iotaledger.github.io/gtsc/JSON-LD-Context/open-gtsc-context.jsonld"
	],
	"generator": "did:iota:123456",
	"updated": "2025-02-19T15:00:50.1839974Z",
	"name": "Pre-Notification"
}

v2 payload

The following payload is the v2 representation of the same data and can be sent directly to POST /supply-chain/data-space/inbox:

{
	"type": "Create",
	"object": {
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
		"type": "Consignment",
		"identifier": "260202-1990",
		"summaryDescription": "Fresh chicken",
		"packageQuantity": {
			"type": "QuantityType",
			"unece:QuantityTypeValue": "25"
		},
		"globalId": "260202-1991",
		"consignmentItemQuantity": {
			"type": "QuantityType",
			"unece:QuantityTypeValue": "1"
		},
		"weightUnitNetWeightMeasure": [
			{
				"type": "WeightUnitMeasureType",
				"unece:WeightUnitMeasureTypeValue": "19578",
				"unece:WeightUnitMeasureTypeCode": "unece:WeightUnitMeasureCode#KGM"
			}
		],
		"utilizedTransportEquipment": [
			{
				"type": "LogisticsTransportEquipment",
				"identifier": "AB24XYZ",
				"affixedSeal": [
					{
						"type": "Seal",
						"identifier": "AB876309"
					}
				],
				"specifiedTransportMeans": [
					{
						"type": "LogisticsTransportMeans",
						"transportMeansTypeCode": "unece:TransportMeansTypeCodeList#3103"
					}
				]
			}
		],
		"carrierParty": {
			"type": "TradeParty",
			"name": "DFDS",
			"registeredId": {
				"@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
				"@value": "DK123456789000"
			}
		},
		"atDepartureTransportMovement": {
			"type": "TransportMovement",
			"departureEvent": [
				{
					"type": "TransportEvent",
					"occurrenceLogisticsLocation": {
						"type": "LogisticsLocation",
						"identifier": {
							"@type": "https://ref.gs1.org/voc/LocationID_Type-UN_LOCODE",
							"@value": "FRCQF"
						}
					},
					"scheduledOccurrenceDateTime": "2026-02-12T19:17:05.620Z"
				}
			],
			"transportModeCode": "unece:TransportModeCodeList#1",
			"usedTransportMeans": {
				"type": "LogisticsTransportMeans",
				"identifier": {
					"@value": "The Black Pearl"
				},
				"transportMeansTypeCode": "unece:TransportMeansTypeCodeList#1512",
				"attachedLogisticsTransportEquipment": [
					{
						"type": "LogisticsTransportEquipment",
						"carrierAssignedBookingId": "DFDS-123456"
					}
				],
				"driverAccompaniedIndicator": true
			}
		},
		"atArrivalTransportMovement": {
			"type": "TransportMovement",
			"arrivalEvent": [
				{
					"type": "TransportEvent",
					"occurrenceLogisticsLocation": {
						"type": "LogisticsLocation",
						"identifier": {
							"@type": "https://ref.gs1.org/voc/LocationID_Type-UN_LOCODE",
							"@value": "GBDVR"
						}
					},
					"scheduledOccurrenceDateTime": "2026-02-12T19:17:21.389Z"
				}
			],
			"transportModeCode": "unece:TransportModeCodeList#3"
		},
		"includedConsignment": [
			{
				"type": "Consignment",
				"identifier": "242110-117",
				"exporterParty": {
					"type": "TradeParty",
					"role": "Exporter",
					"registeredId": {
						"@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
						"@value": "PL82561935000"
					},
					"name": "Traders International",
					"postalAddress": {
						"type": "TradeAddress",
						"tradeAddressCountryId": "unece:CountryId#PL"
					}
				},
				"consignorParty": {
					"type": "TradeParty",
					"role": "Consignor",
					"registeredId": {
						"@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
						"@value": "PL39000000004358Z"
					},
					"name": "Acme distribution",
					"postalAddress": {
						"type": "TradeAddress",
						"streetName": "ul. Olszowa 50, Strzegom, Poland",
						"postcodeCode": "58-150",
						"tradeAddressCountryId": "unece:CountryId#PL",
						"geoCoordinateIdentificationGeographicalCoordinate": [
							{
								"type": "GeographicalCoordinate",
								"latitudeMeasure": {
									"type": "MeasureType",
									"MeasureTypeValue": "50.9667"
								},
								"longitudeMeasure": {
									"type": "MeasureType",
									"MeasureTypeValue": "16.3167"
								}
							}
						]
					}
				},
				"consigneeParty": {
					"type": "TradeParty",
					"role": "Consignee",
					"registeredId": {
						"@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
						"@value": "GB195394660000"
					},
					"name": "We Sell Electronics",
					"postalAddress": {
						"type": "TradeAddress",
						"streetName": "Oakland International, Bardon Hill, Coalville",
						"postcodeCode": "LE67 1TB",
						"tradeAddressCountryId": "unece:CountryId#GB",
						"geoCoordinateIdentificationGeographicalCoordinate": [
							{
								"type": "GeographicalCoordinate",
								"latitudeMeasure": {
									"type": "MeasureType",
									"MeasureTypeValue": "51.47002"
								},
								"longitudeMeasure": {
									"type": "MeasureType",
									"MeasureTypeValue": "-0.454295"
								}
							}
						]
					}
				},
				"importerParty": {
					"type": "TradeParty",
					"role": "Importer",
					"registeredId": {
						"@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
						"@value": "GB452718660000"
					},
					"name": "W E Coyote ltd",
					"postalAddress": {
						"type": "TradeAddress",
						"tradeAddressCountryId": "unece:CountryId#GB"
					}
				},
				"atDepartureTransportMovement": {
					"type": "TransportMovement",
					"departureEvent": [
						{
							"type": "TransportEvent",
							"scheduledOccurrenceDateTime": "2026-02-12T19:18:06.625Z"
						}
					],
					"transportModeCode": "unece:TransportModeCodeList#1"
				},
				"atArrivalTransportMovement": {
					"type": "TransportMovement",
					"arrivalEvent": [
						{
							"type": "TransportEvent",
							"scheduledOccurrenceDateTime": "2026-02-12T19:18:29.515Z"
						}
					],
					"transportModeCode": "unece:TransportModeCodeList#3"
				},
				"includedConsignmentItem": [
					{
						"type": "ConsignmentItem",
						"goodsTypeCode": "unece:GoodsTypeCodeList#ZZZ",
						"information": "Fresh chicken fillets",
						"originCountry": {
							"type": "Country",
							"countryId": "unece:CountryId#PL"
						}
					}
				]
			}
		]
	},
	"actor": {
		"type": "TradeParty",
		"registeredId": {
			"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
			"@value": "did:iota:123456"
		},
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld"
	},
	"@context": ["https://www.w3.org/ns/activitystreams"],
	"generator": "did:iota:123456",
	"updated": "2026-02-12T19:19:01.338Z",
	"name": "Pre-Notification"
}

Key differences

The converted v2 payload differs from the original v1 payload in a few ways:

Empty and null fields are removed.
UN/LOCODE values are resolved automatically by the adaptor.
The updated field is replaced with the current timestamp.

This is the same transformation the adaptor performs internally, so you can use it as a reference to check your own v2 payloads during migration.

Schema changes

This section describes how v1 fields map to their v2 equivalents.

All v2 payloads follow the same high-level structure:

An activity envelope (Create, Update, or Add)
An actor
An object (Consignment, Document, or SupplyChainEvent)
Optionally, a target for Add activities

Actor and target

In v1, actor is an Organization identified by identificationId and identificationType:

	"actor": {
		"type": "Organization",
		"identificationId": "GB000000000000",
		"identificationType": "EORI"
	},

In v2 it becomes a TradeParty with its own @context and a registeredId value object:

"actor": {
  "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
  "type": "TradeParty",
  "registeredId": {
    "@type": "https://ref.gs1.org/voc/OrganizationID_Type-EORI",
    "@value": "GB000000000000"
  }
}

target — only used on Add activities (see Documents and Events) — follows the same pattern. In v1:

	"target": {
		"type": "Consignment",
		"globalId": "5-GN661-859-1403"
	},

In v2, it gains its own @context and always requires an identifier:

"target": {
  "@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
  "type": "Consignment",
  "identifier": "",
  "globalId": "5-GN661-859-1403"
}

The adaptor outputs an empty string when v1 did not provide an identifier, but you should always set a real value.

The value of registeredId["@type"] is derived from the v1 identifier type. The same mapping is used for actor, exporterParty, importerParty, and carrierParty:

v1 `identificationType`	v2 `registeredId["@type"]`
`"EORI"`	`https://ref.gs1.org/voc/OrganizationID_Type-EORI`
`"MobiusReference"`	`https://example.org/vocab/MobiusReference`
any other value	`https://ref.gs1.org/voc/OrganizationID_Type-DID` (fallback)

Consignment

Consignments are published using a Create or Update activity. See Create or update a consignment for the complete schema.

Quantities and equipment

In v1, quantities are plain numbers and the equipment is a single object:

"consignmentItemQuantity": 1,
"utilizedTransportEquipment": {
  "type": "LogisticsTransportEquipment",
  "identifier": "CHAIR"
}

In v2, quantities become typed objects and the equipment an array:

"consignmentItemQuantity": {
  "type": "QuantityType",
  "unece:QuantityTypeValue": "1"
},
"packageQuantity": {
  "type": "QuantityType",
  "unece:QuantityTypeValue": "1"
},
"utilizedTransportEquipment": [
  {
    "type": "LogisticsTransportEquipment",
    "identifier": "CHAIR"
  }
]

Field	v1	v2
`consignmentItemQuantity`	number	`{ type: "QuantityType", "unece:QuantityTypeValue": "<n>" }`
`packageQuantity`	—	new field, set it yourself (typically your item count)
`weightUnitNetWeightMeasure`	—	optional — include only if you have a real net weight
`utilizedTransportEquipment`	single object	array

Transport and locations

In v1, each transport movement carries single-object events, null placeholders, and locations identified only by name:

		"atDepartureTransportMovement": {
			"mode": "RORO",
			"type": "TransportMovement",
			"arrivalEvent": null,
			"loadingEvent": null,
			"departureEvent": {
				"type": "TransportEvent",
				"occurrenceLogisticsLocation": {
					"name": "Dover",
					"type": "LogisticsLocation"
				},
				"scheduledOccurrenceDateTime": "2026-02-12T19:17:21.389Z"
			},
			"unloadingEvent": null,
			"borderCrossingEvent": null
		},

In v2, the events become arrays, mode is replaced by transportModeCode, and each location carries a UN/LOCODE identifier:

"atDepartureTransportMovement": {
  "type": "TransportMovement",
  "transportModeCode": "unece:TransportModeCodeList#3",
  "departureEvent": [
    {
      "type": "TransportEvent",
      "occurrenceLogisticsLocation": {
        "name": "Dover",
        "type": "LogisticsLocation",
        "identifier": {
          "@type": "https://ref.gs1.org/voc/LocationID_Type-UN_LOCODE",
          "@value": "GBDVR"
        }
      },
      "scheduledOccurrenceDateTime": "2026-02-12T19:17:21.389Z"
    }
  ]
}

In the full payload, atDepartureTransportMovement also carries usedTransportMeans, built from the carrier fields — see Carrier.

Field	v1	v2
`departureEvent` / `arrivalEvent`	single object	array
`mode` (on `atDepartureTransportMovement` and `atArrivalTransportMovement`)	string	replaced by `transportModeCode` (table below)
`occurrenceLogisticsLocation.identifier`	resolved for you from the port name	set yourself: `{ "@type": "https://ref.gs1.org/voc/LocationID_Type-UN_LOCODE", "@value": "<locode>" }`
`specifiedTransportMovement`	single object	wrapped in an array, contents kept as-is
`loadingEvent` / `unloadingEvent` / `borderCrossingEvent`	ignored	ignored

mode maps to transportModeCode as follows (values are matched case-insensitively):

v1 `mode`	v2 `transportModeCode`
`"RORO"`	`unece:TransportModeCodeList#3` (Road)
`"SEA"`	`unece:TransportModeCodeList#1` (Maritime)
`"ROAD"`	`unece:TransportModeCodeList#3` (Road)
`"AIR"`	`unece:TransportModeCodeList#4` (Air)
`"RAIL"`	`unece:TransportModeCodeList#2` (Rail)
`"MAIL"`	`unece:TransportModeCodeList#5` (Mail)
`"INLAND_WATER"`	`unece:TransportModeCodeList#8` (Inland water)
other / missing	`unece:TransportModeCodeList#3` (Road, default)

Carrier

In v1, all carrier data lives in the carrierParty object:

		"carrierParty": {
			"carrierParty": "Test Carrier",
			"carrierAssignedBookingID": "B0000001",
			"identifier": "Test Vessel",
			"driverAccompaniedIndicator": true
		},

In v2 it is split: the name and identifier stay in carrierParty, while the booking and driver details move to atDepartureTransportMovement.usedTransportMeans:

"carrierParty": {
  "type": "TradeParty",
  "name": "Test Carrier",
  "registeredId": {
    "@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
    "@value": "Test Vessel"
  }
},
"atDepartureTransportMovement": {
  "usedTransportMeans": {
    "type": "LogisticsTransportMeans",
    "attachedLogisticsTransportEquipment": [
      {
        "type": "LogisticsTransportEquipment",
        "carrierAssignedBookingId": "B0000001"
      }
    ],
    "driverAccompaniedIndicator": true
  }
}

identifier and identificationType map to registeredId using the same id-type mapping as actor. A missing name defaults to "Unknown Carrier".

Parties, items and documents

In v1, locations and items are top-level fields on the consignment:

		"items": [
			{
				"type": "ConsignmentItem",
				"information": "Other preserved meat",
				"goodsTypeCode": ["1602"],
				"originCountry": {
					"type": "Country",
					"countryId": "PL"
				},
				"associatedDocument": [
					{
						"href": null,
						"type": "Document",
						"versionId": null,
						"issueDateTime": null,
						"documentTypeCode": "unece:DocumentCodeList#856",
						"identificationId": "TestCHED",
						"identificationType": "Reference"
					}
				]
			}
		],
		"loadingLocation": {
			"name": "Test Exporter Site",
			"type": "LogisticsLocation",
			"postalAddress": {
				"type": "TradeAddress",
				"streetName": "1 Test Street, Test City",
				"tradeAddressCountryId": "PL"
			},
			"physicalGeographicalCoordinate": {
				"type": "GeographicalCoordinate",
				"latitudeMeasure": 52.0,
				"longitudeMeasure": 19.0
			}
		},

In v2, they move inside includedConsignment[0], which also carries the parties and transport movements (see the full example above):

"consignorParty": {
  "type": "TradeParty",
  "name": "Test Exporter",
  "postalAddress": {
    "type": "TradeAddress",
    "streetName": "1 Test Street, Test City",
    "tradeAddressCountryId": "PL"
  }
},
"includedConsignmentItem": [
  {
    "type": "ConsignmentItem",
    "goodsTypeCode": "1602",
    "information": "Other preserved meat",
    "originCountry": {
      "type": "Country",
      "countryId": "unece:CountryId#PL"
    },
    "associatedDocument": [
      {
        "type": "Document",
        "identifier": "TestCHED",
        "documentTypeCode": "unece:DocumentCodeList#856"
      }
    ]
  }
]

Field	v1	v2
`loadingLocation` / `unloadingLocation`	location object	`includedConsignment[0].consignorParty` / `.consigneeParty` — only `name` and `postalAddress` are preserved
`items[]`	top-level array	`includedConsignment[0].includedConsignmentItem[]`
`items[].goodsTypeCode`	array, e.g. `["1602"]`	single string — the first element, e.g. `"1602"`
`items[].originCountry.countryId`	raw code, e.g. `"PL"`	`"unece:CountryId#PL"`
`items[].associatedDocument[]`	`{ href, versionId, issueDateTime, documentTypeCode, identificationId, identificationType }`	`{ documentTypeCode, identifier }` only — all other fields are dropped

Documents

Documents are published using an Add activity with a target that identifies the consignment.

See Add a document for the complete schema.

In v1, the document activity looks like this:

{
	"type": "Add",
	"object": {
		"documentTypeCode": "unece:DocumentCodeList#730",
		"href": "https://pdfobject.com/pdf/sample.pdf",
		"identificationId": "251702-011-730",
		"identificationType": "Reference",
		"issueDateTime": "2026-02-20T06:22:37.1416918Z",
		"type": "Document",
		"versionId": "2026-02-20T07:25:08.4397546Z"
	},
	"target": {
		"type": "Consignment",
		"globalId": "5-GN661-859-1403"
	},
	"actor": {
		"type": "Organization",
		"identificationId": "GB000000000000",
		"identificationType": "EORI"
	},
	"@context": [
		"https://www.w3.org/ns/activitystreams",
		"https://iotaledger.github.io/gtsc/JSON-LD-Context/open-gtsc-context.jsonld",
		"https://vocabulary.uncefact.org/unece-context.jsonld"
	],
	"generator": "did:iota:testnet:0x6b",
	"updated": "2026-02-20T07:25:08.4774583Z",
	"name": "DocumentIssued"
}

In v2, the same document becomes:

{
	"type": "Add",
	"object": {
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
		"documentTypeCode": "unece:DocumentCodeList#730",
		"uRIId": "https://pdfobject.com/pdf/sample.pdf",
		"identificationId": "251702-011-730",
		"identificationType": "Reference",
		"issueDateTime": "2026-02-20T06:22:37.1416918Z",
		"type": "Document",
		"versionId": "2026-02-20T07:25:08.4397546Z",
		"identifier": "5-GN661-859-1403"
	},
	"actor": {
		"type": "TradeParty",
		"registeredId": {
			"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
			"@value": "did:iota:123456"
		},
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld"
	},
	"target": {
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
		"type": "Consignment",
		"globalId": "5-GN661-859-1403",
		"identifier": "5-GN661-859-1403"
	},
	"@context": ["https://www.w3.org/ns/activitystreams"],
	"generator": "did:iota:123456",
	"updated": "2026-02-20T07:25:08.4774583Z",
	"name": "DocumentIssued"
}

Field	v1	v2
File	`href`	`uRIId` (required - accessible URL) and `attachmentBinaryObject` (base64 content)
Identifier	`identificationId`	`identifier`
Id type	`identificationType`	— (no v2 equivalent)
Document type	`documentTypeCode`	same value, add `unece:DocumentCodeList#` prefix if missing
Version / issue date	`versionId`, `issueDateTime`	unchanged

In v1, you gave TWIN a URL, and TWIN used access credentials configured for your integration to retrieve the file from it. This is no longer done in v2: you are responsible for providing the file, at a URL TWIN can access without credentials (uRIId) or embedded directly in the payload as base64 (attachmentBinaryObject). uRIId is required either way, so a payload that carries the base64 content still has to include it.

Events

Events are also published using an Add activity with the same target structure used for documents.

In v1, the adaptor generates events automatically from the name field of the consignment activity:

	"name": "Pre-Notification"

In v2, there is no automatic trigger — you publish the event yourself as a separate Add activity after the consignment:

{
	"type": "Add",
	"object": {
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
		"type": "SupplyChainEvent",
		"typeCode": "twin:despatched",
		"occurrenceDateTime": "2025-11-04T15:00:50.1839974Z"
	},
	"actor": {
		"type": "TradeParty",
		"registeredId": {
			"@type": "https://ref.gs1.org/voc/OrganizationID_Type-DID",
			"@value": "did:iota:123456"
		},
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld"
	},
	"target": {
		"@context": "https://vocabulary.uncefact.org/unece-context-D23B.jsonld",
		"type": "Consignment",
		"globalId": "5-GN661-859-1403",
		"identifier": "5-GN661-859-1403"
	},
	"@context": ["https://www.w3.org/ns/activitystreams"],
	"generator": "did:iota:123456",
	"updated": "2025-06-19T15:00:50.1839974Z",
	"name": "Event"
}

v1 `name` on the activity	v2 equivalent
`"Despatch"`	`Add` activity containing a `SupplyChainEvent` with `typeCode: "twin:despatched"`
`"Pre-Notification"`	`Add` activity containing a `SupplyChainEvent` with `typeCode: "twin:preNotification"`

See Add an event for the complete list of supported event types.

Publish your converted payload

After converting your payload to v2, publish it to:

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

Consignments, documents, and events are all published to this same endpoint. Authentication works the same way as for /data-space-connector/notify — see Authentication.

For response details and error codes, see Publish Data → Response.

Migrate from v1

On this page