Plan a route

POST /dn/routes/plan creates a route or updates an existing one by name and date, then returns the optimized plan with sequenced jobs.

POST /dn/routes/plan

Plan a route

cURL

curl --request POST \
  --url https://app.detrack.com/api/v2/dn/routes/plan \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "data": {
    "name": "sample_run",
    "date": "2026-09-15",
    "vehicles": [
      "Driver 1",
      "Driver 2"
    ],
    "job_ids": [
      "<string>"
    ],
    "depot_location": {
      "id": "674ecabbe8ec54052f7ead41"
    },
    "end_depot_location": {
      "id": "674ecabbe8ec54052f7ead41"
    },
    "mode": "drive",
    "manual_time_windows": false,
    "time_window_from": "07:00",
    "time_window_to": "23:50",
    "traffic": "free_flow",
    "max_speed": 123,
    "service_time": 123,
    "manual_service_time": false,
    "avoid_toll": false,
    "manual_depot": false,
    "manual_end_depot": false,
    "retain_assignments": false,
    "assign_route": false,
    "vrp_exclude_send_driver": false
  }
}
'

200

{
  "data": {
    "id": "69001c6de8ec5410e2570bb3",
    "name": "sample_run",
    "date": "2026-09-15",
    "mode": "drive",
    "status": "to_be_confirm",
    "message": "<string>",
    "vehicle": {},
    "job_ids": [
      "<string>"
    ],
    "depot_location": {
      "id": "68f0d416e8ec54cbf4a04dba",
      "name": "Main Depot",
      "address": "SM Megamall, EDSA corner Doña Julia Vargas Ave, Mandaluyong, 1550 Metro Manila",
      "addr_1": "<string>",
      "addr_2": "<string>",
      "addr_3": "<string>",
      "zip_code": "<string>",
      "country": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country_id": "<string>",
      "location": [
        121.055626,
        14.583941
      ],
      "address_lat": 14.583941,
      "address_lng": 121.055626
    },
    "end_depot_location": {
      "id": "68f0d416e8ec54cbf4a04dba",
      "name": "Main Depot",
      "address": "SM Megamall, EDSA corner Doña Julia Vargas Ave, Mandaluyong, 1550 Metro Manila",
      "addr_1": "<string>",
      "addr_2": "<string>",
      "addr_3": "<string>",
      "zip_code": "<string>",
      "country": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country_id": "<string>",
      "location": [
        121.055626,
        14.583941
      ],
      "address_lat": 14.583941,
      "address_lng": 121.055626
    },
    "total_distance": 15107,
    "total_time": 4373.497,
    "total_planned": 3,
    "total_unplanned": 0,
    "type": "balanced",
    "jobs": [
      {
        "id": "68e0bac7e8ec545357500616",
        "type": "Delivery",
        "status": "dispatched",
        "do_number": "DO-10001",
        "address": "Vicente Sotto St, CCP Complex, Pasay 1307",
        "deliver_to_collect_from": "<string>",
        "phone_number": "<string>",
        "time_window_from": "09:00",
        "time_window_to": "12:00",
        "job_sequence": 1,
        "eta_time": "07:05",
        "run_number": "1",
        "service_time": 10,
        "geocoded_lat": 14.5542,
        "geocoded_lng": 120.9839,
        "has_latlng": true
      }
    ],
    "planned_routes": [
      {
        "id": "69001c6fe8ec5410e2570bc0",
        "vrp_id": "69001c6de8ec5410e2570bb3",
        "name": "1",
        "date": "2026-09-15",
        "status": "to_be_confirm",
        "vehicle": {},
        "time_window_from": "07:00",
        "time_window_to": "23:50",
        "start_time": "07:00",
        "completion_time": "08:12",
        "total_distance": 15107,
        "total_time": 4373.497,
        "total_planned": 3,
        "total_unplanned": 0,
        "planned_jobs": [
          {
            "id": "68e0bac7e8ec545357500616",
            "type": "Delivery",
            "status": "dispatched",
            "do_number": "DO-10001",
            "address": "Vicente Sotto St, CCP Complex, Pasay 1307",
            "deliver_to_collect_from": "<string>",
            "phone_number": "<string>",
            "time_window_from": "09:00",
            "time_window_to": "12:00",
            "job_sequence": 1,
            "eta_time": "07:05",
            "run_number": "1",
            "service_time": 10,
            "geocoded_lat": 14.5542,
            "geocoded_lng": 120.9839,
            "has_latlng": true
          }
        ],
        "unplanned_jobs": [
          {
            "id": "68e0bac7e8ec545357500616",
            "type": "Delivery",
            "status": "dispatched",
            "do_number": "DO-10001",
            "address": "Vicente Sotto St, CCP Complex, Pasay 1307",
            "deliver_to_collect_from": "<string>",
            "phone_number": "<string>",
            "time_window_from": "09:00",
            "time_window_to": "12:00",
            "job_sequence": 1,
            "eta_time": "07:05",
            "run_number": "1",
            "service_time": 10,
            "geocoded_lat": 14.5542,
            "geocoded_lng": 120.9839,
            "has_latlng": true
          }
        ]
      }
    ],
    "unplanned_jobs": [
      {
        "id": "68e0bac7e8ec545357500616",
        "type": "Delivery",
        "status": "dispatched",
        "do_number": "DO-10001",
        "address": "Vicente Sotto St, CCP Complex, Pasay 1307",
        "deliver_to_collect_from": "<string>",
        "phone_number": "<string>",
        "time_window_from": "09:00",
        "time_window_to": "12:00",
        "job_sequence": 1,
        "eta_time": "07:05",
        "run_number": "1",
        "service_time": 10,
        "geocoded_lat": 14.5542,
        "geocoded_lng": 120.9839,
        "has_latlng": true
      }
    ]
  }
}

