Skip to main content
Routal

Create a plan

Creates a new plan inside the given project.

POST
/v2/plan

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

  1. POST /v2/plan?project_id=... — create the plan for the execution date.
  2. POST /v2/stops?plan_id=... (or POST /v2/stops/geocode) — push the day's orders.
  3. POST /v2/plan/{id}/optimize — let the Routal optimizer build the routes.
  4. 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
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

Query Parameters

project_id*string
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 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"
}
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