OTM (v5)

Download OpenAPI specification:Download

Open Trip Model

Why OTM?

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 developer portal.

Changelog

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.4 candidate (expected release 2022-03)

Note: a new version candidate makes no promises on what will actually be in that release. It is very likely though that everything comes in unless oversights are found. The changes will be added to the API definition below once made official.

(no proposed changes yet)

Version 5.3 (released on 2021-12-16)

  • 2021-09-23: Support 204 (No Content) for delete requests. See 23.
  • 2021-09-23: Add classification lines to goods. See 26.
  • 2021-09-23: Add a result to actions. See 30.
  • 2021-09-23: Extend ADR with points and transport category. See 31.
  • 2021-12-16: Support relatedConsignments in consignments. See 32.
  • 2021-12-16: Support UNCode and GLN in locations. See 36.
  • 2021-12-16: Support temperatureConstraint as a possible constraint type. See 37.
  • 2021-12-16: Add some references to existing code lists. See 27.
    • Using ISO country codes in the country field in addresses.
    • Using ISO currency codes in 'value-with-unit' fields.
    • Using the metric system as recommend and default system for dealing with mass, velocity, weight and sizes.
    • Using the package material codes from the GS1 standard.

Version 5.2 (released on 2021-09-09)

  • 2021-08-17: Add transportEquipmentSubType for example to indicate what type of pallets you use. See 19.
  • 2021-08-17: Add timeWindowConstraint to replace startDateTimeConstraint and endDateTimeConstraint. See 6.
  • 2021-07-27: Add operationalBase as a location type. See 22.
  • 2021-07-27: Add more actor role types. See 20.
  • 2021-07-27: Add new break and wait actions. See 17.
  • 2021-07-27: Allow for server side UUID generation. See 16.

Version 5.1 (released on 2021-06-01)

  • 2021-05-31: Add an optional emission to Vehicle. See 13.
  • 2021-05-31: Add an optional transportMode to Trip and Move. See 12.
  • 2021-05-31: Add optional grossWeight to Goods. See 11.
  • 2021-05-31: AddmobilePhone as contact detail option. See 5.
  • 2021-05-31: Add an optional lastModified field to each entity. See 2.
  • 2021-05-25: Add an optional language to contact details. See 9.
  • 2021-05-25: Add a new entity Document to deal with information about files that can be shared. See 7.
  • 2021-05-25: Add new statuses to Trip and Consignment. See 4.
  • 2021-02-02: Add an optional sensors association to vehicle. See 2.

Version 5.0 (only documentation changes)

  • 2021-01-15: Add documentation about validation endpoints.
  • 2021-01-15: Add reference to the otm5-change-requests github.
  • 2020-12-03: Fix the broken checkbox for actions when choosing the Stop action.
  • 2020-12-03: Document the license plate on a TransportEquipment (i.e. a trailer).

Authentication

Bearer token

The scope of OTM currently does not include authentication requirements. Though the recommended approach is to use Bearer authentication (also known as token authentication).

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Vehicle

A Vehicle is a means to transport consignments from one location to potentially multiple other locations. There are various types of vehicles, each with their own unique properties like size, dimensions, fuel type and means of tranport (by air, on land, over sea).

Adds a new Vehicle

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

vehicleType
string

The type of vehicle

fuel
string

The type of fuel the vehicle runs on. For vehicle without an engine of their own, such as a trailer, you may choose not-applicable. For trailers with cooling capabilities, choose the fuel type of the cooling engine.

emissionStandard
string

European emission standards are vehicle emission standards for exhaust emissions of new vehicles sold in the European Union and EEA member states. The standards are defined in a series of European Union directives staging the progressive introduction of increasingly stringent standards. See also European emission standards - Wikipedia.

Enum: "euro0" "euro1" "euro2" "euro3" "euro4" "euro5" "euro6"
maxLinks
integer <int32>

