# 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:


```bash
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:**


```json
{
  "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:


```bash
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:

| Type | Description |
|  --- | --- |
| `load` | Load goods onto the vehicle at a location |
| `unload` | Unload goods at the destination |
| `move` | Drive between locations |
| `stop` | Scheduled stop |
| `break` | Driver rest break |
| `wait` | Waiting time (at dock, border crossing, etc.) |
| `handOver` | Transfer goods to another party |
| `customs` | Customs clearance |
| `attachChauffeur` | Assign a driver mid-trip |
| `attachTransportEquipment` | Attach a trailer or container |


### Updating Action Times

Update the planned or actual times of a specific action:


```bash
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


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

### Finish a Trip


```bash
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:


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

### Confirm or Cancel


```bash
# 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:


```bash
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:


```bash
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


```bash
# 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

- Learn about [transport order lifecycle](/guides/concepts) and how trips relate to consignments
- Explore [webhooks and events](/guides/webhooks-and-events) to get notified when trip status changes
- See the full [API Reference](/apis) for all trip endpoints