API ReferenceRoute
Reorder the stops of a route
Sets the ordered list of stop IDs for this route.
Sets the ordered list of stop IDs for this route. Use this when you want to manually override the optimizer's sequence (e.g. a dispatcher dragging and dropping stops in your own UI, or a custom heuristic implemented on your side).
ETAs, distance and duration are recomputed automatically. Stops not included in the payload are unassigned from the route. Stops that don't currently belong to this route's plan are rejected.
Authorization
api_key private_key<token>
The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.
In: query
Path Parameters
id*string
Route ID
Match
^[0-9a-f]{24}Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v2/route/string/stops" \ -H "Content-Type: application/json" \ -d '{ "stops": [ "4f75d991ac359f8c4c79d762" ] }'{
"id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"external_id": "ROUTE-2026-05-21-MAD03",
"start_location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"end_location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"label": "Eixample route — Refrigerated van 02",
"phone": "+34612345678",
"comments": "Load at 06:00 at dock 4. Depart 06:30.",
"email": "carlos.lopez@example.com",
"plate": "2596 KHO",
"vehicle_model": "Transit Custom L2H2",
"color": "#1E88E5",
"brand": "Ford",
"vehicle": {
"fuel_type": "diesel",
"consumption": 8,
"break": {
"start": 43200,
"end": 54000,
"duration": 2700
}
},
"planned_track": "spxsBsdb|Lymo`qvAx@TKvAr@K",
"is_locked": true,
"geo_fences": [
"4f75d991ac359f8c4c79d762"
],
"time_window": [
28800,
61200
],
"max_distance": 120000,
"min_distance": 5000,
"max_time": 28800,
"min_time": 3600,
"max_weight": 800,
"max_volume": 8,
"max_services": 40,
"provides": [
"refrigerated",
"lift_gate"
],
"order": 0,
"start_date": "2026-05-29T14:55:24.509Z",
"end_date": "2026-05-29T14:55:24.509Z",
"estimated_end_time": "2026-05-29T14:55:24.509Z",
"last_position": {
"lat": 40.45,
"lng": -3.68,
"created_at": "2026-05-29T14:55:24.508Z",
"orientation": 270
},
"planned_start_time": 23400,
"planned_end_time": 50400,
"custom_fields": {},
"distance_traveled": 0,
"tracing_percent": 0,
"price_per_minute": 0.0035,
"price_per_distance": 0.00045,
"toll_price": 4.8,
"toll_price_currency": "EUR",
"status": "not_started",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true,
"stops": [
{
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "delivery",
"route_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"client_id": "4f75d991ac359f8c4c79d762",
"client_external_id": "CUST-58291",
"external_id": "ORD-2026-58291",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"location_details": "Local 2, junto a la entrada principal",
"label": "Acme Pharmacy — Aragó branch",
"comments": "Ring intercom 2B. Do not leave at reception.",
"phone": "+34612345678",
"email": "sarah.johnson@example.com",
"url": "https://shop.example.com/orders/58291",
"reference_person": "Sarah Johnson",
"duration": 180,
"requires": [
"refrigerated",
"fragile"
],
"cluster": "eixample-norte",
"reward": 5,
"time_windows": [
[
28800,
61200
]
],
"volume": 0.12,
"weight": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-05-29T14:55:24.491Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-05-29T14:55:24.491Z",
"estimated_departure_time": "2026-05-29T14:55:24.491Z",
"pickup_id": "4f75d991ac359f8c4c79d762",
"distance_to_previous_stop": 30000,
"distance_to_next_stop": 20000,
"optimization_warning": true,
"chain_id": "order-58291",
"chain_position": 1,
"custom_fields": {
"order_reference": "ORD-2026-58291",
"parcel_count": 2,
"cod_amount": 24.9
},
"tasks": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"label": "Deliver refrigerated parcel 1/2",
"comments": "Keep cold chain. Weight 12.4 kg.",
"barcode": "8410076472158",
"status": "completed",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
},
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.485Z",
"updated_at": "2026-05-29T14:55:24.485Z",
"deleted_at": "2026-05-29T14:55:24.485Z"
}
],
"reports": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "service_report_completed",
"comments": "Customer not present. Notice left in the mailbox.",
"images": [
{
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
}
],
"signature": {
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
},
"tasks": [
{
"task_id": "4f75d991ac359f8c4c79d762",
"status": "completed",
"comments": "Parcel delivered in perfect condition.",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
}
}
],
"cancel_reason": "nobody",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-05-29T14:55:24.486Z"
}
],
"report_attempts": 2,
"survey": {
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"rating": 1,
"rating_tag": "time",
"comments": "The delivery was very professional and punctual.",
"created_at": "2026-05-29T14:55:24.489Z",
"updated_at": "2026-05-29T14:55:24.489Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-05-29T14:55:24.499Z",
"location_validated": false,
"location_validated_at": "2026-05-29T14:55:24.500Z",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true,
"pickup": {
"id": "4f75d991ac359f8c4c79d762",
"fixed_id": "1",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "delivery",
"route_id": "4f75d991ac359f8c4c79d762",
"vehicle_id": "4f75d991ac359f8c4c79d762",
"client_id": "4f75d991ac359f8c4c79d762",
"client_external_id": "CUST-58291",
"external_id": "ORD-2026-58291",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"location_details": "Local 2, junto a la entrada principal",
"label": "Acme Pharmacy — Aragó branch",
"comments": "Ring intercom 2B. Do not leave at reception.",
"phone": "+34612345678",
"email": "sarah.johnson@example.com",
"url": "https://shop.example.com/orders/58291",
"reference_person": "Sarah Johnson",
"duration": 180,
"requires": [
"refrigerated",
"fragile"
],
"cluster": "eixample-norte",
"reward": 5,
"time_windows": [
[
28800,
61200
]
],
"volume": 0.12,
"weight": 8.4,
"max_delivery_time": 7200,
"status": "pending",
"plan_execution_date": "2026-05-29T14:55:24.491Z",
"order": 0,
"planned_arrival_time": 29500,
"planned_departure_time": 30000,
"estimated_arrival_time": "2026-05-29T14:55:24.491Z",
"estimated_departure_time": "2026-05-29T14:55:24.491Z",
"pickup_id": "4f75d991ac359f8c4c79d762",
"distance_to_previous_stop": 30000,
"distance_to_next_stop": 20000,
"optimization_warning": true,
"chain_id": "order-58291",
"chain_position": 1,
"custom_fields": {
"order_reference": "ORD-2026-58291",
"parcel_count": 2,
"cod_amount": 24.9
},
"tasks": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"label": "Deliver refrigerated parcel 1/2",
"comments": "Keep cold chain. Weight 12.4 kg.",
"barcode": "8410076472158",
"status": "completed",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
},
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.485Z",
"updated_at": "2026-05-29T14:55:24.485Z",
"deleted_at": "2026-05-29T14:55:24.485Z"
}
],
"reports": [
{
"id": "4f75d991ac359f8c4c79d762",
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"plan_id": "4f75d991ac359f8c4c79d762",
"type": "service_report_completed",
"comments": "Customer not present. Notice left in the mailbox.",
"images": [
{
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
}
],
"signature": {
"id": "4f75d991ac359f8c4c79d762",
"url": "https://api.routal.com"
},
"tasks": [
{
"task_id": "4f75d991ac359f8c4c79d762",
"status": "completed",
"comments": "Parcel delivered in perfect condition.",
"custom_fields": {
"sku": "SKU-4582",
"quantity": 2,
"lot_number": "L-2026-038"
}
}
],
"cancel_reason": "nobody",
"location": {
"location_id": "4f75d991ac359f8c4c79d762",
"label": "Location label",
"country": "Spain",
"country_code": "ES",
"state": "Catalonia",
"city": "Barcelona",
"street": "Calle de Pau Claris",
"postal_code": "08302",
"comments": "Location comments",
"lat": 40.45,
"lng": -3.68,
"main_text": "Calle de Pau Claris 12",
"secondary_text": "Barcelona, Catalonia, Spain"
},
"time_in_stop": 180,
"custom_fields": {
"delivered_to": "neighbor 2A",
"cod_collected": 24.9,
"photo_count": 2
},
"created_at": "2026-05-29T14:55:24.486Z"
}
],
"report_attempts": 2,
"survey": {
"stop_id": "4f75d991ac359f8c4c79d762",
"route_id": "4f75d991ac359f8c4c79d762",
"rating": 1,
"rating_tag": "time",
"comments": "The delivery was very professional and punctual.",
"created_at": "2026-05-29T14:55:24.489Z",
"updated_at": "2026-05-29T14:55:24.489Z"
},
"pin": "4729",
"customer_text_field": "Leave at reception if I'm not home.",
"supervisors": [
"4f75d991ac359f8c4c79d762"
],
"location_validation_sent": false,
"location_validation_sent_at": "2026-05-29T14:55:24.499Z",
"location_validated": false,
"location_validated_at": "2026-05-29T14:55:24.500Z",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.339Z",
"updated_at": "2026-05-29T14:55:24.339Z",
"deleted_at": "2026-05-29T14:55:24.339Z",
"deleted": true
}
}
],
"break_stop": {
"is_completed": false,
"order": 2,
"planned_start_time": 20000,
"planned_end_time": 30000,
"real_start_time": 20000,
"real_end_time": 30000
}
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}Empty
{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}Empty
Empty
Dispatch a route to its driver
Sends an email to the route's assigned driver containing a public driver link that opens the route in the Routal Drivers webview or mobile app.
Retrieve a stop
Returns a stop with its full execution payload: tasks, status, time windows, customer details, geocoded location, proof of delivery (signature, photos, scans),…