Circuit API
Circuit (now Spoke Dispatch) is a last-mile delivery management platform that gives dispatchers route planning and optimization and gives drivers a mobile app for navigation, proof of delivery, and recipient notifications. An API lets you programmatically create and optimize delivery plans, import and manage stops, assign drivers and depots, retrieve optimized routes and ETAs, and subscribe to webhooks for live route and stop events.
What is Circuit?
Circuit (now branded Spoke Dispatch) is a last-mile delivery management platform that helps courier and delivery teams plan multi-stop routes, optimize them, and track drivers in real time. Dispatchers work in a browser-based planning interface to build and optimize routes, assign stops to drivers, and monitor live progress, while drivers use a mobile app for turn-by-turn navigation, proof of delivery, and status updates. Recipients receive text or email tracking links and dynamic delivery-window notifications, reducing "where is my order?" support calls.
Core capabilities include:
- Route planning and optimization (Plans, Stops, optimized Routes with ETAs, distance, and stop order)
- Driver dispatch and management (driver records, depot assignments, route overrides, live tracking)
- Proof of delivery (photos, signatures, delivery notes, timestamped records for dispute resolution)
- Recipient notifications (tracking links, fixed and dynamic delivery windows, delay and arrival alerts)
- Live Plans and Live Stops for editing already-optimized, distributed plans on the day of delivery
Common data entities:
- Plans, Stops, Unassigned Stops, Live Plans, Live Stops
- Routes (with ETA, travel distance, travel duration, stop order)
- Drivers, Depots
- Operations (long-running optimization and distribution jobs), Webhooks
The Circuit Integration Challenge
Circuit publishes a public REST API, but building a resilient production integration on top of last-mile delivery workflows still involves real friction:
- Asynchronous optimization: Plans must be optimized and distributed before ETAs, route order, and distances exist—integrations have to poll Operations or handle webhooks rather than read results synchronously
- Tiered rate limits: Write endpoints, driver creation, batch imports, and optimization each have distinct per-second and per-minute limits that require careful backoff and queueing
- Live-day mutations: Editing stops after a plan is distributed requires the separate Live Plans and Live Stops surfaces, with different semantics from pre-optimization stops
- Mobile-only signals: Proof of delivery, live driver location, and completion states originate in the driver mobile app and surface through routes rather than a simple data export
- Rebrand drift: The product is migrating from Circuit (getcircuit.com) to Spoke (spoke.com), so base URLs, console links, and docs shift across the transition
- Pagination and consistency: List endpoints page through nextPageToken, and stop/route state changes as drivers progress, so syncs must reconcile against a moving target
How Supergood Creates Circuit APIs
Supergood wraps Circuit's public API and authenticated app surfaces in a resilient, normalized integration layer so you can build delivery automation without managing the optimization lifecycle, rate-limit tiers, and live-day edge cases yourself.
- Manages API key authentication (Basic and Bearer) with secure credential storage and rotation
- Orchestrates async optimize/distribute Operations and exposes completed Routes, ETAs, and stop order as ready-to-use results
- Respects tiered rate limits with adaptive throttling, batching, and exponential backoff on 429s
- Normalizes Plans, Stops, Routes, Drivers, and Depots into consistent objects across the Circuit-to-Spoke rebrand
Use Circuit with AI agents: Circuit MCP Server →
Getting Started
- Schedule Integration Assessment
Book a 30-minute session to confirm your delivery workflows, plan volume, and proof-of-delivery requirements.
- Supergood Generates and Validates Your API
We deliver a production-ready Circuit adapter covering plans, stops, routes, drivers, and webhooks tuned to your account.
- Deploy with Monitoring
Go live with continuous monitoring and automatic adaptation as Circuit migrates to Spoke and the API evolves.
API Endpoints
Authentication
/authenticateAuthenticate with a Circuit API key using Basic or Bearer auth and establish a session for downstream calls.
Plans
/plansList delivery plans with filters for date and status, including drivers and optimization state.
Plans
/create_planCreate a delivery plan for a specific day, then optimize and distribute it to assigned drivers.
Stops
/import_stopsBatch import stops into a plan with addresses, time windows, and delivery details (up to 1,000 stops per minute).
Routes
/routesRetrieve optimized routes for a plan with per-stop ETA, travel distance, travel duration, and stop order.
Drivers
/driversList drivers with depot assignments, route overrides, and availability for dispatch.
Use Cases
Automate plan creation and route optimization
- Create daily delivery plans and batch-import stops from your OMS or WMS - Trigger optimization and distribution, then poll Operations or webhooks for completion - Pull back optimized routes with ETAs, stop order, and travel distance for downstream systems
Sync delivery status and proof of delivery
- Stream stop completion, photos, signatures, and delivery notes into your records - Reconcile timestamped proof-of-delivery against orders for dispute resolution - Push exception and failed-delivery events to support and retention workflows
Power recipient tracking and notifications
- Surface live driver location and dynamic delivery windows to customer-facing tracking pages - Trigger arrival and delay alerts from route progress - Reduce WISMO contacts by feeding real-time ETAs into your notification stack
Manage drivers and depots programmatically
- Provision and update driver records and depot assignments in bulk - Apply route overrides and rebalance stops across drivers on the day of delivery - Keep driver rosters in sync with your HR and scheduling systems
Technical Specifications
Authentication
Circuit API key via Basic auth (apiKey:empty, base64) or Bearer token, managed in a secure session
Connectivity
Circuit/Spoke public REST API (base https://api.getcircuit.com/public/v0.2b) plus authenticated app surfaces
Response format
Normalized JSON across Plans, Stops, Routes, Drivers, and Depots with Content-type application/json on writes
Rate limits
Adaptive throttling tuned to Circuit's tiers: 10 reads/sec, 5 writes/sec, 3 optimizations/min, batch imports per minute
Session management
Automatic API key handling, credential rotation, and retry of expired or throttled requests
Data freshness
Near real-time route, stop, and driver-location updates with optional scheduled batch syncs
Security
Encrypted credential vault, scoped access, SOC 2-aligned controls, and audit logging
Webhooks
Subscribe to Spoke webhook events for route, stop, and delivery status changes
Latency
Sub-second reads on cached entities; async optimization handled via Operations polling and callbacks
Throughput
Horizontally scaled workers sized to high-volume daily plans, stop imports, and driver rosters
Reliability
Exponential backoff on 429s, idempotent retries, and pagination via nextPageToken
Adaptation
Continuous monitoring of the Circuit-to-Spoke rebrand, API version changes, and endpoint drift
Frequently asked questions
Yes. Circuit (now Spoke Dispatch) publishes a public REST API (v0.2b) for plans, stops, routes, drivers, depots, and webhooks. Supergood wraps it with normalization, async-optimization orchestration, and rate-limit handling so you integrate once against stable objects.
Stops only gain ETA, travel distance, duration, and stop order after a plan is optimized and becomes a Route. Supergood orchestrates the async optimize and distribute Operations and exposes completed routes so you do not have to poll the lifecycle yourself.
Circuit enforces tiered limits (10 reads/sec, 5 writes/sec, slower driver creation and optimization, and per-minute batch import caps). Supergood applies adaptive throttling, batching, and exponential backoff on 429 responses to stay within them.
Yes. Circuit exposes Live Plans and Live Stops for adding, updating, and deleting stops on an already-optimized, distributed plan. Supergood routes day-of changes through these surfaces with consistent semantics.
No. Supergood normalizes across the Circuit (getcircuit.com) and Spoke (spoke.com) surfaces and monitors base-URL, console, and docs changes, so your integration keeps working through the transition.