{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Planning a Multi-Stop Trip","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":"planning-a-multi-stop-trip","__idx":0},"children":["Planning a Multi-Stop Trip"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"objective","__idx":1},"children":["Objective"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Plan a trip with multiple pickup and delivery stops, assign a vehicle and chauffeur, and calculate the optimal route."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scenario","__idx":2},"children":["Scenario"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need to deliver goods from a warehouse in Rotterdam to two customers in Amsterdam and Utrecht, with a return to the depot."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-the-transport-order","__idx":3},"children":["Step 1: Create the Transport Order"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/transportOrder \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"name\": \"Multi-drop RTD → AMS + UTR\",\n    \"status\": \"requested\",\n    \"consignments\": [\n      {\n        \"name\": \"Amsterdam delivery\",\n        \"status\": \"requested\",\n        \"goods\": [\n          {\n            \"type\": \"items\",\n            \"description\": \"Consumer electronics\",\n            \"quantity\": 30,\n            \"weight\": { \"value\": 600, \"unit\": \"kg\" }\n          }\n        ]\n      },\n      {\n        \"name\": \"Utrecht delivery\",\n        \"status\": \"requested\",\n        \"goods\": [\n          {\n            \"type\": \"items\",\n            \"description\": \"Office supplies\",\n            \"quantity\": 15,\n            \"weight\": { \"value\": 200, \"unit\": \"kg\" }\n          }\n        ]\n      }\n    ]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-create-the-trip-with-route-calculation","__idx":4},"children":["Step 2: Create the Trip with Route Calculation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":route"]}," endpoint to create the trip with automatic route calculation. Define the actions in order:"]},{"$$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\": \"Multi-drop trip RTD-AMS-UTR\",\n    \"type\": \"road\",\n    \"vehicle\": { \"id\": \"truck-uuid\" },\n    \"chauffeurs\": [{ \"id\": \"chauffeur-uuid\" }],\n    \"actions\": [\n      {\n        \"type\": \"load\",\n        \"location\": { \"id\": \"rotterdam-warehouse-uuid\" },\n        \"startTime\": \"2026-03-23T07:00:00Z\",\n        \"endTime\": \"2026-03-23T07:45:00Z\"\n      },\n      {\n        \"type\": \"move\"\n      },\n      {\n        \"type\": \"unload\",\n        \"location\": { \"id\": \"amsterdam-customer-uuid\" },\n        \"startTime\": \"2026-03-23T08:30:00Z\",\n        \"endTime\": \"2026-03-23T09:00:00Z\"\n      },\n      {\n        \"type\": \"move\"\n      },\n      {\n        \"type\": \"unload\",\n        \"location\": { \"id\": \"utrecht-customer-uuid\" },\n        \"startTime\": \"2026-03-23T10:00:00Z\",\n        \"endTime\": \"2026-03-23T10:30:00Z\"\n      },\n      {\n        \"type\": \"move\"\n      },\n      {\n        \"type\": \"stop\",\n        \"location\": { \"id\": \"rotterdam-warehouse-uuid\" },\n        \"startTime\": \"2026-03-23T11:30:00Z\"\n      }\n    ]\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\": \"Multi-drop trip RTD-AMS-UTR\",\n    \"status\": \"planned\",\n    \"routeStatus\": \"calculated\",\n    \"estimatedDuration\": 16200,\n    \"route\": {\n      \"distance\": 142.5,\n      \"geometry\": \"...\"\n    },\n    \"actions\": [\n      { \"id\": \"action-1\", \"type\": \"load\", \"status\": \"planned\" },\n      { \"id\": \"action-2\", \"type\": \"move\", \"status\": \"planned\" },\n      { \"id\": \"action-3\", \"type\": \"unload\", \"status\": \"planned\" },\n      { \"id\": \"action-4\", \"type\": \"move\", \"status\": \"planned\" },\n      { \"id\": \"action-5\", \"type\": \"unload\", \"status\": \"planned\" },\n      { \"id\": \"action-6\", \"type\": \"move\", \"status\": \"planned\" },\n      { \"id\": \"action-7\", \"type\": \"stop\", \"status\": \"planned\" }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-confirm-the-trip","__idx":5},"children":["Step 3: Confirm the Trip"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/trip/{trip-uuid}/confirm\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-start-the-trip","__idx":6},"children":["Step 4: Start the Trip"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the driver begins:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/trip/{trip-uuid}/start\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-update-action-times-as-execution-happens","__idx":7},"children":["Step 5: Update Action Times as Execution Happens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the driver completes each action, update the actual times:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Mark loading complete\ncurl -X PUT \"https://api.otms.transportial.com/api/trip/{trip-uuid}/action/{action-1}/times\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"startTime\": \"2026-03-23T07:05:00Z\",\n    \"endTime\": \"2026-03-23T07:50:00Z\"\n  }'\n\n# Mark Amsterdam unload complete\ncurl -X PUT \"https://api.otms.transportial.com/api/trip/{trip-uuid}/action/{action-3}/times\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"startTime\": \"2026-03-23T08:40:00Z\",\n    \"endTime\": \"2026-03-23T09:10:00Z\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-finish-the-trip","__idx":8},"children":["Step 6: Finish the Trip"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/trip/{trip-uuid}/finish\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-takeaways","__idx":9},"children":["Key Takeaways"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trip:route"]}," to create trips with automatic route calculation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Actions are executed in order — load → move → unload → move → unload → move → stop"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update action times with actual timestamps as the driver progresses"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The route response includes distance and geometry for map visualization"]}]}]},"headings":[{"value":"Planning a Multi-Stop Trip","id":"planning-a-multi-stop-trip","depth":1},{"value":"Objective","id":"objective","depth":2},{"value":"Scenario","id":"scenario","depth":2},{"value":"Step 1: Create the Transport Order","id":"step-1-create-the-transport-order","depth":2},{"value":"Step 2: Create the Trip with Route Calculation","id":"step-2-create-the-trip-with-route-calculation","depth":2},{"value":"Step 3: Confirm the Trip","id":"step-3-confirm-the-trip","depth":2},{"value":"Step 4: Start the Trip","id":"step-4-start-the-trip","depth":2},{"value":"Step 5: Update Action Times as Execution Happens","id":"step-5-update-action-times-as-execution-happens","depth":2},{"value":"Step 6: Finish the Trip","id":"step-6-finish-the-trip","depth":2},{"value":"Key Takeaways","id":"key-takeaways","depth":2}],"frontmatter":{"seo":{"title":"Planning a Multi-Stop Trip"}},"lastModified":"2026-03-22T21:04:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/examples/planning-multi-stop-trip","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}