Routes

The route endpoints let you build and manage routes programmatically — create a route, update its settings, delete it, kick off optimization, and poll for the optimization result. Optimization runs asynchronously: you start it with one call and check the outcome with another.

Every endpoint on this page requires the x-api-token header. You can find your token in the app under Settings → Webhooks (the API Token field has a copy button). See Authentication for the full details on tokens and error responses.

All examples use the base URL https://teamapi.upperinc.com/api/v1 and return the standard envelope { "code": <int>, "message": "<string>", "data": <object|array> }.

Create a route

POST /api/v1/ext-create-route

Header: x-api-token: <your token>

Creates a new route. Defaults for optimization preference, units, pickup settings, and service time are pulled from your account settings when the corresponding field is omitted.

Parameters

Example request

curl -X POST "https://teamapi.upperinc.com/api/v1/ext-create-route" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "route_name": "Monday Deliveries",
    "route_date": "2026-06-29",
    "optimize_for": "time",
    "units": "miles",
    "pickup_settings": "auto",
    "service_time": 120
  }'

Example response

{
  "code": 200,
  "message": "Route created successfully.",
  "data": {
    "route_id": 18452,
    "route_name": "Monday Deliveries",
    "route_date": "2026-06-29",
    "optimize_for": "Time",
    "service_time": 120,
    "units": "Miles",
    "pickup_settings": "Auto"
  }
}

Update a route

POST /api/v1/ext-update-route

Header: x-api-token: <your token>

Updates settings on an existing route. Only the fields you include are changed; omitted fields are left as-is. route_id is required.

Parameters

Example request

curl -X POST "https://teamapi.upperinc.com/api/v1/ext-update-route" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "route_id": 18452,
    "route_name": "Monday Deliveries (Updated)",
    "optimize_for": "distance",
    "units": "km"
  }'

Example response

{
  "code": 200,
  "message": "Route updated successfully.",
  "data": {
    "route_id": 18452,
    "route_name": "Monday Deliveries (Updated)",
    "route_date": "2026-06-29",
    "optimize_for": "Distance",
    "service_time": 120,
    "units": "Kms",
    "pickup_settings": "Auto"
  }
}

Delete a route

POST /api/v1/ext-delete-route

Header: x-api-token: <your token>

Deletes a route. This is a soft delete — the route is marked deleted rather than permanently removed. route_id is required.

Parameters

Example request

curl -X POST "https://teamapi.upperinc.com/api/v1/ext-delete-route" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "route_id": 18452
  }'

Example response

{
  "code": 200,
  "message": "Route deleted successfully.",
  "data": {
    "route_id": 18452
  }
}

Optimize a route

POST /api/v1/ext-optimize-route

Header: x-api-token: <your token>

Starts optimization for a route. Before calling this, the route must have at least one stop and at least one assigned driver (use Assign drivers first) — optimizing a route with no driver assigned returns an error. Optimization runs asynchronously — this call queues the job and returns a pending status with a queue_id. Use Get optimization status to check when it finishes. If the route is already being optimized, the call returns the existing pending job instead of starting a new one. route_id is required.

Parameters

Example request

curl -X POST "https://teamapi.upperinc.com/api/v1/ext-optimize-route" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "route_id": 18452,
    "timezone": "America/New_York"
  }'

Example response

{
  "code": 200,
  "message": "Optimization started successfully.",
  "data": {
    "route_id": 18452,
    "status": "pending",
    "queue_id": "6657f1a2b9d3c40012ab34cd"
  }
}

Get optimization status

GET /api/v1/ext-optimization-status

Header: x-api-token: <your token>

Checks the current optimization state of a route. Poll this endpoint after starting an optimization to know when it has completed. route_id is required.

Parameters

The returned status is one of:

• optimized — optimization finished and the route is optimized.
• pending — optimization is still in progress.
• not_optimized — the route has not been optimized.

Example request

curl -X GET "https://teamapi.upperinc.com/api/v1/ext-optimization-status?route_id=18452" \
  -H "x-api-token: YOUR_API_TOKEN"

Example response

{
  "code": 200,
  "message": "Status fetched successfully.",
  "data": {
    "route_id": 18452,
    "route_name": "Monday Deliveries",
    "status": "optimized",
    "is_optimized": "Y",
    "queue_id": "6657f1a2b9d3c40012ab34cd"
  }
}

Related

• Authentication