API reference for master routes — list, create, manage stops, approve pending stops, reorder, optimize, generate daily routes, and clone templates.

Route Templates API

Route templates (also called master routes) define which properties to service, in what order, and at what frequency. Daily routes are generated from these templates. All endpoints require a valid JWT token.

List Templates

Retrieve all templates with stop counts and zone metadata.

curl "https://api.nextroute.app/api/route-templates?active=true&zone_id=zone_central" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Description
`zone_id`	string	Filter by service zone
`active`	string	Only active templates (`true`)

Response (200):

{
  "data": [
    {
      "id": "rt_abc123",
      "name": "Central Austin - Monday",
      "service_zone_id": "zone_central",
      "zone_name": "Central Austin",
      "zone_color": "#3B82F6",
      "day_of_week": "Monday",
      "default_driver_id": "usr_driver1",
      "is_active": 1,
      "max_stops": 60,
      "stop_count": 45,
      "pending_count": 3
    }
  ]
}

stop_count is the number of approved, active stops. pending_count is the number of stops awaiting approval.

Get Template with Stops

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

Returns the template plus an array of stops, each containing customer name, phone, billing status, property address, coordinates, bin details, sequence, frequency, week parity, service plan, and approval status.

Create a Template

curl -X POST "https://api.nextroute.app/api/route-templates" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_zone_id": "zone_central",
    "name": "Central Austin - Wednesday",
    "default_driver_id": "usr_driver1",
    "day_of_week": "Wednesday",
    "max_stops": 50
  }'

service_zone_id is required. Optional fields: name, default_driver_id, default_vehicle_id, day_of_week, max_stops.

Update a Template

curl -X PUT "https://api.nextroute.app/api/route-templates/rt_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Central Austin - Monday AM", "max_stops": 60 }'

Updatable fields: name, default_driver_id, default_vehicle_id, is_active, notes, day_of_week, max_stops.

Add a Stop

Adds a property at the end of the sequence. Frequency is inherited from the property's service plan.

curl -X POST "https://api.nextroute.app/api/route-templates/rt_abc123/stops" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "property_id": "prop_new456", "week_parity": "A" }'

Field	Type	Required	Description
`property_id`	string	Yes	Property to add
`week_parity`	string	No	`A`, `B`, or `every` (biweekly plans)
`month_week`	string	No	`1st`, `2nd`, `3rd`, `4th`, `last` (monthly plans)

Returns 409 if the property is already on this template.

Remove a Stop

Soft-deletes the stop (is_active = 0). Use DELETE /api/route-templates/:id/stops/:stopId.

Approve / Reject Stops

Stops from enrollment or field sales may need approval before appearing on generated routes.

# Approve one stop
curl -X PUT ".../route-templates/rt_abc123/stops/rts_001/approve" -H "Authorization: Bearer YOUR_TOKEN"
# Reject (deactivate) one stop
curl -X PUT ".../route-templates/rt_abc123/stops/rts_001/reject" -H "Authorization: Bearer YOUR_TOKEN"
# Approve all pending stops at once
curl -X POST ".../route-templates/rt_abc123/approve-all" -H "Authorization: Bearer YOUR_TOKEN"

The approve-all response includes the count: { "success": true, "approved": 3 }.

Reorder Stops

Batch-update sequence numbers.

curl -X PUT "https://api.nextroute.app/api/route-templates/rt_abc123/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stops": [
      { "id": "rts_003", "sequence": 1 },
      { "id": "rts_001", "sequence": 2 }
    ]
  }'

Batch Add Stops

Add multiple properties at once. All are added as weekly frequency with approved status.

curl -X POST "https://api.nextroute.app/api/route-templates/rt_abc123/add-batch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "property_ids": ["prop_001", "prop_002", "prop_003"] }'

Optimize Stop Order

Reorder stops using the Mapbox Optimization API to minimize driving distance. Falls back to nearest-neighbor if Mapbox is unavailable. Requires at least 3 geocoded stops.

curl -X POST "https://api.nextroute.app/api/route-templates/rt_abc123/optimize" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "depot_lat": 30.2500, "depot_lng": -97.7500 }'

Response (200):

{ "success": true, "distance_mi": 18.4, "duration_min": 42.3, "stops_reordered": 45 }

Generate a Daily Route

Generate a concrete daily route from this template for a specific date. The engine applies frequency filtering, blackout dates, vacation holds, and skip policies.

curl -X POST "https://api.nextroute.app/api/route-templates/rt_abc123/generate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-03-25" }'

Returns { "route": null, "message": "..." } if the route already exists or no stops are due.

Clone a Template

Duplicate a template with all its stops.

curl -X POST "https://api.nextroute.app/api/route-templates/rt_abc123/clone" \
  -H "Authorization: Bearer YOUR_TOKEN"

{ "id": "rt_new456", "name": "Central Austin - Monday (Copy)", "stops_count": 45 }

Delete / Restore

Soft-delete with DELETE /api/route-templates/:id. Restore with PUT /api/route-templates/:id/restore.

Available Customers

List customers in the zone not yet on this template: GET /api/route-templates/:id/available-customers. Useful for the bulk-add flow.

Master Routes -- conceptual overview of templates
Route Generation -- how daily routes are built from templates
Routes API -- managing the generated daily routes
Properties API -- the properties that feed into template stops

Route Templates API

On this page