Update Trip Status (v2)
Once a trip is created, the default tripStatus is set to Planned and this is displayed in the Plan Trip API response. tripStatus is then monitored until the trip is completed.
The Update Trip Status API (v2) changes a trip status to one of five values. This version uses the same request and response format as the legacy Update Trip Status endpoint, but allows status changes on trips that are already Completed or Cancelled.
Use this endpoint to change the status or when you need to reopen a completed or cancelled trip.
POST /trip/tripStatus
Resource URL
https://tripmanagement.trimblemaps.com/api/trip/tripStatus
Request fields
| Field | Description | Type | Required |
|---|---|---|---|
tripId
| The alkTripId returned when you planned the trip. If no trip is found with the given alkTripId, an error message is returned. If tmsTripId is also supplied, alkTripId is ignored and the trip matching tmsTripId is updated instead.
|
integer | Yes, if tmsTripId is not supplied.
|
tmsTripId
| The tmsTripId of the previously generated route. If tripId is also supplied, it is ignored and only the trip matching tmsTripId is updated.
|
string | Yes, if tripId is not supplied.
|
status
| Status of the trip: 0 = Rejected, 1 = Accepted, 2 = Completed, 3 = Cancelled, 4 = Received.
|
integer | Yes |
timeStamp
| Timestamp when the trip status update was sent. Must be ISO-8601 date format. |
string | Yes |
loc
| The vehicle’s GPS coordinates at the time the status is changed or last known location. |
GPSCoords | Yes |
loc.coords
| Object containing GPS latitude and longitude. |
Coords object | Yes |
loc.coords.lat
| GPS latitude. Minimum 4 decimal digits required; 6 decimal digits desired. |
string | Yes |
loc.coords.lon
| GPS longitude. Minimum 4 decimal digits required; 6 decimal digits desired. |
string | Yes |
loc.speed
| Speed. |
integer | No |
loc.heading
| Heading. |
integer | No |
loc.altitude
| Altitude. |
integer | No |
loc.deviceDT
| Device time. Must be ISO-8601 date format. |
string | No |
Status values
| Status | Behavior |
|---|---|
Rejected
| The driver rejected this trip and the trip is not in an active state. |
Accepted
| The driver accepted this trip and the trip is now active. This sets tripStatus to InProgress.
|
Completed
| All open stops on the trip are completed. This sets tripStatus to Completed. A completed trip can be reopened by sending Accepted, or cancelled by sending Cancelled.
|
Cancelled
| This sets tripStatus to Cancelled. A cancelled trip can be reopened by sending Accepted, or completed by sending Completed.
|
Received
| Confirms that a trip was delivered to a device and a driver received it. It does not put the trip InProgress; that requires the additional Accepted step.
|
Rules: Deleted trips cannot be modified. A trip in
InProgress,Completed, orCancelledstate cannot be set toRejected.
Response fields
| Field | Description | Type |
|---|---|---|
success
| true or false.
|
boolean |
errorCode
| Numeric error code. If success is true, errorCode can be ignored. -1 = trip cannot be found. -3 = trip last modification happened after the request timestamp.
|
integer |
Sample request
{
"tripId": 12345,
"status": 1,
"timeStamp": "2026-03-20T15:00:42.624Z",
"loc": {
"coords": {
"lat": "42.364551",
"lon": "-71.180604"
}
}
}
Sample response
{
"success": true,
"errorCode": 0
}
Error conditions
| Field | Description | Type | Values |
|---|---|---|---|
ErrorType
| The type of error that occurred. |
string | ArgumentException — a required field was not supplied, an invalid value was passed, or an inappropriate action was attempted. Correct the error and try again.
|
Description
| Error message describing what occurred. |
string | Explains how to fix the error or what went wrong. |
ErrorCode
| Numerical error code, if applicable. |
integer |
ArgumentException examples
{
"ErrorType": "ArgumentException",
"Description": "Can't update trip status with timestamp older than trip last modified time",
"ErrorCode": null
}
{
"ErrorType": "ArgumentException",
"Description": "Cannot modify a deleted trip.",
"ErrorCode": null
}
{
"ErrorType": "ArgumentException",
"Description": "Can't reject (TripAction.Rejected) a trip that is 'InProgress'. TripId: 12345.",
"ErrorCode": null
}
{
"ErrorType": "ArgumentException",
"Description": "GPS position must not be null.",
"ErrorCode": null
}