Use this endpoint to build a new route or overwrite an existing route that shares the same name and date. Detrack runs an optimization engine to sequence the supplied job_ids, compute ETAs, and return totals such as distance and duration. If the route already exists, it is replaced with the newly computed plan.

Known issues:

• If you re-plan with the same name and date and the request fails validation, the existing plan has already been deleted and isn’t replaced. Check your request before re-planning (DTR-6207).
• Each name in vehicles matches any vehicle whose name contains it, ignoring case. For example, Driver 1 also selects Driver 10. Use vehicle names that aren’t contained in other names (DTR-6206).

Vehicle working hours (from and to) are configured per driver inside the Detrack app; they are not part of the API request payload.

Each route has two levels:

• The plan (the top-level object) holds the plan’s status, depot, and totals across all vehicles.
• planned_routes has one entry per vehicle, with that vehicle’s status, start_time, completion_time, time window, and its planned_jobs in delivery order (job_sequence, eta_time).

Jobs that couldn’t be placed on any vehicle are in the plan-level unplanned_jobs. The plan-level vehicle shows one of the plan’s vehicles; use planned_routes[].vehicle to see which vehicle drives which route. See Route status for what each status value means.

Errors

Validation errors return 422 with a code and message. The API checks the request in the order below and stops at the first failure.

code	When
invalid_data	The request body has no data object.
missing_name_or_date	data.name or data.date is missing.
missing_jobs	data.job_ids is missing or empty.
missing_vehicles	data.vehicles is missing or empty.
error_vehicles	data.vehicles isn’t an array.
no_vehicles_found	None of the names in data.vehicles match a vehicle in your account.
validation_failed	The plan couldn’t be saved. The errors array lists each failing field and its codes.

{
  "code": "no_vehicles_found",
  "message": "No Vehicles Found"
}

See Errors for other status codes.

Authorizations

X-API-KEY · string · header · required

Your Detrack API key, from Integrations > API Key in the dashboard.

Body

application/json

data · object · required

Show child attributes

Response

200

application/json

Optimization finished.

data · object

Show child attributes