This section describes how to Create, Update and Delete transports in Transporeon Visibility. The related technical specification can be found here.

The create, update (of the transport object, e.g. timeslots, stop data, etc.) and delete functionality require an activation within Transporeon Visibility. Therefore, please contact https://support.transporeon.com or your Transporeon representative if you want to use it. In addition, the update and delete operations are limited to transports which have also been created via the here described Visibility API.

1 PUT Create or Update a Transport
- 1.1 Stops
- 1.2 Delivery items
  - 1.2.1 Collection & Delivery Stops
  - 1.2.2 Intermediate stops
- 1.3 Carrier
2 DELETE a transport

PUT Create or Update a Transport

To create or update a transport, you must provide the following URL parameters:

The identifier_type that should be used to uniquely identify the transport. The available types are:
- transport_id
- transport_number
  --> see here for more infos on the definition of those fields.
The identifier_value: The actual value of the identifier.

The transport_id is a UUID generated by Transporeon and part of the synchronous response when creating a transport using the transport_number. The former can therefore only be used for updating a transport, while the latter additionally allows a transport creation, for which this attribute becomes mandatory.

In the payload of the request to create or update a transport several transport master data attributes are mandatory or optional, while further details on that can be found in the technical specification here.

While different transport modes are supported within Transporeon Visibility, this section focuses on Road-Transports.

To create or update a transport an authenticated PUT request is required to the following endpoint. The example payload below contains some of the most important data attributes, which are further described subsequently.

PUT https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}

{
    "stops": [
        {
            "stop_reference_number": "stop-reference-1",
            "sequence_number": 1,
            "location": {
                "location_reference_number": "BBL04",
                "name": "Berlin Beverages Loading",
                "address": {
                    "full_address": "Magirus-Deutz-Str. 16, 89077, Ulm, DE",
                    "street_address": "Magirus-Deutz-Str. 16",
                    "city": "Ulm",
                    "country": "DE",
                    "zipcode": "89077"
                },
                "position": {
                    "lat": 48.398875,
                    "lng": 9.959085
                }
            },
            "timeslot": {
                "begin": "2025-02-18T14:50:18.044Z",
                "end": "2025-02-18T14:55:18.044Z"
            }
        },
        {
            "stop_reference_number": "stop-reference-2",
            "sequence_number": 2,
            "location": {
                "place_reference_id": "UAKEC1234",
            },
            "timeslot": {
                "begin": "2025-02-18T20:15:18.044Z",
                "end": "2025-02-18T20:35:18.044Z"
            }
        }
    ],
    "delivery_items": [
        {
            "delivery_item_type": "delivery_order",
            "delivery_order_number": "62305",
            "stop_references": [
                {
                    "stop_reference_number": "stop-reference-1",
                    "action": "collection"
                },
                {
                    "stop_reference_number": "stop-reference-2",
                    "action": "delivery"
                }
            ]
        }
    ],
    "assigned_carrier_id_type": "company_id",
    "assigned_carrier_id_value": "123456"
}

Note that the endpoint for creating or updating a transport expects a full state payload so previously provided transport data will be overwritten.

Stops

A transport must contain one or more stops.

Each stop requires a unique stop_reference_number. The sequence_number determines the order in which stops are visited during transport—this is critical for tracking purposes.

Each stop must also include physical location information. This can be provided in one of two ways:

place_reference_id can be used to match an existing Visibility Hub Place (see Manage Visibility Places documentation) or
location can be specified as an object containing address and/or position (coordinates) data. When both are present, position takes precedence. This object includes a unique location_reference_number to identify the location on the implementer side and a location name for display purposes.

For accurate tracking, each stop must have a planned timeslot with begin and end times. These timeslots represent the carrier's planned arrival times. More precise timeslots enable the tracking engine to calculate more accurate estimated times of arrival (ETA).

Timestamps are expected in ISO 8601 format and presented to the user in local time. The recommendation is to provide them in UTC (or specify the UTC offset).

