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.
|