API reference for creating, managing, dispatching, and optimizing daily routes and stops.

Routes API

The Routes API lets you manage daily routes, add and update stops, dispatch to drivers, optimize stop order, and track live progress. All endpoints require a valid JWT token.

List Routes

Retrieve routes with optional filters.

curl "https://api.nextroute.app/api/routes?date=2026-03-24&status=dispatched" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Description
`date`	string	Exact date (YYYY-MM-DD)
`date_from`	string	Start of date range
`date_to`	string	End of date range
`zone_id`	string	Filter by service zone
`driver_id`	string	Filter by assigned driver
`status`	string	Filter by status: `draft`, `dispatched`, `in_progress`, `completed`

Response (200):

{
  "data": [
    {
      "id": "rt_abc123",
      "name": "North Zone - Monday",
      "date": "2026-03-24",
      "status": "dispatched",
      "driver_id": "usr_drv001",
      "service_zone_id": "sz_north",
      "planned_stops_count": 28,
      "completed_stops_count": 0,
      "skipped_stops_count": 0,
      "optimized_distance_mi": 34.2,
      "optimized_duration_min": 185,
      "stop_count": 28
    }
  ]
}

Create Route

Create a new draft route.

curl -X POST https://api.nextroute.app/api/routes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-03-25",
    "name": "South Zone - Tuesday",
    "driver_id": "usr_drv002",
    "service_zone_id": "sz_south"
  }'

Request Body:

Field	Type	Required	Description
`date`	string	Yes	Route date (YYYY-MM-DD)
`name`	string	No	Route name (auto-generated if omitted)
`driver_id`	string	No	Assigned driver user ID
`service_zone_id`	string	No	Associated service zone

Response (201): Returns the created route object.

Get Route Details

Retrieve a single route with its stops.

curl https://api.nextroute.app/api/routes/rt_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Route

Update route metadata (name, driver, date, status, notes).

curl -X PUT https://api.nextroute.app/api/routes/rt_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "driver_id": "usr_drv003",
    "notes": "Cover for Mike today"
  }'

Delete Route

Delete a draft route. Returns an error if the route has been dispatched.

curl -X DELETE https://api.nextroute.app/api/routes/rt_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Stops

Add a Stop

Add a customer stop to a route.

curl -X POST https://api.nextroute.app/api/routes/rt_abc123/stops \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "property_id": "prop_xyz",
    "position": 5,
    "notes": "Ring doorbell on arrival"
  }'

Update a Stop

Update stop status, notes, or completion details. This is the primary endpoint used by the driver mobile app to mark stops as completed or skipped.

curl -X PUT https://api.nextroute.app/api/routes/rt_abc123/stops/stp_001 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "photo_url": "https://storage.example.com/photos/stp_001.jpg",
    "notes": "Left bins at curb"
  }'

Stop Statuses:

Status	Description
`pending`	Not yet visited
`in_progress`	Driver is at the stop
`completed`	Service completed (triggers auto-charge if configured)
`skipped`	Stop skipped with a reason

When a stop is marked completed, the system can automatically trigger per-service billing via the auto-charge system.

Remove a Stop

Remove a stop from a route.

curl -X DELETE https://api.nextroute.app/api/routes/rt_abc123/stops/stp_001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Dispatch

Dispatch a route to the assigned driver. This changes the route status to dispatched and sends a push notification to the driver's mobile app.

curl -X PUT https://api.nextroute.app/api/routes/rt_abc123/dispatch \
  -H "Authorization: Bearer YOUR_TOKEN"

The driver must be assigned before dispatching. The endpoint will return an error if no driver is set.

Reorder Stops

Manually reorder stops within a route by providing an array of stop IDs in the desired order.

curl -X PUT https://api.nextroute.app/api/routes/rt_abc123/reorder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stop_ids": ["stp_003", "stp_001", "stp_002", "stp_004"]
  }'

Optimize Route

Run route optimization to find the most efficient stop order. NextRoute supports multiple optimization strategies:

curl -X POST https://api.nextroute.app/api/routes/rt_abc123/optimize \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"strategy": "ai"}'

Optimization Strategies:

Strategy	Description
`nearest_neighbor`	Fast heuristic — visits the nearest unvisited stop each time
`ai`	AI-powered optimization using travel time matrices and historical data

The optimizer returns the optimized distance in miles, estimated duration in minutes, and reorders the stops automatically.

Live Route Tracking

Get real-time status for an active route, including the driver's last known position and per-stop completion status.

curl https://api.nextroute.app/api/routes/rt_abc123/live \
  -H "Authorization: Bearer YOUR_TOKEN"

Reschedule Route

Reschedule an entire route to a new date.

curl -X PUT https://api.nextroute.app/api/routes/rt_abc123/reschedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_date": "2026-03-26"}'

Auto-Reschedule

Automatically reschedule incomplete stops from a route to the next available date based on scheduling rules.

curl -X POST https://api.nextroute.app/api/routes/rt_abc123/auto-reschedule \
  -H "Authorization: Bearer YOUR_TOKEN"

Reschedule Individual Stop

Move a single stop from one route to another date.

curl -X POST https://api.nextroute.app/api/routes/reschedule-stop \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stop_id": "stp_001",
    "new_date": "2026-03-26",
    "reason": "Customer not home"
  }'

Route Lifecycle

A route progresses through these statuses:

Draft — route created, stops being added
Dispatched — sent to driver, visible in mobile app
In Progress — driver has started the route
Completed — all stops visited (completed or skipped)

Daily Routes — route concepts and data model
Route Generation — auto-generating routes from templates
Dispatching — dispatch workflow details
API Authentication — obtaining JWT tokens

Routes API

On this page