Example snapshot:

    "stops": [
        {
            "stop_reference_number": "stop-reference-1",
            "sequence_number": 1,
            "location": {
                "location_reference_number": "BBL04",
                "name": "Berlin Beverages Loading",
                "address": {
                    "full_address": "Magirus-Deutz-Str. 16, 89077, Ulm, DE",
                    "street_address": "Magirus-Deutz-Str. 16",
                    "city": "Ulm",
                    "country": "DE",
                    "zipcode": "89077"
                },
                "position": {
                    "lat": 48.398875,
                    "lng": 9.959085
                }
            },
            "timeslot": {
                "begin": "2025-02-18T14:50:00.000Z",
                "end": "2025-02-18T14:55:00.000Z"
            }
        }
    ]

Delivery items

Besides stops, transports optionally can contain relevant delivery_items. One of the supported and primary delivery_item_types for a road transport is a: delivery_order.

A delivery_order needs a unique delivery number in the scope of the transport, which must be specified with the delivery_order_number field by the transport creator.

For each delivery item, the system generates a unique delivery ID, which appears as delivery_id in the GET /transports endpoint (see here). The delivery_order_number is shown as delivery_number.

Collection & Delivery Stops

A delivery_order can be linked to one or multiple stops (typically two—pickup and delivery locations) using the stop_reference_number specified on the stops:

collection: Where the goods are being picked up
delivery: Where the goods are being delivery to

Example: A transport snapshot showing one delivery order being collected at one stop and delivered to another:

    "delivery_items": [
        {
            "delivery_item_type": "delivery_order",
            "delivery_order_number": "dn-1",
            "stop_references": [
                {
                    "stop_reference_number": "stop-reference-1",
                    "action": "collection"
                },
                {
                    "stop_reference_number": "stop-reference-2",
                    "action": "delivery"
                }
            ]
        }
    ]

Example: A transport snapshot showing two delivery orders being collected at one stop and delivered to two separate stops:

    "delivery_items": [
        {
            "delivery_item_type": "delivery_order",
            "delivery_order_number": "dn-1",
            "stop_references": [
                {
                    "stop_reference_number": "stop-reference-1",
                    "action": "collection"
                },
                {
                    "stop_reference_number": "stop-reference-2",
                    "action": "delivery"
                }
            ]
        },
        {
            "delivery_item_type": "delivery_order",
            "delivery_order_number": "dn-2",
            "stop_references": [
                {
                    "stop_reference_number": "stop-reference-1",
                    "action": "collection"
                },
                {
                    "stop_reference_number": "stop-reference-3",
                    "action": "delivery"
                }
            ]
        }
    ]

Intermediate stops

For intermediate stops such as ferry ports, customs checkpoints, cross-dock locations, or entry gates where no loading or unloading takes place, referencing the delivery_order is not needed. The definition in the stops list is sufficient.

However, you can still link the delivery_order to such stops if you want to require tracking this stop visit before proceeding to the delivery stop. Note: This creates a strict requirement: If we cannot track this stop, we cannot track the delivery visit.
Additionally, when specifying the action as a waypoint, the system uses a smaller geofence size and simplified stop visit detection. See here to learn more about stop visit detection & geofencing in Transporeon Visibility.

If you're unsure which option to choose, contact support at https://support.transporeon.com/

Carrier

A stakeholder who creates or updates a transport is considered the transport creator or owner. Each transport must also be assigned to a carrier who acts as the executing stakeholder.

If you execute a transport with your own vehicle instead of assigning it to a carrier, use your company_id as the assigned_carrier_id_value.

The transport assignment can be realized by using either the Transporeon account company_id or by the relation_identifier specified between the transport owner and executor.

You can use the /partners endpoint documented here to look up the company_id and relation_identifier for a specific company.

Example snapshot:

    "assigned_carrier_id_type": "company_id",
    "assigned_carrier_id_value": "123456"

If assigned_carrier_id_type is not provided company_id will be used by default.

DELETE a transport

To delete a transport, you must provide the following URL parameters:

The identifier_type that should be used to uniquely identify the transport. The available types are:
- transport_id
- transport_number
  --> see here for more infos on the definition of those fields.

The DELETE operation is asynchronous and it may take a few moments before a transport is actually deleted.

To delete a transport an authenticated DELETE request is required to the following endpoint by using either transport_id or transport_number.

DELETE https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}

Transporeon API Developer Portal

Create, Update or Delete a Transport