Drivers
List your drivers, assign them to a route, and share the route to their mobile app over the Upper API.
These endpoints let you work with drivers programmatically: fetch the drivers on your team, assign one or more of them to a route, and push (or schedule) the route to their mobile app. They build on the route endpoints — list your drivers first, assign them to a route, then share it for dispatch.
Every request must include your API token in the x-api-token header. You can find your token in the app under Settings → Webhooks (the API Token field, with a copy button). See Authentication for details on tokens and the standard response envelope.
All endpoints return the standard envelope: { "code": <int>, "message": "<string>", "data": <object|array> }. A missing token returns HTTP 400 { "code": 400, "message": "Token is required.", "data": [] }, and an invalid token returns HTTP 401 { "message": "User not found." }.
List drivers
Returns all active drivers on your team.
GET /api/v1/ext-get-drivers
Header: x-api-token: <your token>
Parameters
No parameters. The drivers returned are scoped to the team that owns the API token.
Example request
curl -X GET "https://teamapi.upperinc.com/api/v1/ext-get-drivers" \
-H "x-api-token: YOUR_API_TOKEN"Example response
{
"code": 200,
"message": "Drivers fetched successfully.",
"data": [
{
"id": 1042,
"name": "Jordan Smith",
"email": "jordan.smith@example.com",
"phone": "+1 555 0142",
"v_company_logo_thumb": null,
"v_image_thumb": null
},
{
"id": 1043,
"name": "Alex Lee",
"email": "alex.lee@example.com",
"phone": "+1 555 0177",
"v_company_logo_thumb": null,
"v_image_thumb": null
}
]
}Each driver object contains id, name, email, and phone. Use the id values as the driver_ids for the assign and share endpoints below.
Assign drivers to a route
Assigns one or more drivers to an existing route. This sets up each driver on the route (including their depot Start/End locations) and updates the route's selected drivers and driver count.
POST /api/v1/ext-assign-drivers
Header: x-api-token: <your token>
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
route_id | integer | Yes | ID of the route to assign drivers to. The route must belong to your team. |
driver_ids | array or comma-separated string | Yes | Driver IDs to assign. Accepts either a JSON array (for example [1042, 1043]) or a comma-separated string (for example "1042,1043"). Every ID must be an active driver on your team. |
If any of the supplied driver IDs are not active members of your team, the request fails with a message listing the invalid ID(s): "Invalid driver ID(s): <id>. Driver(s) not found in your team."
Example request
curl -X POST "https://teamapi.upperinc.com/api/v1/ext-assign-drivers" \
-H "x-api-token: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"route_id": 502,
"driver_ids": [1042, 1043]
}'Example response
{
"code": 200,
"message": "Drivers assigned successfully.",
"data": {
"route_id": 502,
"driver_ids": "1042,1043",
"driver_count": 2,
"needs_optimization": true
}
}needs_optimization is true when the assigned drivers changed on a route that was already optimized — in that case the route is reset to unoptimized and you should re-run optimization before sharing. See Routes for the optimization endpoints.
Share a route to drivers
Pushes a route to the assigned drivers' mobile app. You can send the notification immediately or schedule it relative to each driver's shift. If you omit driver_ids, the route's currently assigned drivers are used.
POST /api/v1/ext-share-to-driver
Header: x-api-token: <your token>
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
route_id | integer | Yes | ID of the route to share. The route must belong to your team. |
driver_ids | array or comma-separated string | No | Driver IDs to notify. Accepts a JSON array or a comma-separated string. If omitted, all drivers currently assigned to the route are used. Every supplied ID must be an active driver on your team. |
schedule_duration | string | No | Controls when the notification is sent. "0" (default) sends immediately. Other values schedule the notification (for example, minutes before the shift, or a custom time used with schedule_at). |
schedule_at | string | No | Specific date/time to send the notification when using a custom schedule_duration. If not provided, the driver's route date and shift start time are used. |
timezone | string | No | Timezone used when computing the scheduled send time. Defaults to the application timezone. |
The exact accepted values for schedule_duration (beyond "0" for immediate send) and the expected format of schedule_at are pending confirmation.
Example request
curl -X POST "https://teamapi.upperinc.com/api/v1/ext-share-to-driver" \
-H "x-api-token: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"route_id": 502,
"driver_ids": [1042, 1043],
"schedule_duration": "0",
"timezone": "America/New_York"
}'Example response
{
"code": 200,
"message": "Route shared to drivers successfully.",
"data": {
"route_id": 502,
"route_name": "Route Plan - 502",
"drivers_notified": [
{
"id": 1042,
"v_name": "Jordan Smith",
"v_email": "jordan.smith@example.com",
"v_company_logo_thumb": null,
"v_image_thumb": null
},
{
"id": 1043,
"v_name": "Alex Lee",
"v_email": "alex.lee@example.com",
"v_company_logo_thumb": null,
"v_image_thumb": null
}
],
"schedule_duration": "0",
"sent_immediately": true
}
}When schedule_duration is "0", the message is "Route shared to drivers successfully." and sent_immediately is true. For a scheduled send, the message is "Route notification scheduled successfully." and sent_immediately is false.
A route with no drivers assigned returns HTTP 400 { "code": 400, "message": "No drivers assigned to this route.", "data": [] }. Assign drivers first, or pass driver_ids explicitly.