Create and Modify Vehicle Groups

Contents

Add Vehicle Groups

POST /vehiclegroups

Adds one or more vehicle groups into the fleet’s account. There is a limit of adding up to 50 vehicle groups per API call.

Vehicle Group names are required to be unique in an account and up to 2,000 vehicle groups can be created in the fleet’s account.

Request

Authorization: bearer {token}

POST Body

Name Description Data Type
VehicleGroupName
(Required) 		The vehicle group name added to the account. Each name must be unique within the fleet’s account. 
String

Response

Name Description Data Type
modifiedOn Indicates the last time the vehicle group was modified. 
DateTime
vehicleGroupId Unique, system-generated identifier for unique vehicle group. 
Int
vehicleGroupName Vehicle group that was added into the fleet’s account. 
Alphanumeric

Sample Request 

[
  {
    "vehicleGroupName": "CherryHillVehicles"
  },
  {
    "vehicleGroupName": "MerryHillVehicles"
  }
]

Sample Response 

{
  "message": "Successfully added all vehicle groups to the account.",
  "data": [
    {
      "vehicleGroupId": 557473,
      "vehicleGroupName": "CherryHillVehicles",
      "modifiedOn": "2020-05-27T20:36:06.647"
    },
    {
      "vehicleGroupId": 557474,
      "vehicleGroupName": "MerryHillVehicles",
      "modifiedOn": "2020-05-27T20:36:06.647"
    }
  ]
}

Error Codes

Message Description
The request finished without adding duplicate vehicle groups. This error is thrown when a vehicle group already exists within the account.

Update a Specific Vehicle Group

PUT /vehiclegroups/{vehicleGroupId}

Updates a vehicle group name based on its unique vehicle group identifier.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupId
(Required) 		Unique system generated identifier for vehicle group. 
String

Request Body

Name Description Data Type
vehicleGroupName New name for the vehicle group. Must be unique within the fleet’s account. 
String

Response

Name Description Data Type
message Acknowledgement of the success or failure of the operation. 
String
data True if operation was successful. 
String

Sample Request 

{
  "vehicleGroupName": "CherryHillVehicles-PA"
}

Sample Response 

{
  "message": "Successfully updated vehicle group",
  "data": true
}

Error Codes

Message Description
The request finished without updating non-existent vehicle group ID. This error is thrown when the vehicle group ID does not exist within the account.

Get a List of All Vehicle Groups

GET /vehiclegroups

Gets a list of vehicle groups available in the account. By default, the first 20 vehicle groups in the account will be populated.

Request

Authorization: bearer {token}

Response

Name Description Data Type
vehicleGroupId Unique, system-generated identifier for unique vehicle group. 
Int
vehicleGroupName Vehicle group name. 
Alphanumeric
modifiedOn Indicates the last time the vehicle group was modified. 
DateTime

Sample Request

https://fleets.trimblemaps.com/api/assets/v1/vehiclegroups

Sample Response 

{
  "message": null,
  "data": [
    {
      "vehicleGroupId": 557473,
      "vehicleGroupName": "CherryHillVehiclesUpdated",
      "modifiedOn": "2020-05-27T20:38:05.383"
    },
    {
      "vehicleGroupId": 557435,
      "vehicleGroupName": "First-Group",
      "modifiedOn": "2020-05-27T17:36:29.22"
    },
    {
      "vehicleGroupId": 557474,
      "vehicleGroupName": "MerryHillVehicles",
      "modifiedOn": "2020-05-27T20:36:06.647"
    }
  ]
}

Get a Specific Vehicle Group

GET /VehicleGroups/{vehicleGroupId}

Gets a vehicle group by its vehicle group ID.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupId
(Required) 		Unique system generated identifier for vehicle group. 
Int

Response

Name Description Data Type
vehicleGroupId Unique, system-generated identifier for unique vehicle group. 
Int
vehicleGroupName Vehicle group name. 
String
modifiedOn Indicates the last time the vehicle group was modified. 
DateTime

Sample Request

https://fleets.trimblemaps.com/api/assets/v1/vehiclegroups/557473

Sample Response 

{
  "message": null,
  "data": {
    "vehicleGroupId": 557473,
    "vehicleGroupName": "CherryHillVehiclesUpdated",
    "modifiedOn": "2020-05-27T20:38:05.383"
  }
}

Delete a Specific Vehicle Group