Maximum number of links to other Vehicle s. Typical values are 0, 1 or 2.

Array of objects

The load capacities of the Vehicle. This can be an array of values, for several reasons:

  • The Vehicle might be split up in multiple compartments.
  • You might want to express the load capacities in different quantities. E.g. in square meters or litres as well as in number of pallets.
object

The length of the Vehicle.

object

The height of the Vehicle.

object

The width of the Vehicle.

licensePlate
string

The license plate of the vehicle.

object

The weight of the Vehicle when empty.

Array of any

There are multiple roles in which actors can be associated with a vehicle, such as the owner or the driver of the vehicle.

Array of any

Vehicles might have some sensors that are permanently attached, these can be described using the sensors field. If one works with detachable sensors the recommend approach is to use associationCreated and associationRemoved events instead.

Responses

Request samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Get a specific Vehicle by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Deletes a Vehicle

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Route

A route models the path going from one location to at least one other location.

Adds a new Route

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

required
any

Geographic representation of this route.

Array of any

Actors associated with this route, for instance the Company that requires this route as a Last-Mile guidance.

Array of any (associations-actions)

All the actions that need to be executed on this route.

any

Constraints of using this route, for instance it might only be used by vehicles with below a certain weight.

Responses

Request samples

Content type
application/json
{
  • "id": "5507e5bf-d7f4-4448-b582-5cf6402599c1",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Response samples

Content type
application/json
{
  • "id": "5507e5bf-d7f4-4448-b582-5cf6402599c1",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Get a specific Route by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
{
  • "id": "5507e5bf-d7f4-4448-b582-5cf6402599c1",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Deletes a Route

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Event

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:

  • The LocationUpdateEvent that provides location data received from some GPS.

  • The SensorUpdateEvent that provides sensor value updates (such as temperature or speed measurements) received from a sensor.

  • The StartMovingEvent, StopMovingEvent, StartEngineEvent, StopEngineEvent that indicate events provided by Fleet Management Systems.

  • Updates on earlier provided data*:

  • The UpdateEvent that is used to update an earlier provided entity with new information. Note that only the changed data has to be provided.

  • The AssociationCreatedEvent and AssociationRemovedEvent that allow for static entities to be coupled after the fact. Such as coupling a Vehicle to a Trip.

Get a specific Event by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
Example
associationCreatedEvent
associationCreatedEvent
associationRemovedEvent
updateEvent
locationUpdateEvent
startMovingEvent
stopMovingEvent
startWaitingEvent
startEngineEvent
stopEngineEvent
sensorUpdateEvent
{
  • "id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
  • "name": "couple vehicle to trip",
  • "lifecycle": "planned",
  • "eventType": "associationCreatedEvent",
  • "entity1": {
    },
  • "entity2": {
    }
}

Deletes a Event

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Event

Authorizations:
Bearer token
Request Body schema: application/json
eventType
required
string
associationCreatedEvent
associationCreatedEvent
associationRemovedEvent
updateEvent
locationUpdateEvent
startMovingEvent
stopMovingEvent
startWaitingEvent
startEngineEvent
stopEngineEvent
sensorUpdateEvent
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

lifecycle
string

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

Enum: "requested" "planned" "projected" "actual" "realized"
required
any (entity1)
required
any (entity2)

Responses

Request samples

Content type
application/json
Example
associationCreatedEvent
associationCreatedEvent
associationRemovedEvent
updateEvent
locationUpdateEvent
startMovingEvent
stopMovingEvent
startWaitingEvent
startEngineEvent
stopEngineEvent
sensorUpdateEvent
{
  • "id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
  • "name": "couple vehicle to trip",
  • "lifecycle": "planned",
  • "eventType": "associationCreatedEvent",
  • "entity1": {
    },
  • "entity2": {
    }
}

Response samples

Content type
application/json
Example
associationCreatedEvent
associationCreatedEvent
associationRemovedEvent
updateEvent
locationUpdateEvent
startMovingEvent
stopMovingEvent
startWaitingEvent
startEngineEvent
stopEngineEvent
sensorUpdateEvent
{
  • "id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
  • "name": "couple vehicle to trip",
  • "lifecycle": "planned",
  • "eventType": "associationCreatedEvent",
  • "entity1": {
    },
  • "entity2": {
    }
}

Sensor

A sensor is a device that is able to measure a quantity in a certain unit, such as measuring the speed in km/h.

Adds a new Sensor

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

placement
string

Sometimes more than one sensor can be associated with a single entity. This is the case e.g. in cooled trailers that are divided into compartments with different temperatures, where each compartment has its own sensor. The placement member can be used to identify where a sensor is placed. Parties using OpenTripModel to exchange sensor data may wish to agree on a standardized naming, but this is too specific to describe in the standard.

sensorType
string

The type of sensor.

Array of any

The actors associated with this sensor, for instance the owners, the producers or the users of this sensor.

any

In the context of a Sensor, only sensorValueConstraints really make sense. You can use such a constraint to model a sensor of which the measured value must be within certain bounds at all times.

ℹ Note that constraints can be nested and combined using the andConstraint, orConstraint and notConstraint.

Responses

Request samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Get a specific Sensor by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Deletes a Sensor

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Location

Object describing a geographic location. A location can either be a point or an area.

Get a specific Location by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Location

Responses

Response samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "geoReference": {
    },
  • "type": "warehouse",
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Deletes a Location

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Location

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Location

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

required
any

Describes a geographic reference, this is the primary way to link a Location entity to a physical, geographic location.

unCode
string

the United Nations Code for Trade and Transport Locations, is a geographic coding scheme developed and maintained by United Nations Economic Commission for Europe (UNECE) to uniquely identify locations. See this Wikipedia page.

gln
string

The Global Location Number (GLN) is part of the GS1 systems of standards to uniquely identify a location. See also this Wikipedia page

type
string

The type of location.

Enum: "warehouse" "store" "environmentalZone" "restrictedArea" "customer" "operationalBase"
object (Address)
Array of any

Contact details for this Location.

remark
string

Remark about the location. Please don't misuse this field for external references, use the externalAttributes field instead.

Array of any

Locations can be associated with actors in multiple ways, though the most common one is the owner of the location, either a person or a legal entity.

Array of any (associations-actions)

Multiple actions can be associated with a location, such as a Last-Mile guidance that should be followed to reach that location.

any

In the context of a Location, access to the location is only allowed if the given constraint applies.

ℹ Note that constraints can be nested and combined using the andConstraint, orConstraint and notConstraint.

Responses

Request samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "geoReference": {
    },
  • "type": "warehouse",
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Response samples

Content type
application/json
{
  • "id": "00000014-69a6-9702-0000-0021dca4629b",
  • "name": "Main warehouse",
  • "geoReference": {
    },
  • "type": "warehouse",
  • "administrativeReference": {
    },
  • "remark": "The cafe around the corner has the best coffee in town."
}

Actor

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.

Adds a new Actor

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

Array of any

Contact details for this Actor.

Array of any

Locations for this Actor.

Responses

Request samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Get a specific Actor by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Deletes a Actor

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Goods

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.

Get a specific Goods by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Goods

Responses

Response samples

Content type
application/json
Example
items
items
transportEquipment
{
  • "id": "1132dc78-212a-4400-9823-de154dad35db",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

Deletes a Goods

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Goods

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Goods

Authorizations:
Bearer token
Request Body schema: application/json
type
required
string
items
transportEquipment
items
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

description
string

A free text description of these goods.

remark
string

Remark belonging to the goods that need to be transported. For example a delivery note.

barCode
string

A barcode present on the (packaging of the) goods that uniquely identifies these goods.

quantity
integer <int32>

A quantity determines how many of a certain good you have. Note that all other measurements are measured for a single product, not for the total of products.

object

The net weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

object

The gross weight of a 'single' good, the total weight can be calculated by using the quantity and multiplying it with this weight.

object

The width of a 'single' good, the total width can be calculated by using the quantity and multiplying it with this width.

object

The height of a 'single' good, the total height can be calculated by using the quantity and multiplying it with this height.

object

The length of a 'single' good, the total length can be calculated by using the quantity and multiplying it with this length.

object

Information about the potentially dangerous properties of these goods.

productType
string

The product type of goods, for instance bananas.

packagingMaterial
string

Description of the package type. Use as described by the GS1 standard

Array of objects
Array of any

All parties associated with these goods, for example the consignor and consignee.

Array of any (associations-actions)

Actions associated with goods, for example loading and unloading them at various locations.

any

The constraints put on these goods, for example the required temperature range or size of the vehicle.

Responses

Request samples

Content type
application/json
Example
items
items
transportEquipment
{
  • "id": "1132dc78-212a-4400-9823-de154dad35db",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

Response samples

Content type
application/json
Example
items
items
transportEquipment
{
  • "id": "1132dc78-212a-4400-9823-de154dad35db",
  • "description": "Box of bananas",
  • "remark": "Please deliver in time, we want fresh bananas",
  • "barCode": "CSE370",
  • "productType": "Fruit",
  • "packagingMaterial": "Box",
  • "constraint": {
    },
  • "type": "items"
}

TransportOrder

The TransportOrder is the top-level entity to model a group of related consignments that might be transported separately, but need to be administered together.

Adds a new TransportOrder

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

description
string

Actions related to this transport order, for example all loading and unloading actions of the consignments.

Array of any

All consignments belonging to this transport order.

Array of any

The actors associated with this transport order, for instance the consignor, consignee.

any

Constraints this transport order has to abide to, such as the expected delivery time windows.

Responses

Request samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Get a specific TransportOrder by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this TransportOrder

Responses

Response samples

Content type
application/json
{
  • "id": "baa507c2-1d81-4092-a5c2-e80820ee4fd1",
  • "externalAttributes": {
    },
  • "description": "Transport order containing all consignments to be shipped.",
  • "consignments": [
    ]
}

Deletes a TransportOrder

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this TransportOrder

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Consignment

A consignment is a description of an identifiable collection of goods items to be transported between the consignor and the consignee. This information may be defined within a transport contract.

Get a specific Consignment by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Consignment

Responses

Response samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Deletes a Consignment

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Consignment

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Consignment

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

description
string

General description of consignment in Free text. e.g 20 europallets fruit.

status
string

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.

Enum: "draft" "requested" "confirmed" "inTransit" "completed" "cancelled" "accepted" "modified"
type
string

Free text to describe type of consignment e.g. FTL, Full Truck Load, LTL Less than Truck Load, bulk, reverse logistics orders, pick up order, delivery order.

Array of any

The various goods that need to be transported, together they are part of this consignment.

Array of any

Documents that are relevant for this consignment. Such as an official agreement between consignee and consignor.

remark
string

Remark concerning the complete consignment, to be printed on the transport document.

Array of any

The actors associated with this consignment, for instance the shipper and carrier.

Array of any (associations-actions)

General description of actions related to the consignment f.e. loading, unloading, hand over, drop of.

any

Constraints this consignment has to abide to, such special equipment (tail lift, truck mounted forklift), special vehicle, special instructions related to consignor and consignee.

Array of any

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.

Responses

Request samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Response samples

Content type
application/json
{
  • "id": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  • "externalAttributes": {
    },
  • "description": "Shipment for mr. X",
  • "status": "requested",
  • "type": "HumanFood",
  • "goods": [
    ],
  • "remark": "Please step 1.5m away after ringing the door bell",
  • "actors": [
    ],
  • "actions": [
    ],
  • "constraint": {
    }
}

Trip

A Trip is an aggregate entity that combines various entities to model visiting various locations, potentially doing one or multiple actions on each location, such as loading or unloading consignments. It is optionally coupled to a Vehicle that is/was driving this trip.

Get a specific Trip by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Trip

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Deletes a Trip

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Trip

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Trip

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

status
string

Whether this trip 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.

Enum: "draft" "requested" "confirmed" "inTransit" "completed" "cancelled" "accepted" "modified"
transportMode
string

Method of transport used for the carriage of goods on this trip, can either be using a ship (maritime or inland waterway), a truck/car/van/bike/etc. (road), using the train (rail), or using a plane (air). These values are based on the recommendation of UNECE.

Enum: "maritime" "road" "rail" "air" "inlandWaterway"
any

The Vehicle that is driving this trip.

Array of any

The actors associated with this trip, for instance the client or the executing party

Array of any (associations-actions)

All actions that are/were happening on this trip, such as stopping at certain locations and loading and unloading of consignments.

any

Constraints this trip has to abide to, such as the start and end date times in which it has to be completed.

Responses

Request samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "Daily supply trip",
  • "vehicle": {
    },
  • "actions": [
    ]
}

Action

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:

  • The Stop that models visiting a certain location at a certain time and potentially doing several other actions at that location.
  • The Load action, that models loading in one or multiple Consignments into a vehicle or some sort of container.
  • The Unload action, that models unloading one or multiple Consignments from a vehicle or some other sort of container.
  • The HandOver that indicates transferring a consignment from one Actor to another.
  • The Move that models moving between two or more locations, potentially with detailed route information on how to move between these locations.
  • The AttachTransportEquipment that allows you to attach some equipment to the associated vehicle. Note that you can both load/unload and attach/detach TransportEquipments. For instance loading a container on a ship, or attach a trailer to a truck. So choose the one that is most appropriate.
  • The DetachTransportEquipment that allows you to detach some previously attached equipment from the associated vehicle.
  • The Break action that models a mandatory resting period for the driver of the vehicle. During this period the driver is prohibited from doing any driving activities or other work.
  • The Wait action that models waiting at a particular location during the trip. This can be due to various circumstances such as waiting for the vehicle to be transported by a ferry or train. Or because of waiting at frontiers or docks (e.g. the dock of the loading/unload location is occupied) or traffic prohibitions. The driver is allowed to leave the vehicle during this period. An important aspect distinguishing this from the break action is that waiting times can be shortened because of changing circumstances. For example, if the original waiting time was expected to be 15 minutes because of an occupied dock, but the driver is 10 minutes late, the waiting time can be shortened to 5 minutes until the dock is free.
  • The GenericAction for whenever any of the above actions cannot model the situation appropriately.

Get a specific Action by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Action

Responses

Response samples

Content type
application/json
Example
load
load
unload
stop
move
handOver
attachTransportEquipment
detachTransportEquipment
break
wait
genericAction
{
  • "id": "e81a7aa3-23a6-4089-b916-52b854c7b6f1",
  • "lifecycle": "planned",
  • "remark": "loading a consignment",
  • "consignment": {
    },
  • "startTime": "2021-06-23T14:00:00.000Z",
  • "endTime": "2021-06-23T14:15:00.000Z",
  • "constraint": {
    },
  • "actionType": "load"
}

Deletes a Action

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Action

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a new Action

Authorizations:
Bearer token
Request Body schema: application/json
actionType
required
string
load
genericAction
wait
break
detachTransportEquipment
attachTransportEquipment
handOver
move
stop
unload
load
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

lifecycle
string

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

Enum: "requested" "planned" "projected" "actual" "realized"
object

The result of the action, can only be present in the actual or realized lifecycles. The result has a required status and optional additional info, like a remark and reason (in the case of failure).

remark
string

Free text field for adding an on remark on this action.

any

The stop that is associated with this action.

any

The consignment that is the subject of this action.

Array of any

Documents that are relevant for this action. Such as a proof-of-delivery photo, or scanned CMR.

any

The location at which this action is taking place.

startTime
string

The time at which the actions starts in ISO format.

endTime
string

The time at which the action is completed in ISO format.

Array of any (associations-actions)
any

The constraints this action abides to, such as start and end time windows.

Responses

Request samples

Content type
application/json
Example
load
load
unload
stop
move
handOver
attachTransportEquipment
detachTransportEquipment
break
wait
genericAction
{
  • "id": "e81a7aa3-23a6-4089-b916-52b854c7b6f1",
  • "lifecycle": "planned",
  • "remark": "loading a consignment",
  • "consignment": {
    },
  • "startTime": "2021-06-23T14:00:00.000Z",
  • "endTime": "2021-06-23T14:15:00.000Z",
  • "constraint": {
    },
  • "actionType": "load"
}

Response samples

Content type
application/json
Example
load
load
unload
stop
move
handOver
attachTransportEquipment
detachTransportEquipment
break
wait
genericAction
{
  • "id": "e81a7aa3-23a6-4089-b916-52b854c7b6f1",
  • "lifecycle": "planned",
  • "remark": "loading a consignment",
  • "consignment": {
    },
  • "startTime": "2021-06-23T14:00:00.000Z",
  • "endTime": "2021-06-23T14:15:00.000Z",
  • "constraint": {
    },
  • "actionType": "load"
}

Document

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.

Adds a new Document

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

required
any (content)
documentType
string

The type of the document, such as a photo, text document, PDF etc.

filename
string

The name of the file.

mimeType
string

The official MIME type of the file. See Wikepedia for more information.

description
string

The description of the file, for example what purpose it serves.

any

The actor who owns the document. If not provided, the creator will be assumed to be the owner.

any

The actor who owns the document. If not provided, the creator will be assumed to be the owner.

Responses

Request samples

Content type
application/json
{
  • "id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
  • "name": "Photo of the PoD",
  • "externalAttributes": {
    },
  • "content": {},
  • "documentType": "photo",
  • "filename": "my_photo.JPG",
  • "mimeType": "image.jpeg",
  • "description": "Proof that the goods are delivered by providing the photo that captures the moment",
  • "owner": {
    }
}

Response samples

Content type
application/json
{
  • "id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
  • "name": "Photo of the PoD",
  • "externalAttributes": {
    },
  • "content": {},
  • "documentType": "photo",
  • "filename": "my_photo.JPG",
  • "mimeType": "image.jpeg",
  • "description": "Proof that the goods are delivered by providing the photo that captures the moment",
  • "owner": {
    }
}

Get a specific Document by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Document

Responses

Response samples

Content type
application/json
{
  • "id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
  • "name": "Photo of the PoD",
  • "externalAttributes": {
    },
  • "content": {},
  • "documentType": "photo",
  • "filename": "my_photo.JPG",
  • "mimeType": "image.jpeg",
  • "description": "Proof that the goods are delivered by providing the photo that captures the moment",
  • "owner": {
    }
}

Deletes a Document

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Document

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Constraint

Constraints can do different things, depending on the context they're used in:

  • In the context of a Location, access to the location is only allowed if the given constraint applies.
  • In the context of a 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.
  • In the context of a 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.

Adds a new Constraint

Authorizations:
Bearer token
Request Body schema: application/json
id
string

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.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity.

lastModified
string

The last modified date of this entity. If none is given the creation date is used instead.

required
any (constraintValue)

Responses

Request samples

Content type
application/json
{
  • "id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
  • "name": "Time window constraints",
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
  • "name": "Time window constraints",
  • "value": {
    }
}

Get a specific Constraint by its UUID

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
{
  • "id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
  • "name": "Time window constraints",
  • "value": {
    }
}

Deletes a Constraint

Authorizations:
Bearer token
path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
[
  • {
    }
]