# Routal API Developers

> Routal is a route-optimization and last-mile delivery platform. The Routal API lets you create and manage plans, stops, routes, and vehicles programmatically, track deliveries in real time, and retrieve proof of delivery. All requests are authenticated with a `private_key` query parameter.

## Overview

- [Landing page](https://developers.routal.com/): Quickstart, API key setup, and code samples (cURL, JavaScript, Python).
- [OpenAPI spec (JSON)](https://developers.routal.com/openapi.json): Machine-readable OpenAPI 3.0 specification.
- [Full markdown reference](https://developers.routal.com/llms-full.txt): Every endpoint and schema as a single markdown document.

## API Reference

- [Authentication](https://developers.routal.com/docs/authentication): How API keys work in Routal — where to issue them, how to deactivate them, and how to keep them safe.
- [Build with AI](https://developers.routal.com/docs/build-with-ai): Wire Routal into your AI coding assistant — Cursor, Claude Code, ChatGPT, Gemini, Copilot — so it generates correct Routal code on the first try.
- [Changelog](https://developers.routal.com/docs/changelog): Notable changes to the Routal API and the developer portal. Subscribe to the RSS feed to track every release.
- [Errors](https://developers.routal.com/docs/errors): HTTP status codes, the error envelope, and the machine codes Routal returns.
- [Idempotency](https://developers.routal.com/docs/idempotency): How to make your integration safe to retry — using external_id and webhook deduplication.
- [Welcome](https://developers.routal.com/docs): The Routal API automates route planning, dispatching, and proof of delivery — all through a single REST/JSON interface.
- [Resource lifecycle](https://developers.routal.com/docs/lifecycle): The states a Plan, Route, and Stop move through, and which transitions are automatic.
- [Pagination](https://developers.routal.com/docs/pagination): How list endpoints page their results — offset, limit, and the response envelope.
- [Quickstart](https://developers.routal.com/docs/quickstart): Make your first authenticated call to the Routal API in under five minutes.
- [Rate limits](https://developers.routal.com/docs/rate-limits): Routal's request quota, what happens when you exceed it, and recommended client patterns.
- [Webhooks](https://developers.routal.com/docs/webhooks): Subscribe your endpoint to plan, route, and stop lifecycle events. Routal pushes them as they happen.
- [Capacitated distribution](https://developers.routal.com/docs/recipes/capacitated-distribution): When weight, volume, cold chain, or specialist equipment are non-negotiable. The optimizer respects every constraint you declare; the cost of not declaring them is a truck that gets to the third stop, runs out of room, and has to come back to the depot. This recipe walks the constraint matrix and the operational patterns for cold chain, oversized loads, and mixed fleets.
- [Field service with appointments](https://developers.routal.com/docs/recipes/field-service-with-appointments): For mobile workforces — technicians, installers, home health, equipment maintenance. The unit of work is a service appointment, not a delivery. This recipe covers skill matching, tight appointment windows, multi-task checklists, and how to keep the customer-facing ticket in sync with what the technician did on site.
- [Grocery — same-day delivery](https://developers.routal.com/docs/recipes/grocery-same-day): Dark store and grocery e-commerce — the customer ordered 90 minutes ago and expects the doorbell to ring inside a two-hour window. Orders land continuously, the integration micro-batches them into short waves, the optimizer slots each wave onto active vehicles, and the customers app sends arrival ETAs as the driver gets close. This recipe covers the wave cadence, the cold-chain stop shape, and the rate-control patterns that keep dispatchers ahead of the order book.
- [Recipes](https://developers.routal.com/docs/recipes): Complete, runnable integration walkthroughs — one per common operation rhythm.
- [Last-mile e-commerce](https://developers.routal.com/docs/recipes/last-mile-ecommerce): B2C parcel delivery — orders flow from your OMS or WMS into Routal throughout the day, the optimizer batches them into dense neighborhood routes, drivers execute with barcode-scan tasks, and customers get tracking links automatically. This recipe covers the OMS→Routal→customer notification loop and the high-density stop patterns specific to parcel logistics.
- [Nightly batch — B2B distribution](https://developers.routal.com/docs/recipes/nightly-batch-b2b): The default mode for B2B distributors. Orders close yesterday at 18:00, optimization runs overnight, the fleet rolls out at dawn. This recipe walks the full nightly job — when to fire it, how to make it idempotent against a daily cron, and how to recover when something misses the window.
- [Nightly batch + live dispatch](https://developers.routal.com/docs/recipes/nightly-batch-plus-live-dispatch): Most of the work is the nightly batch — but new orders keep arriving during operations and have to be slotted into routes that already left the depot. This recipe covers the architectural decision of where to slot, the three optimizer strategies that are safe with drivers already on the road, and the operational patterns that keep dispatcher panic to a minimum.
- [Recurring services — calendar-driven dispatch](https://developers.routal.com/docs/recipes/recurring-services): Operations that run on a calendar, not an order book. Bulk gas refills, ITV inspections, elevator maintenance, water cooler service, pest control. The same customer is visited every N weeks at roughly the same time slot, and the value the customer pays for is the reliability of the schedule. This recipe covers schedule-to-Routal materialisation, customer-stable time slots, and the deviation patterns that keep recurring routes honest.
- [Reverse logistics — pickups & returns](https://developers.routal.com/docs/recipes/reverse-logistics): Distributors and retailers that don't just deliver — they pick up. Empty kegs from bars, empty pallets from supermarkets, returned items from customers, malfunctioning equipment from clients. This recipe covers pure pickup routes, mixed delivery+pickup routes via Routal's chain mechanic, and the operational patterns that prevent drivers from showing up to "pick up" stops the customer never agreed to.
- [Delete a route](https://developers.routal.com/docs/route/deleteV2RouteId): Deletes the route from its plan.
- [Retrieve a route](https://developers.routal.com/docs/route/getV2RouteId): Returns a route with its ordered stops, assigned vehicle, total distance, total duration and ETAs.
- [Dispatch a route to its driver](https://developers.routal.com/docs/route/postV2RouteIdDispatch): 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.
- [Optimize the stop sequence of a single route](https://developers.routal.com/docs/route/postV2RouteIdOptimize): Runs the Routal optimizer over the stops already assigned to this route, keeping the vehicle assignment fixed.
- [Create multiple routes](https://developers.routal.com/docs/route/postV2Routes): Creates multiple routes in a plan in a single request.
- [Update a route](https://developers.routal.com/docs/route/putV2RouteId): Updates route-level attributes such as status, assigned vehicle / driver, label and constraints.
- [Reorder the stops of a route](https://developers.routal.com/docs/route/putV2RouteIdStops): Sets the ordered list of stop IDs for this route.
- [Delete a plan](https://developers.routal.com/docs/plan/deleteV2PlanId): Deletes the plan together with all its routes and stops.
- [Retrieve a plan](https://developers.routal.com/docs/plan/getV2PlanId): Returns the full plan, including its routes, stops, vehicles and metadata.
- [List routes of a plan](https://developers.routal.com/docs/plan/getV2PlanIdRoutes): Returns every route in the plan, each containing its ordered list of stops, the assigned vehicle, total distance, total duration and estimated arrival times.
- [List stops of a plan](https://developers.routal.com/docs/plan/getV2PlanIdStops): Returns every stop that belongs to the plan along with its execution payload — each stop includes its tasks, custom fields, timestamps and any reports captured…
- [List plans](https://developers.routal.com/docs/plan/getV2Plans): Returns a paginated list of plans for a project, optionally filtered by date range, status or label.
- [Create a plan](https://developers.routal.com/docs/plan/postV2Plan): Creates a new plan inside the given project.
- [Optimize a plan](https://developers.routal.com/docs/plan/postV2PlanIdOptimize): Triggers the Routal optimizer for this plan.
- [Update a plan](https://developers.routal.com/docs/plan/putV2PlanId): Updates plan-level attributes such as label, execution date, status or optimizer configuration.
- [Retrieve a stop](https://developers.routal.com/docs/stop/getV2StopStop_id): Returns a stop with its full execution payload: tasks, status, time windows, customer details, geocoded location, proof of delivery (signature, photos, scans),…
- [Move stops between plans](https://developers.routal.com/docs/stop/postV2StopMove): Moves one or more stops to a different plan.
- [Create multiple stops](https://developers.routal.com/docs/stop/postV2Stops): Bulk-creates stops with already known coordinates.
- [Create stops with automatic geocoding](https://developers.routal.com/docs/stop/postV2StopsGeocode): Bulk-creates stops from free-text addresses.
- [Search stops with rich filters](https://developers.routal.com/docs/stop/postV2StopsSearch): Searches stops across plans within a project, with full-text, status, date-range, label, customer, supervisor and custom-field filters.
- [Update a stop](https://developers.routal.com/docs/stop/putV2StopStop_id): Updates a stop.
- [Delete multiple stops](https://developers.routal.com/docs/stop/putV2StopsDelete): Deletes the given stops in a single request.
- [Delete a task](https://developers.routal.com/docs/task/deleteV2TaskTask_id): Removes a task from a stop.
- [Create a task on a stop](https://developers.routal.com/docs/task/postV2Task): Attaches a new task to an existing stop.
- [Update a task](https://developers.routal.com/docs/task/putV2TaskTask_id): Updates a task on a stop — its label, comments, barcode, customfields or status.
- [Retrieve a vehicle](https://developers.routal.com/docs/vehicle/getV2VehicleVehicle_id): Returns the full vehicle profile: capacity (weight / volume / units), skills, working hours, break windows, start / end locations, transport mode, driver assig…
- [List and search vehicles](https://developers.routal.com/docs/vehicle/getV2Vehicles): Returns a paginated, sortable list of the vehicles available in a project.
- [Create multiple vehicles (v3)](https://developers.routal.com/docs/vehicle/postV3Vehicles): Bulk-creates vehicles in a project.
- [Update a vehicle](https://developers.routal.com/docs/vehicle/putV2VehicleVehicle_id): Updates the vehicle profile — capacity, skills, working hours, breaks, start / end locations, assigned driver and traffic options.