Goal
Document the public Integration API v1 contract for operations teams connecting ERP, ecommerce, dispatch, analytics, or internal automation systems to Rouptimize.
Who it is for
Company admins, technical operations teams, and external system integrators.
Expected result
Your integration can read or update approved company-scoped resources, retry safely, and receive signed webhook events for operational changes.
Prerequisites
API access
Base path
/api/v1
All public integration routes are versioned under the Rouptimize Integration API v1 base path.
OpenAPI reference
/swagger
Use the live backend Swagger reference for schemas, request bodies, and response examples.
Token management
Settings > Rouptimize API
Company admins create scoped API tokens from the web panel. Raw tokens are shown only once.
Webhook management
Settings > Webhooks
Webhook endpoints and delivery history are managed from the web panel with signed JSON payloads.
| Token preset | Intended use |
|---|---|
| read_only | Read branches, drivers, missions, mobile users, routes, vehicle-driver assignments, vehicles, reports, and dashboard data. |
| full_access | Read and mutate supported operational resources for approved automation workflows. |
Authentication
Send API tokens as bearer credentials. Production tokens use the rpt_live_ prefix; non-production tokens use the rpt_test_ prefix.
Token safety
API tokens are company-scoped and never grant superadmin access. Rouptimize stores only hashed token material after the one-time reveal.
Errors
Public API errors return a stable envelope with code, message, details, and requestId. Log the requestId when opening a support case.
Idempotency
Mutating calls support Idempotency-Key. Replaying the same request returns the stored response; reusing a key with a different body returns 409.
External IDs
Create requests may include externalId so ERP, ecommerce, or dispatch systems can map their own records to Rouptimize resources safely.
Public endpoints
These endpoints are company-scoped and write through the same Rouptimize services used by the web panel and mobile app.
Account
Inspect the authenticated integration token and company context.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/me | Inspect token and company context. |
Branches
Create and manage operating branches used by dispatch and reporting.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/branches | List branches. |
| POST | /api/v1/branches | Create a branch. |
| GET | /api/v1/branches/:id | Get a branch. |
| PATCH | /api/v1/branches/:id | Update a branch. |
| DELETE | /api/v1/branches/:id | Delete a branch. |
Depots
Create and manage depot locations for route starts, ends, and operating context.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/depots | List depots. |
| POST | /api/v1/depots | Create a depot. |
| GET | /api/v1/depots/:id | Get a depot. |
| PATCH | /api/v1/depots/:id | Update a depot. |
| DELETE | /api/v1/depots/:id | Delete a depot. |
Fleet
Manage vehicles, drivers, mobile users, and vehicle-driver assignments.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/vehicles | List vehicles. |
| POST | /api/v1/vehicles | Create a vehicle. |
| GET | /api/v1/vehicles/:id | Get a vehicle. |
| PATCH | /api/v1/vehicles/:id | Update a vehicle. |
| DELETE | /api/v1/vehicles/:id | Delete a vehicle. |
| GET | /api/v1/drivers | List drivers. |
| POST | /api/v1/drivers | Create a driver. |
| GET | /api/v1/drivers/:id | Get a driver. |
| PATCH | /api/v1/drivers/:id | Update a driver. |
| DELETE | /api/v1/drivers/:id | Delete a driver. |
| POST | /api/v1/drivers/:id/invite | Invite a driver to the mobile app. |
| GET | /api/v1/drivers/:id/devices | List registered driver devices. |
| GET | /api/v1/mobile-users | List mobile users. |
| GET | /api/v1/mobile-users/:id | Get a mobile user. |
| PATCH | /api/v1/mobile-users/:id | Update a mobile user. |
| POST | /api/v1/mobile-users/:id/disable | Disable a mobile user. |
| POST | /api/v1/mobile-users/:id/enable | Enable a mobile user. |
| DELETE | /api/v1/mobile-users/:id | Delete a mobile user. |
| GET | /api/v1/vehicle-driver-assignments | List vehicle-driver assignments. |
| POST | /api/v1/vehicle-driver-assignments | Create a vehicle-driver assignment. |
| GET | /api/v1/vehicle-driver-assignments/:id | Get a vehicle-driver assignment. |
| PATCH | /api/v1/vehicle-driver-assignments/:id | Update a vehicle-driver assignment. |
| DELETE | /api/v1/vehicle-driver-assignments/:id | Delete a vehicle-driver assignment. |
Missions
Create, import, inspect, update, reassign, verify, and delete delivery missions.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/missions | List missions. |
| POST | /api/v1/missions | Create a mission. Trusted integrations may set autoGeocode to true to geocode missing pickup and delivery coordinates from addresses; the default is false. |
| POST | /api/v1/missions/bulk | Create multiple missions. |
| POST | /api/v1/missions/validate | Validate a mission create payload without creating a mission. |
| GET | /api/v1/missions/distribution-view | Read distribution-ready mission data. |
| GET | /api/v1/missions/export | Read export-style mission data. |
| POST | /api/v1/missions/plan-route | Preview mission route planning where supported. |
| GET | /api/v1/missions/:id | Get a mission. |
| GET | /api/v1/missions/:id/history-changes | Read mission history changes. |
| PATCH | /api/v1/missions/:id | Update a mission. |
| POST | /api/v1/missions/:id/reassign | Reassign a mission. |
| POST | /api/v1/missions/:id/proof-of-delivery/verify | Verify proof of delivery where rules allow it. |
| DELETE | /api/v1/missions/:id | Delete a mission. |
Routes
Plan, optimize, assign, reorder, inspect, and delete delivery routes.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/routes/plan | Preview route planning. |
| POST | /api/v1/routes/auto-optimize | Use DEFAULT_ROUTE_OPTIMIZATION_STRATEGY when optimizationStrategy is omitted; accept smart_zoning or legacy_vroom, return optional zoning metadata, and fall back to baseline VROOM when performance or quality guards reject the zoned result. Credits follow the existing consumption rules. |
| POST | /api/v1/routes | Create a route. |
| GET | /api/v1/routes | List routes. |
| GET | /api/v1/routes/:id | Get a route. |
| GET | /api/v1/routes/:id/timeline | Read route execution timeline from mission executions. |
| GET | /api/v1/routes/:id/navigation-geometry | Read route navigation geometry. |
| PUT | /api/v1/routes/:id/assign-driver | Assign a driver. |
| PUT | /api/v1/routes/:id/assign-vehicle | Assign a vehicle. |
| PUT | /api/v1/routes/:id/add-missions | Add missions to a route. |
| PUT | /api/v1/routes/:id/missions/order | Reorder missions on a route. |
| DELETE | /api/v1/routes/:id | Delete a route. |
Reports and dashboard
Read reporting and dashboard data for approved operational analytics use cases.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/reports/overview | Read report overview data. |
| GET | /api/v1/reports/details/:section | Read report details for a supported section. |
| GET | /api/v1/dashboard/stats | Read dashboard statistics. |
| GET | /api/v1/dashboard/recent-activity | Read recent dashboard activity. |
| GET | /api/v1/dashboard/charts | Read dashboard chart data. |
Settings endpoints
These authenticated company-admin endpoints support token management, webhook endpoint management, and delivery review inside Rouptimize settings.
Company settings
| Method | Path | Purpose |
|---|---|---|
| GET | /companies/me/api-tokens | List API tokens for the current company. |
| POST | /companies/me/api-tokens | Create a scoped API token. |
| DELETE | /companies/me/api-tokens/:id | Delete an API token. |
| GET | /companies/me/webhook-endpoints | List webhook endpoints. |
| POST | /companies/me/webhook-endpoints | Create a webhook endpoint. |
| PATCH | /companies/me/webhook-endpoints/:id | Update a webhook endpoint. |
| DELETE | /companies/me/webhook-endpoints/:id | Delete a webhook endpoint. |
| GET | /companies/me/webhook-endpoints/:id/deliveries | Review recent webhook deliveries. |
Webhooks
Rouptimize sends signed JSON payloads with event id, event type, timestamp, company id, resource type, resource id, and event data.
Signature header
X-Rouptimize-Signature: t=...,v1=...
mission.created
A mission was created.
mission.updated
A mission was updated.
mission.deleted
A mission was deleted.
mission.status_changed
A mission status changed.
route.created
A route was created.
route.optimized
A route was optimized.
route.assigned
A route was assigned.
route.reordered
A route stop order changed.
route.deleted
A route was deleted.
route.completed
A route was completed.
driver.created
A driver was created.
driver.updated
A driver was updated.
driver.deleted
A driver was deleted.
vehicle.created
A vehicle was created.
vehicle.updated
A vehicle was updated.
vehicle.deleted
A vehicle was deleted.
vehicle_driver_assignment.created
A vehicle-driver assignment was created.
vehicle_driver_assignment.updated
A vehicle-driver assignment was updated.
vehicle_driver_assignment.deleted
A vehicle-driver assignment was deleted.
Operational notes
Tenant isolation is enforced through the existing Rouptimize company context and database access policies.
Public controllers write through existing Rouptimize domain services instead of duplicating mission, route, assignment, credit, or proof-of-delivery logic.
Records created or changed through /api/v1 are the same records used by the web app and mobile app.
Internal-only surfaces such as login, refresh, billing, Stripe, support tickets, backoffice, in-app notifications, and company registration are excluded from the public API.
Production environments must have token hashing and webhook signing configured before creating API tokens or enabling webhook delivery.
Steps
01
Create a scoped API token
Company admins create tokens from Settings > Rouptimize API. Use read_only for reporting or synchronization and full_access only for approved workflows that mutate operational resources.
02
Authenticate requests
Send tokens as bearer credentials in the Authorization header. Production tokens use the rpt_live_ prefix and non-production tokens use the rpt_test_ prefix.
03
Use the versioned endpoint surface
Public integration endpoints are versioned under /api/v1 and write through the same Rouptimize services used by the web and mobile apps.
04
Retry mutating calls safely
Send Idempotency-Key on create, update, assignment, optimization, and reorder calls that may be retried by the external system.
05
Map external records
Create requests may include externalId so source systems can map orders, jobs, vehicles, drivers, and route work back to their own records.
06
Subscribe to signed webhook events
Create webhook endpoints from Settings > Webhooks, verify the X-Rouptimize-Signature header, and review recent deliveries from the web panel.
Field definitions
Troubleshooting
401 or 403 responses usually mean the token is missing, expired, scoped incorrectly, or belongs to a different company.
409 idempotency responses mean the same key was reused with a different request body.
Webhook verification failures usually mean the receiver is not validating the timestamped signature with the configured endpoint secret.
Missing imported records usually mean the externalId, branch, date, or required operational fields do not match the expected workflow.
Related product pages
Related tutorials
Need to try it with your own route data?