POST a Vehicle to Transport Allocation

To allocate a vehicle to 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.

In the payload of the request, the vehicle license plate number of the vehicle that should be allocated is used.

To execute an allocation, make an authenticated POST request as shown in the example below:

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

{
    "license_plate_number": "AB 12 CD"
}

Allocate a vehicle that is not in your vehicle network

In Transporeon Visibility, you can allocate

1. Vehicles from your current network, which comprises

   1. own vehicles and

   2. vehicles shared by your partners (e.g. subcontractors)

2. Vehicles outside of your current network, which are

   1. vehicles of partners which are not yet in your current network

The allocation to a vehicle outside of your current network is done in the same way as it is explained in POST a Vehicle to Transport Allocation section above.

You can notice the difference in the response message, which will be 200 OK (instead of 204 No Content for a regular allocation):

{
  message: "Global allocation - limited visibility. Allocated vehicle "12345" is outside of vehicle pool."
}

Allocate multiple vehicles to a transport

It is possible that multiple tracked vehicles are involved to execute a given transport.

This usually happens when a tractor takes the trailer from a loading stop to a switch location (cross-dock, warehouse, etc.), where another tractor hooks up the trailer and delivers it to the unloading stop:

The following ways of allocating multiple vehicles to a transport are supported, where the focus is on when a future vehicle should be taken into account for tracking

1. Immediately: When you allocate “Tractor A” on top of (the already existing allocation) “Tractor B”, Visibility switches to “Tractor B” at the time the request is received (“in real-time”). Also called “Real-time allocation”.
   This requires the carrier to know when to send the request in order to switch tractors.

   In order to do so, just send another POST allocation request as shown below:

   First:

   {
       "license_plate_number": "AB 12 CD"
   }

   And then:

   {
       "license_plate_number": "CD 34 EF"
   }

2. Auto-detect: You can plan the vehicles involved in a transport upfront. In that case, Visibility Hub will automatically detect when and where to switch from one tractor to the next one.
   It’s done when both vehicles have stopped in the same location, time independent (“based on auto-switch”).
   Example: Tractor A brings the trailer to a switch location and leaves again. Later, Tractor B arrives at the switch location and hooks the trailer. The stop in the same location is detected automatically and the tracking stream is switched to Tractor B.

   In order to send such an allocation request, you need to include the field allocation_switch_type with value auto_switch for the vehicle to be switched to as shown below:

   First:

   {
       "license_plate_number": "AB 12 CD"
   }

   And then (and repeat that step of all future vehicles):

   {
       "license_plate_number": "CD 34 EF",
       "allocation_switch_type": "auto_switch"
   }

3. Manual: You can plan the vehicles involved in a transport upfront. In this case, you supply a timestamp when Visibility Hub should switch from one tractor to the next one.
   In order to send such an allocation request, you need to include the optional field start_tracking_at with the timestamp value in addition to the license plate:
   First:

   {
       "license_plate_number": "AB 12 CD"
   }

   And then (and repeat that step of all future vehicles):

   {
       "license_plate_number": "CD 34 EF",
       "start_tracking_at": 2024-09-12T11:35:39.643Z"
   }

4. Combined: Auto-detect and Manual options can be combined. It follows the rules of auto-detect, but uses the manually added timestamp as a fallback in case the auto-detect didn’t work as expected, because for example GPS updates were missing or too infrequent.
   In order to send such an allocation request, you need to include the fields allocation_switch_type with value auto_switch as well as start_tracking_at with the timestamp indicated the latest time for the vehicle to be switched to as shown below:
   First:

   {
       "license_plate_number": "AB 12 CD"
   }

   And then (and repeat that step of all future vehicles):

   {
       "license_plate_number": "CD 34 EF",
       "allocation_switch_type": "auto_switch",
       "start_tracking_at": 2024-09-12T11:35:39.643Z"
   }

POST a vehicle deallocation

To remove the latest allocation from a transport, make an authenticated POST request as shown in the example below:

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

DELETE all allocations & tracking history

If you want to remove all vehicle allocations and delete tracking data already received from those vehicles on a given transport, you can revert this transport to it’s state before any allocations were received.

To do so, make an authenticated DELETE request as shown in the example below:

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

GET the Vehicle Allocated to a Transport

To receive the latest allocated vehicle for the given transport, make an authenticated GET request as shown in the example below:

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

The response contains the vehicle license plate number as well as the datetime when the allocation was created:

{
    "transport_allocation": {
        "created_at": "2022-12-15T02:03:47.179Z",
        "license_plate_number": "UL-RTV 24163"
    }
}