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 is required to be unique within the fleet account, whereas Driver Name is not required to be unique.

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.
    • If Driver Name is the same but Driver ID is different, then a new record gets created with the new Driver ID and Driver Name.

Request

Authorization: bearer {token}

Name Description Data Type
driverId External driver identifier—must be unique within the fleet account
Alphanumeric
Name External driver name—need not 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.

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

Delete a driver using his or her driverID.

Request

Authorization: bearer {token}

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 Response

{
  "message": "Successfully deleted driver with Id: did48976"
}

Error Codes

Message Description
No driver found with Id: {} The driverId passed in the request to delete was not found in the account.
Last updated June 4, 2020.