In this day and age more and more information about logistics and traffic is shared over the Internet between various parties. To make this communication easier the Open Trip Model specification was created. It is a lightweight data model used to exchange real-time logistic trip data on the web, and to make it easier for shippers, carriers, software vendors, OEMs, and truck manufacturers to create new multi-brand applications and services.
To learn more about the what, the why and the how see the OTM documentation website.
Found any bugs on this page? Or have any feature requests for OTM? Create a new ticket on the OTM5 change requests Github page
Version 5.7 (released on 2025-05-23)
Version 5.6 (released on 2023-11-17)
owner as a new type of actor role. See 78.routeEntityConstraint and deprecate routeConstraint. See 80.Version 5.5 (released on 2023-02-07)
Consignment vs Goods constraints. See 42.fuel on vehicle an enum instead of a free string. See 51.emissionStandardConstraint as a possible constraint. See 52.transportOrder as a field on Consignment to enable the two-way relationship. See 59.eori as a possible contact detail option. See 60.valueBoundConstraint as a possible constraint. See 61.refuel as a possible action. See 62.accessConstraint as possible constraint. See 69.Version 5.4 (released on 2022-05-09)
TransportEquipmentConstraint. See 46.averageFuelConsumption to vehicle. See 48.contextEvents on entities. See 49.sequenceNr to all action types. See 50.cancelled on action results and receiverAbsent as 'reason' type. See 53.actors to all event types. See 55.description to all constraint types. See 56.Version 5.3 (released on 2021-12-16)
relatedConsignments in consignments. See 32.temperatureConstraint as a possible constraint type. See 37.Version 5.2 (released on 2021-09-09)
transportEquipmentSubType for example to indicate what type of pallets you use. See 19.timeWindowConstraint to replace startDateTimeConstraint and endDateTimeConstraint. See 6.operationalBase as a location type. See 22.Version 5.1 (released on 2021-06-01)
emission to Vehicle. See 13.transportMode to Trip and Move. See 12.grossWeight to Goods. See 11.mobilePhone as contact detail option. See 5.lastModified field to each entity. See 2.Version 5.0 (only documentation changes)
Stop action.TransportEquipment (i.e. a trailer).An Actor models a legal entity. A legal entity is an individual, company, or organization that has legal rights and obligations. The use of Actors is optional, and is not necessary to use OpenTripModel. Actors can be used e.g. to group all locations that belong to an organisation, or to address an OpenTripModel message to a specific person or organisation.
https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments/{UUID}
https://example.com/api/v5/consignments/{UUID}
curl -i -X GET \
'https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments/{UUID}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Returned the entity with the provided UUID
Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.
The last modified date of this entity. If none is given the creation date is used instead.
The context events provides some optional information about the events that can provide additional information on the current state of this entity.
For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.
General description of consignment in Free text. e.g 20 europallets fruit. Meant for human inspection, not for automating processes.
Whether this consignment is a draft, requested, confirmed, in transit, completed or cancelled. The values accepted (replaced by confirmed) and modified (replaced the lastModified field on every entity) are deprecated since OTM5.1, but will be supported for the whole OTM5.X line.
Free text to describe type of consignment. Usually used to indicate the property types of the products being transported (e.g. frozen, fragile, etc.).
The various goods that need to be transported, together they are part of this consignment.
Documents that are relevant for this consignment. Such as an official agreement between consignee and consignor.
The actors associated with this consignment, for instance the shipper and carrier. One should inline the actors only on the top-level entity (such as the transportOrder or trip)
General description of actions related to the consignment f.e. loading, unloading, hand over, drop of.
Constraints this consignment has to abide to, such special equipment (tail lift, truck mounted forklift), special vehicle, special instructions related to consignor and consignee. Note that you can put the constraints on the individual goods. However using constraints on the consignment is simpler and therefore recommended when possible.
Consignments that have replaced the current consignment. Because of various reasons a consignment can be cancelled and replaced by one or more other consignments. An example is that the consignment is too large to be transported as a single 'transportable unit'. You can use the relation field in the association to indicate the type of relationship.
{ "id": "string", "name": "string", "creationDate": "string", "lastModified": "string", "contextEvents": [ { … } ], "externalAttributes": { "property1": {}, "property2": {} }, "description": "string", "status": "draft", "type": "string", "goods": [ { … } ], "transportOrder": { "associationType": "inline", "entity": { … }, "description": "string" }, "documents": [ { … } ], "remark": "string", "actors": [ { … } ], "actions": [ { … } ], "constraint": { "associationType": "inline", "entity": { … }, "description": "string" }, "relatedConsignments": [ { … } ] }
https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments/{UUID}
https://example.com/api/v5/consignments/{UUID}
curl -i -X DELETE \
'https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments/{UUID}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.
The last modified date of this entity. If none is given the creation date is used instead.
The context events provides some optional information about the events that can provide additional information on the current state of this entity.
For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.
General description of consignment in Free text. e.g 20 europallets fruit. Meant for human inspection, not for automating processes.
Whether this consignment is a draft, requested, confirmed, in transit, completed or cancelled. The values accepted (replaced by confirmed) and modified (replaced the lastModified field on every entity) are deprecated since OTM5.1, but will be supported for the whole OTM5.X line.
Free text to describe type of consignment. Usually used to indicate the property types of the products being transported (e.g. frozen, fragile, etc.).
The various goods that need to be transported, together they are part of this consignment.
Documents that are relevant for this consignment. Such as an official agreement between consignee and consignor.
The actors associated with this consignment, for instance the shipper and carrier. One should inline the actors only on the top-level entity (such as the transportOrder or trip)
General description of actions related to the consignment f.e. loading, unloading, hand over, drop of.
Constraints this consignment has to abide to, such special equipment (tail lift, truck mounted forklift), special vehicle, special instructions related to consignor and consignee. Note that you can put the constraints on the individual goods. However using constraints on the consignment is simpler and therefore recommended when possible.
Consignments that have replaced the current consignment. Because of various reasons a consignment can be cancelled and replaced by one or more other consignments. An example is that the consignment is too large to be transported as a single 'transportable unit'. You can use the relation field in the association to indicate the type of relationship.
https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments
https://example.com/api/v5/consignments
curl -i -X PUT \
https://otm-api-spec.redocly.app/_mock/api/5.7/otm/api/v5/consignments \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"id": "string",
"name": "string",
"creationDate": "string",
"lastModified": "string",
"contextEvents": [
{
"id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
"name": "couple vehicle to trip",
"lifecycle": "planned",
"entity1": {
"uuid": "50824123-0924-4563-ac1e-ca0e37487823",
"entityType": "trip",
"associationType": "reference"
},
"entity2": {
"entity": {
"id": "b9bb914d-845e-46f2-91ff-31fa4bac2fbe",
"name": "Bob'\''s Boxtruck",
"vehicleType": "boxtruck",
"fuel": "electricity",
"loadCapacities": [
{
"value": 1000,
"unit": "kg"
}
],
"length": {
"value": 8,
"unit": "m"
},
"height": {
"value": 2.8,
"unit": "m"
},
"width": {
"value": 2,
"unit": "m"
},
"licensePlate": "AB-12-CD",
"emptyWeight": {
"value": 2000,
"unit": "kg"
},
"entityType": "vehicle"
},
"associationType": "inline"
},
"eventType": "associationCreatedEvent"
}
],
"externalAttributes": {
"property1": {},
"property2": {}
},
"description": "string",
"status": "draft",
"type": "string",
"goods": [
{
"associationType": "inline",
"entity": {
"id": "903807df-ee62-47aa-bf8e-7efd747618ce",
"description": "Box of bananas",
"remark": "Please deliver in time, we want fresh bananas",
"barCode": "CSE370",
"productType": "Fruit",
"packagingMaterial": "Box",
"constraint": {
"entity": {
"value": {
"and": [
{
"startTime": "2021-06-23T10:00:00Z",
"endTime": "2021-06-23T13:00:00Z",
"description": "alert-threshold",
"type": "timeWindowConstraint"
},
{
"constraintType": "maximum",
"maximum": {
"value": 5,
"unit": "C"
},
"type": "temperatureConstraint"
},
{
"or": [
{
"fuelTypes": [
"battery"
],
"type": "fuelTypeConstraint"
},
{
"fuelTypes": [
"biodiesel"
],
"type": "fuelTypeConstraint"
},
{
"minimum": "euro5",
"type": "emissionStandardConstraint"
}
],
"type": "orConstraint"
}
],
"type": "andConstraint"
}
},
"associationType": "inline"
},
"type": "items"
},
"description": "string"
}
],
"transportOrder": {
"associationType": "inline",
"entity": {
"id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
"externalAttributes": {
"id": "OrderId"
},
"description": "Transport order containing all consignments to be shipped.",
"consignments": [
{
"entity": {
"id": "e75a541b-e9d9-49e7-8bba-95492d682a6c",
"description": "Package for miss X."
},
"associationType": "inline"
},
{
"entity": {
"id": "4a08bd61-720e-4a8c-81cf-028f1271c4da",
"description": "Package for mr Y."
},
"associationType": "inline"
}
]
},
"description": "string"
},
"documents": [
{
"associationType": "inline",
"entity": {
"id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
"name": "Photo of the PoD",
"content": {
"uri": "https://link-to-the-actual-document.org/1234",
"contentType": "link"
},
"externalAttributes": {
"externalID": "photo1234"
},
"documentType": "photo",
"filename": "my_photo.JPG",
"mimeType": "image/jpeg",
"description": "Proof that the goods are delivered by providing the photo that captures the moment",
"creator": {
"uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
"entityType": "actor",
"associationType": "reference"
},
"owner": {
"uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
"entityType": "actor",
"associationType": "reference"
}
},
"description": "string"
}
],
"remark": "string",
"actors": [
{
"associationType": "inline",
"entity": {
"id": "45db6ed0-28a7-4e4a-baba-3d5f8d171103",
"name": "Logistics manager",
"contactDetails": [
{
"value": "Simon Isaac",
"remark": "Wants to be called '\''Sim'\''.",
"type": "firstName"
},
{
"value": "Macan",
"type": "lastName"
},
{
"value": "+312012345678",
"remark": "private cellphone of the CEO",
"language": "nld",
"type": "phone"
},
{
"value": "simon@macan",
"type": "email"
},
{
"value": "NL74BANK5890469479",
"type": "iban"
},
{
"value": "NL000099998B57",
"type": "vatCode"
}
]
},
"description": "string",
"roles": [
"shipper"
]
}
],
"actions": [
{
"associationType": "inline",
"entity": {
"id": "e81a7aa3-23a6-4089-b916-52b854c7b6f1",
"lifecycle": "planned",
"remark": "loading a consignment",
"consignment": {
"uuid": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
"entityType": "consignment",
"associationType": "reference"
},
"startTime": "2021-06-23T14:00:00Z",
"endTime": "2021-06-23T14:15:00Z",
"constraint": {
"entity": {
"id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
"name": "Example combined constraint",
"value": {
"and": [
{
"startTime": "2021-06-23T10:00:00Z",
"endTime": "2021-06-23T13:00:00Z",
"description": "alert-threshold",
"type": "timeWindowConstraint"
},
{
"constraintType": "maximum",
"maximum": {
"value": 5,
"unit": "C"
},
"type": "temperatureConstraint"
},
{
"or": [
{
"fuelTypes": [
"battery"
],
"type": "fuelTypeConstraint"
},
{
"fuelTypes": [
"biodiesel"
],
"type": "fuelTypeConstraint"
},
{
"minimum": "euro5",
"type": "emissionStandardConstraint"
}
],
"type": "orConstraint"
}
],
"type": "andConstraint"
}
},
"associationType": "inline"
},
"actionType": "load"
},
"description": "string"
}
],
"constraint": {
"associationType": "inline",
"entity": {
"id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
"name": "Example combined constraint",
"value": {
"and": [
{
"startTime": "2021-06-23T10:00:00Z",
"endTime": "2021-06-23T13:00:00Z",
"description": "alert-threshold",
"type": "timeWindowConstraint"
},
{
"constraintType": "maximum",
"maximum": {
"value": 5,
"unit": "C"
},
"type": "temperatureConstraint"
},
{
"or": [
{
"fuelTypes": [
"battery"
],
"type": "fuelTypeConstraint"
},
{
"fuelTypes": [
"biodiesel"
],
"type": "fuelTypeConstraint"
},
{
"minimum": "euro5",
"type": "emissionStandardConstraint"
}
],
"type": "orConstraint"
}
],
"type": "andConstraint"
}
},
"description": "string"
},
"relatedConsignments": [
{
"associationType": "inline",
"entity": {
"id": "string",
"name": "string",
"creationDate": "string",
"lastModified": "string",
"contextEvents": [
{
"id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
"name": "couple vehicle to trip",
"lifecycle": "planned",
"entity1": {
"uuid": "50824123-0924-4563-ac1e-ca0e37487823",
"entityType": "trip",
"associationType": "reference"
},
"entity2": {
"entity": {
"id": "b9bb914d-845e-46f2-91ff-31fa4bac2fbe",
"name": "Bob'\''s Boxtruck",
"vehicleType": "boxtruck",
"fuel": "electricity",
"loadCapacities": [
{
"value": 1000,
"unit": "kg"
}
],
"length": {
"value": 8,
"unit": "m"
},
"height": {
"value": 2.8,
"unit": "m"
},
"width": {
"value": 2,
"unit": "m"
},
"licensePlate": "AB-12-CD",
"emptyWeight": {
"value": 2000,
"unit": "kg"
},
"entityType": "vehicle"
},
"associationType": "inline"
},
"eventType": "associationCreatedEvent"
}
],
"externalAttributes": {
"property1": {},
"property2": {}
},
"description": "string",
"status": "draft",
"type": "string",
"goods": [
{
"associationType": "inline",
"entity": {
"id": "903807df-ee62-47aa-bf8e-7efd747618ce",
"description": "Box of bananas",
"remark": "Please deliver in time, we want fresh bananas",
"barCode": "CSE370",
"productType": "Fruit",
"packagingMaterial": "Box",
"constraint": {
"entity": {
"value": {
"and": [
{
"startTime": "2021-06-23T10:00:00Z",
"endTime": "2021-06-23T13:00:00Z",
"description": "alert-threshold",
"type": "timeWindowConstraint"
},
{
"constraintType": "maximum",
"maximum": {
"value": 5,
"unit": "C"
},
"type": "temperatureConstraint"
},
{
"or": [
{
"fuelTypes": [
"battery"
],
"type": "fuelTypeConstraint"
},
{
"fuelTypes": [
"biodiesel"
],
"type": "fuelTypeConstraint"
},
{
"minimum": "euro5",
"type": "emissionStandardConstraint"
}
],
"type": "orConstraint"
}
],
"type": "andConstraint"
}
},
"associationType": "inline"
},
"type": "items"
},
"description": "string"
}
],
"transportOrder": {
"associationType": "inline",
"entity": {
"id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
"externalAttributes": {
"id": "OrderId"
},
"description": "Transport order containing all consignments to be shipped.",
"consignments": [
{
"entity": {
"id": "e75a541b-e9d9-49e7-8bba-95492d682a6c",
"description": "Package for miss X."
},
"associationType": "inline"
},
{
"entity": {
"id": "4a08bd61-720e-4a8c-81cf-028f1271c4da",
"description": "Package for mr Y."
},
"associationType": "inline"
}
]
},
"description": "string"
},
"documents": [
{
"associationType": "inline",
"entity": {
"id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
"name": "Photo of the PoD",
"content": {
"uri": "https://link-to-the-actual-document.org/1234",
"contentType": "link"
},
"externalAttributes": {
"externalID": "photo1234"
},
"documentType": "photo",
"filename": "my_photo.JPG",
"mimeType": "image/jpeg",
"description": "Proof that the goods are delivered by providing the photo that captures the moment",
"creator": {
"uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
"entityType": "actor",
"associationType": "reference"
},
"owner": {
"uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
"entityType": "actor",
"associationType": "reference"
}
},
"description": "string"
}
],
"remark": "string",
"actors": [
{
"associationType": "inline",
"entity": {
"id": "45db6ed0-28a7-4e4a-baba-3d5f8d171103",
"name": "Logistics manager",
"contactDetails": [
{
"value": "Simon Isaac",
"remark": "Wants to be called '\''Sim'\''.",
"type": "firstName"
},
{
"value": "Macan",
"type": "lastName"
},
{
"value": "+312012345678",
"remark": "private cellphone of the CEO",
"language": "nld",
"type": "phone"
},
{
"value": "simon@macan",
"type": "email"
},
{
"value": "NL74BANK5890469479",
"type": "iban"
},
{
"value": "NL000099998B57",
"type": "vatCode"
}
]
},
"description": "string",
"roles": [
"shipper"
]
}
],
"constraint": {
"associationType": "inline",
"entity": {
"id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
"name": "Example combined constraint",
"value": {
"and": [
{
"startTime": "2021-06-23T10:00:00Z",
"endTime": "2021-06-23T13:00:00Z",
"description": "alert-threshold",
"type": "timeWindowConstraint"
},
{
"constraintType": "maximum",
"maximum": {
"value": 5,
"unit": "C"
},
"type": "temperatureConstraint"
},
{
"or": [
{
"fuelTypes": [
"battery"
],
"type": "fuelTypeConstraint"
},
{
"fuelTypes": [
"biodiesel"
],
"type": "fuelTypeConstraint"
},
{
"minimum": "euro5",
"type": "emissionStandardConstraint"
}
],
"type": "orConstraint"
}
],
"type": "andConstraint"
}
},
"description": "string"
},
"relatedConsignments": [
{}
]
},
"description": "string",
"relation": "split"
}
]
}'The same entity
Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.
The last modified date of this entity. If none is given the creation date is used instead.
The context events provides some optional information about the events that can provide additional information on the current state of this entity.
For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.
General description of consignment in Free text. e.g 20 europallets fruit. Meant for human inspection, not for automating processes.
Whether this consignment is a draft, requested, confirmed, in transit, completed or cancelled. The values accepted (replaced by confirmed) and modified (replaced the lastModified field on every entity) are deprecated since OTM5.1, but will be supported for the whole OTM5.X line.
Free text to describe type of consignment. Usually used to indicate the property types of the products being transported (e.g. frozen, fragile, etc.).
The various goods that need to be transported, together they are part of this consignment.
Documents that are relevant for this consignment. Such as an official agreement between consignee and consignor.
The actors associated with this consignment, for instance the shipper and carrier. One should inline the actors only on the top-level entity (such as the transportOrder or trip)
General description of actions related to the consignment f.e. loading, unloading, hand over, drop of.
Constraints this consignment has to abide to, such special equipment (tail lift, truck mounted forklift), special vehicle, special instructions related to consignor and consignee. Note that you can put the constraints on the individual goods. However using constraints on the consignment is simpler and therefore recommended when possible.
Consignments that have replaced the current consignment. Because of various reasons a consignment can be cancelled and replaced by one or more other consignments. An example is that the consignment is too large to be transported as a single 'transportable unit'. You can use the relation field in the association to indicate the type of relationship.
{ "id": "string", "name": "string", "creationDate": "string", "lastModified": "string", "contextEvents": [ { … } ], "externalAttributes": { "property1": {}, "property2": {} }, "description": "string", "status": "draft", "type": "string", "goods": [ { … } ], "transportOrder": { "associationType": "inline", "entity": { … }, "description": "string" }, "documents": [ { … } ], "remark": "string", "actors": [ { … } ], "actions": [ { … } ], "constraint": { "associationType": "inline", "entity": { … }, "description": "string" }, "relatedConsignments": [ { … } ] }
Events - like actions - model dynamic entities that couple various static entities at a certain moment in time. Events are used for either real-time updates, or updates on earlier provided data. Notice that in both event types these are updates on earlier provided data, whereas actions are usually used together with the entities they dynamically couple.
There are various kinds of events that fall into the two earlier mentioned kinds.
Real-time updates:
Both real-time and projected/realized events
Updates on earlier provided data:
Actions are dynamic entities that are able to couple together various static entities at a certain moment in time. For instance a Load action couples together a Consignment and a Vehicle at the moment the Loading happens.
There are various types of Actions:
Goods are the items to be transported as part of a consignment. Goods can be divided into two sub-types of goods, depending on the use case and the level of detail. Goods either consists of items, describing the actual goods to be transported. Or a transport equipment, which is equipment used to carry the actual goods to be transported. Transport equipment is (usually) a means to an end, not something that needs to be transported on itself, such as pallets.
Note that goods can either be or contain dangerous goods. OTM uses the official specification of ADR to describe in what manner and how dangerous those goods are. The used descriptions in the OTM documentation are extracted from document ADR2021_Vol1e_0.pdf. The official documentation is always leading and should be consulted.
In many logistic operations documents are an important part of the data flow. Documents can serve multiple purposes, such as proving some package was delivered with help of a photo, or some scanned document that establishes that the transferred goods are accepted on handover. Documents in OTM come in two flavors, either you provide the content of the document directly as a base64 encoded string, or you provide a link to the document where it can be accessed online.
Constraints can do different things, depending on the context they're used in:
Location, access to the location is only allowed if the given constraint applies.Trip, constraints can be used to define constraints that have to be met during the trip, e.g. if the temperature in a refrigerated trailer has to stay below a given maximum during the trip.Shipment, constraints can be used to e.g. define minimum or maximum temperatures for shipments, or date time constraints for delivery.Since OTM5.2 the timeWindowConstraint is supported which allows you to give (optionally) both the start and end time of the window between which something needs to occur. This replaces the old style where you had to use an and constraint in combination with the startDateTimeConstraint and endDateTimeConstraint. Since the new solution is shorter and simpler the startDateTimeConstraint and endDateTimeConstraint are deprecated.
Note that constraints can be nested and combined using the andConstraint, orConstraint and notConstraint.