{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Trips & Planning","description":"The operational transportation management API. Full access to planning, tracking, invoicing, and integrations — built on the OTM5 open data standard.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"trips--planning","__idx":0},"children":["Trips & Planning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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.)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-trip","__idx":1},"children":["Creating a Trip"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a trip and link it to a consignment:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/trip \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"name\": \"RTD → AMS delivery\",\n    \"type\": \"road\",\n    \"vehicle\": { \"id\": \"vehicle-uuid\" },\n    \"chauffeurs\": [{ \"id\": \"chauffeur-uuid\" }]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"message\": \"OK\",\n  \"trip\": {\n    \"id\": \"trip-uuid\",\n    \"name\": \"RTD → AMS delivery\",\n    \"status\": \"planned\",\n    \"type\": \"road\",\n    \"vehicle\": { \"id\": \"vehicle-uuid\", \"name\": \"Truck NL-AB-12\" },\n    \"chauffeurs\": [{ \"id\": \"chauffeur-uuid\", \"firstName\": \"Peter\" }],\n    \"createdAt\": \"2026-03-22T10:00:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-trip-with-route-calculation","__idx":2},"children":["Creating a Trip with Route Calculation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":route"]}," endpoint to create a trip and automatically calculate the route in one call:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/trip:route \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"name\": \"RTD → AMS delivery\",\n    \"type\": \"road\",\n    \"vehicle\": { \"id\": \"vehicle-uuid\" },\n    \"actions\": [\n      {\n        \"type\": \"load\",\n        \"location\": { \"id\": \"warehouse-uuid\" },\n        \"startTime\": \"2026-03-23T08:00:00Z\"\n      },\n      {\n        \"type\": \"move\"\n      },\n      {\n        \"type\": \"unload\",\n        \"location\": { \"id\": \"destination-uuid\" },\n        \"startTime\": \"2026-03-23T11:00:00Z\"\n      }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"actions","__idx":3},"children":["Actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Actions are the atomic tasks within a trip. Each action type serves a specific purpose:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["load"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Load goods onto the vehicle at a location"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unload goods at the destination"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["move"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Drive between locations"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stop"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scheduled stop"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["break"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Driver rest break"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wait"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Waiting time (at dock, border crossing, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handOver"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer goods to another party"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customs clearance"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attachChauffeur"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Assign a driver mid-trip"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attachTransportEquipment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Attach a trailer or container"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"updating-action-times","__idx":4},"children":["Updating Action Times"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update the planned or actual times of a specific action:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT https://api.otms.transportial.com/api/trip/{tripId}/action/{actionId}/times \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"startTime\": \"2026-03-23T08:15:00Z\",\n    \"endTime\": \"2026-03-23T08:45:00Z\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"trip-lifecycle","__idx":5},"children":["Trip Lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trips follow a defined lifecycle. Use these endpoints to progress a trip through its stages:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"start-a-trip","__idx":6},"children":["Start a Trip"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/trip/{id}/start \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"finish-a-trip","__idx":7},"children":["Finish a Trip"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/trip/{id}/finish \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"chain-trips","__idx":8},"children":["Chain Trips"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finish one trip and immediately start the next:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET https://api.otms.transportial.com/api/trip/{id}/finish/{nextTripId}/start \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"confirm-or-cancel","__idx":9},"children":["Confirm or Cancel"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Confirm a single trip\ncurl -X GET https://api.otms.transportial.com/api/trip/{id}/confirm \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Cancel a single trip\ncurl -X GET https://api.otms.transportial.com/api/trip/{id}/cancel \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"batch-operations","__idx":10},"children":["Batch Operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirm or cancel multiple trips at once:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/trips/confirm \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '[\"trip-uuid-1\", \"trip-uuid-2\", \"trip-uuid-3\"]'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"route-types","__idx":11},"children":["Route Types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trips support multiple transport modes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Road"]}," — Route calculated via road network"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Maritime"]}," — Sea routes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rail"]}," — Rail network routes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Air"]}," — Air freight routes"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The route type affects how the route geometry and estimated duration are calculated."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"trip-optimization","__idx":12},"children":["Trip Optimization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the optimizer endpoint to create optimally planned trips from a set of consignments:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/trip/optimizer \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"consignments\": [\"consignment-uuid-1\", \"consignment-uuid-2\"],\n    \"vehicles\": [\"vehicle-uuid-1\"],\n    \"optimizeFor\": \"distance\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listing--searching-trips","__idx":13},"children":["Listing & Searching Trips"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List trips (paginated)\ncurl -X GET \"https://api.otms.transportial.com/api/trips/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Search trips with filters\ncurl -X POST \"https://api.otms.transportial.com/api/trips/0/20\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"status\": \"planned\",\n    \"startDate\": \"2026-03-22T00:00:00Z\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":14},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Learn about ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/concepts"},"children":["transport order lifecycle"]}," and how trips relate to consignments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explore ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/webhooks-and-events"},"children":["webhooks and events"]}," to get notified when trip status changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["See the full ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis"},"children":["API Reference"]}," for all trip endpoints"]}]}]},"headings":[{"value":"Trips & Planning","id":"trips--planning","depth":1},{"value":"Creating a Trip","id":"creating-a-trip","depth":2},{"value":"Creating a Trip with Route Calculation","id":"creating-a-trip-with-route-calculation","depth":2},{"value":"Actions","id":"actions","depth":2},{"value":"Updating Action Times","id":"updating-action-times","depth":3},{"value":"Trip Lifecycle","id":"trip-lifecycle","depth":2},{"value":"Start a Trip","id":"start-a-trip","depth":3},{"value":"Finish a Trip","id":"finish-a-trip","depth":3},{"value":"Chain Trips","id":"chain-trips","depth":3},{"value":"Confirm or Cancel","id":"confirm-or-cancel","depth":3},{"value":"Batch Operations","id":"batch-operations","depth":3},{"value":"Route Types","id":"route-types","depth":2},{"value":"Trip Optimization","id":"trip-optimization","depth":2},{"value":"Listing & Searching Trips","id":"listing--searching-trips","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Trips & Planning"}},"lastModified":"2026-03-22T20:40:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/trips-and-planning","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}