Skip to content
/
Trips & Planning
Last updated

Trips & Planning

Trips are the execution layer of transport orders. A trip defines the route, assigns a vehicle and chauffeur, and contains an ordered sequence of actions (load, move, unload, etc.).

Creating a Trip

Create a trip and link it to a consignment:

curl -X POST https://api.otms.transportial.com/api/trip \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "RTD → AMS delivery",
    "type": "road",
    "vehicle": { "id": "vehicle-uuid" },
    "chauffeurs": [{ "id": "chauffeur-uuid" }]
  }'

Response:

{
  "success": true,
  "message": "OK",
  "trip": {
    "id": "trip-uuid",
    "name": "RTD → AMS delivery",
    "status": "planned",
    "type": "road",
    "vehicle": { "id": "vehicle-uuid", "name": "Truck NL-AB-12" },
    "chauffeurs": [{ "id": "chauffeur-uuid", "firstName": "Peter" }],
    "createdAt": "2026-03-22T10:00:00Z"
  }
}

Creating a Trip with Route Calculation

Use the :route endpoint to create a trip and automatically calculate the route in one call:

curl -X POST https://api.otms.transportial.com/api/trip:route \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "RTD → AMS delivery",
    "type": "road",
    "vehicle": { "id": "vehicle-uuid" },
    "actions": [
      {
        "type": "load",
        "location": { "id": "warehouse-uuid" },
        "startTime": "2026-03-23T08:00:00Z"
      },
      {
        "type": "move"
      },
      {
        "type": "unload",
        "location": { "id": "destination-uuid" },
        "startTime": "2026-03-23T11:00:00Z"
      }
    ]
  }'

Actions

Actions are the atomic tasks within a trip. Each action type serves a specific purpose:

TypeDescription
loadLoad goods onto the vehicle at a location
unloadUnload goods at the destination
moveDrive between locations
stopScheduled stop
breakDriver rest break
waitWaiting time (at dock, border crossing, etc.)
handOverTransfer goods to another party
customsCustoms clearance
attachChauffeurAssign a driver mid-trip
attachTransportEquipmentAttach a trailer or container

Updating Action Times

Update the planned or actual times of a specific action:

curl -X PUT https://api.otms.transportial.com/api/trip/{tripId}/action/{actionId}/times \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "startTime": "2026-03-23T08:15:00Z",
    "endTime": "2026-03-23T08:45:00Z"
  }'

Trip Lifecycle

Trips follow a defined lifecycle. Use these endpoints to progress a trip through its stages:

Start a Trip

curl -X GET https://api.otms.transportial.com/api/trip/{id}/start \
  -H "Authorization: Bearer YOUR_TOKEN"

Finish a Trip

curl -X GET https://api.otms.transportial.com/api/trip/{id}/finish \
  -H "Authorization: Bearer YOUR_TOKEN"

Chain Trips

Finish one trip and immediately start the next:

curl -X GET https://api.otms.transportial.com/api/trip/{id}/finish/{nextTripId}/start \
  -H "Authorization: Bearer YOUR_TOKEN"

Confirm or Cancel

# Confirm a single trip
curl -X GET https://api.otms.transportial.com/api/trip/{id}/confirm \
  -H "Authorization: Bearer YOUR_TOKEN"

# Cancel a single trip
curl -X GET https://api.otms.transportial.com/api/trip/{id}/cancel \
  -H "Authorization: Bearer YOUR_TOKEN"

Batch Operations

Confirm or cancel multiple trips at once:

curl -X POST https://api.otms.transportial.com/api/trips/confirm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '["trip-uuid-1", "trip-uuid-2", "trip-uuid-3"]'

Route Types

Trips support multiple transport modes:

  • Road — Route calculated via road network
  • Maritime — Sea routes
  • Rail — Rail network routes
  • Air — Air freight routes

The route type affects how the route geometry and estimated duration are calculated.

Trip Optimization

Use the optimizer endpoint to create optimally planned trips from a set of consignments:

curl -X POST https://api.otms.transportial.com/api/trip/optimizer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "consignments": ["consignment-uuid-1", "consignment-uuid-2"],
    "vehicles": ["vehicle-uuid-1"],
    "optimizeFor": "distance"
  }'

Listing & Searching Trips

# List trips (paginated)
curl -X GET "https://api.otms.transportial.com/api/trips/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search trips with filters
curl -X POST "https://api.otms.transportial.com/api/trips/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "planned",
    "startDate": "2026-03-22T00:00:00Z"
  }'

Next Steps

Previous page
Next page