Create and Modify Drivers
Contents
Add Drivers
POST /drivers
Adds drivers to the fleet account. There is a limit of adding up to 50 drivers per API call.
Each driver has a Driver ID (identifier) and a Driver Name. Driver ID and Drive Name are required to be unique within the fleet account.
Note:
- If a Driver ID and Driver Name combination already exists in the fleet account and
- If the same Driver ID and Driver Name is sent in the request, then the request will be ignored with an appropriate message indicating that duplicate records were not added.
- If the Driver ID is same but Driver Name is different, then in the response, an appropriate message is returned indicating that duplicate records were not added.
Names and Ids can only include the following characters: A-Za-z0-9-_=+*#! .,()`~?.
Request
Authorization: bearer {token}
| Name | Description | Data Type |
|---|---|---|
driverId
| External driver identifier—must be unique within the fleet account |
Alphanumeric |
Name
| External driver name—must be unique within the fleet account |
Alphanumeric |
Response
| Name | Description | Data Type |
|---|---|---|
Id
| Unique, system-generated identifier for unique driver |
Int |
Name
| Driver Name that was added into the fleet account |
Alphanumeric |
driverId
| Driver Id that was added into the fleet account |
Alphanumeric |
ModifiedOn
| Indicates the last time the vehicle was modified |
DateTime |
Sample Request
[
{
"driverId": "drv1",
"Name": "driver 1"
},
{
"driverId": "drv2",
"Name": "driver 2"
}
]
Sample Response
{
"error": {
"message": "The request finished without adding duplicate driverIds",
"code": -12,
"duplicate_ids": ["drv1"]
},
"data": [
{
"Id": 337318,
"Name": "driver 2",
"DriverId": "drv2",
"ModifiedOn": "2019-03-29T14:19:17.34"
}
]
}
Error Codes
| Message | Description |
|---|---|
| The request finished without adding duplicate driverIds | This error is thrown when driverIds already exist within the account |
Update Drivers
PUT /drivers
Updates a Driver Name that is associated with a specific Driver ID in the account. The Name must be unique within the fleet.
Request
Authorization: bearer {token}
| Name | Description | Data Type |
|---|---|---|
driverId
| External Driver Identifier |
Alphanumeric |
Name
| External Driver Name |
Alphanumeric |
Response
| Name | Description | Data Type |
|---|---|---|
Id
| Unique system generated identifier for unique driver. |
Int |
Name
| Driver Name that was updated. |
Alphanumeric |
DriverId
| Driver Id of the driver that was updated. |
Alphanumeric |
ModifiedOn
| Indicates the last time the driver was modified. |
DateTime |
Sample Request
[
{
"driverId": "drv1",
"Name": "driver 1"
},
{
"driverId": "drv3",
"Name": "driver 3"
}
]
Sample Response
{
"error": {
"message": "The request finished without updating non-existent drivers",
"code": -11,
"ids_not_found": ["drv3"]
},
"data": [
{
"Id": 337316,
"Name": "driver 1",
"DriverId": "drv1",
"ModifiedOn": "2019-03-29T14:15:49.577"
}
]
}
Error Codes
| Message | Description |
|---|---|
| The request finished without updating non-existent drivers | This error is thrown when driversIds do not exist within the account. |
Get a List of Drivers
GET /drivers
Gets a list of Driver IDs and Driver Names from an account. By default, the first 20 drivers in the account will be populated. Set the limit parameter to retrieve as many drivers as necessary.
Request
Authorization: bearer {token}
| Name | Description | Data Type |
|---|---|---|
offset
| Pagination parameter indicating the cursor position to begin with in the response for this request |
Alphanumeric |
limit
| Pagination parameter indicating the number of results to return in the response for this request |
Int |
sortExpression
| The parameter based on which sorting should be performed. Pass either driverId or driverName.
|
string |
sortDirection
| Sort the results in ascending or descending order. Pass either ASC or DESC.
|
string |
Response
| Name | Description | Data Type |
|---|---|---|
href
| Request URL |
string |
offset
| Pagination parameter indicating the cursor position at which the response begins |
Int |
limit
| Pagination parameter indicating the number of results in the response |
Int |
size
| Pagination parameter indicating the total number of pages that are available in the response |
Int |
first
| Pagination parameter with a link to get the first page of the results in the response |
string |
next
| Pagination parameter with a link to get the next page of the results in the response |
string |
previous
| Pagination parameter with a link to get the previous page of the results in the response |
string |
last
| Pagination parameter with a link to get the last page of the results in the response |
string |
id
| Unique system generated identifier for unique vehicle |
Int |
name
| Name of the driver |
string |
driverId
| Driver Id of the driver |
Int |
modifiedOn
| Indicates the last time the driver record was modified |
DateTime |
Sample Response
{
"href": "https://fleets.trimblemaps.com/api/assets/v1/drivers",
"offset": 50,
"limit": 15,
"size": 255,
"first": {
"href": "https://fleets.trimblemaps.com/api/assets/v1/drivers?offset=0&limit=15"
},
"previous": {
"href": "https://fleets.trimblemaps.com/api/assets/v1/drivers?offset=35&limit=15"
},
"next": {
"href": "https://fleets.trimblemaps.com/api/assets/v1/drivers?offset=65&limit=15"
},
"last": {
"href": "https://fleets.trimblemaps.com/api/assets/v1/drivers?offset=240&limit=15"
},
"data": [
{
"id": 77864,
"name": "Fred",
"driverId": "did12345",
"modifiedOn": "2017-09-12T17:59:04.453"
},
{
"id": 3626,
"name": "Tom",
"driverId": "did48976",
"modifiedOn": "2016-01-19T21:21:47.303"
}
]
}
Delete a Driver
DELETE /drivers
Query Parameter
Delete a driver using their driverID.
Request
Authorization: bearer {token}
Query Parameter
| Name | Description | Data Type |
|---|---|---|
driverId
| Driver ID of the driver |
Int |
Response
| Name | Description | Data Type |
|---|---|---|
message
| Text indicating the result of deleting a driver |
string |
Sample Request
https://fleets.trimblemaps.com/api/assets/v1/drivers?driverId=1234
Sample Response
{
"message": "Successfully deleted driver with Id: 1234"
}
Error Codes
| Message | Description |
|---|---|
| No driver found with Id: {} | The driverId passed in the request to delete was not found in the account. |