Create a plan
Creates a new plan inside the given project.
Creates a new plan inside the given project. A plan is the container for the routes and stops that will be executed on a specific date.
Recommended integration flow
POST /v2/plan?project_id=...— create the plan for the execution date.POST /v2/stops?plan_id=...(orPOST /v2/stops/geocode) — push the day's orders.POST /v2/plan/{id}/optimize— let the Routal optimizer build the routes.POST /v2/route/{id}/dispatch— send each route to its driver.
Payload size is limited to 3 MB. If you need to send more stops at once, split them into multiple POST /v2/stops calls after the plan is created.
Plan-level GeoFences are deprecated — the plan inherits the GeoFences defined at the project level and they cannot be overridden per plan.
Authorization
api_key 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
Query Parameters
^[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 POST "https://example.com/v2/plan?project_id=string" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "4f75d991ac359f8c4c79d762",
"organization_id": "4f75d991ac359f8c4c79d762",
"project_id": "4f75d991ac359f8c4c79d762",
"completed_stops": 1,
"canceled_stops": 2,
"pending_stops": 3,
"incomplete_stops": 3,
"total_stops": 6,
"total_routes": 5,
"label": "Eixample route — 2026-05-21",
"execution_date": "2026-05-29T14:55:24.518Z",
"status": "planning",
"created_by": "4f75d991ac359f8c4c79d762",
"created_at": "2026-05-29T14:55:24.518Z",
"updated_at": "2026-05-29T14:55:24.518Z",
"deleted_at": "2026-05-29T14:55:24.518Z",
"deleted": true
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}{
"message": "Domain not found",
"message_id": "highway.domain.error.not_found"
}