DELETE /vehiclegroups/{vehicleGroupId}

Delete a vehicle group by its unique vehicle group ID.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupID
(Required) 		Unique, system-generated identifier for unique vehicle group. 
Int

Response

Name Description Data Type
message Text indicating the result of deleting a vehicle group. 
String

Sample Request

https://fleets.trimblemaps.com/api/assets/v1/vehiclegroups/557473

Sample Response 

{
  "message": "Successfully deleted vehicle group",
  "data": true
}

Error Codes

Message Description
No vehicle group found with Id: {} The response indicates that the vehicle group id passed in the request to delete was not found in the account.

Add Vehicles to a Vehicle Group

POST /vehiclegroups/{vehiclegroupid}/vehicles

Adds vehicles to an existing vehicle group.

There is a limit of 50 vehicles per request that can be added to the vehicle group.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupID
(Required) 		Unique, system-generated identifier for unique vehicle group. 
Int

Request Body Parameter

Name Description Data Type
vehicleId
(Required) 		Unique, system-generated identifier for unique vehicles. 
Int

Response

Name Description Data Type
message Text indicating the results of the request to add vehicle IDs. 
String

Sample Request 

{
  "vehicleIds": ["vid12345", "vid123456"]
}

Sample Response 

{
  "message": "Successfully added the following vehicles to the group: vid12345, vid123456",
  "data": ["vid12345", "vid123456"]
}

Delete Vehicles from a Vehicle Group

DELETE /vehiclegroups/{vehiclegroupid}/vehicles

Remove vehicles from an existing vehicle group.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupID
(Required) 		Unique, system-generated identifier for unique vehicle group. 
Int

Request Body Parameter

Name Description Data Type
vehicleId
(Required) 		Unique, system-generated identifier for unique vehicles. 
Int

Response

Name Description Data Type
message Text indicating the results of the request to delete vehicle IDs. 
String

Sample Request 

{
  "vehicleIds": ["vid12345"]
}

Sample Response 

{
  "message": "Successfully removed the following vehicles from the group: vid12345",
  "data": ["vid12345"]
}

Get List of Vehicles in a Vehicle Group

GET /vehiclegroups/{vehiclegroupid}/vehicles

Gets a list of vehicles in an existing vehicle group.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleGroupID
(Required) 		Unique, system-generated identifier for unique vehicle group. 
Int

Response

Name Description Data Type
id Unique, system generated identifier for unique vehicle. 
Int
vehicleId Vehicle identifier. 
Alphanumeric
name Vehicle name. 
Alphanumeric
modifiedOn Indicates the last time the vehicle group was modified. 
DateTime

Sample Request

https://fleets.trimblemaps.com/api/assets/v1/vehiclegroups/504954/vehicles

Sample Response 

{
  "message": null,
  "data": [
    {
      "id": 496913,
      "name": "vid12345",
      "vehicleId": "vid12345",
      "modifiedOn": "2020-05-27T20:21:53.08"
    },
    {
      "id": 496914,
      "name": "vid123456",
      "vehicleId": "vid123456",
      "modifiedOn": "2020-05-27T20:22:10.55"
    }
  ]
}

Get List of Vehicle Groups by Vehicle

GET /vehicles/{vehicleId}/groups

Gets a list of vehicle groups associated with a specific vehicle.

Request

Authorization: bearer {token}

Query Parameter

Name Description Data Type
vehicleId
(Required) 		The vehicle identifier for which you want to retrieve a list of vehicle groups. A vehicleId must be unique within the fleet account & partner cloud. 
Alphanumeric

Response

Name Description Data Type
vehicleGroupId Unique, system-generated identifier for unique vehicle group. 
Int
vehicleGroupName The vehicle group name. 
String

Sample Request

https://fleets.trimblemaps.com/api/assets/v1/vehicles/veh1/groups

Sample Response 

{
    "message": "Successfully retrieved vehicle groups for vehicle veh1",
    "data": [
        {
            "vehicleGroupId": 1085632,
            "vehicleGroupName": "CherryHillVehicles"
        },
        {
            "vehicleGroupId": 1085633,
            "vehicleGroupName": "MerryHillVehicles"
        }
    ]
}

Error Codes

Message Description
No vehicle groups are associated with vehicle {vehicleId}. This error is thrown when no vehicle groups are associated with the requested vehicleId.
Last updated July 6, 2021.