RESTful APIs

Create and Modify Vehicles

Contents

Add Vehicles

POST /vehicles

Adds vehicles into the fleet account. There is a limit of adding 50 vehicles per API call. Each vehicle must have a Vehicle ID (identifier) and a Vehicle Name.

Direct CoPilot customer/fleet account

Vehicle IDs and Vehicle Names are required to be unique within the fleet.

Partner/Reseller

If you are a partner/reseller, Vehicle IDs are required to be unique within the partner/reseller cloud.

Note:

  • If a Vehicle ID and Vehicle Name combination already exists in the fleet account or the partner/reseller cloud and
    • If the same Vehicle ID and Vehicle 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 Vehicle ID is same but Vehicle Name is different, then an appropriate message is sent in the response 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
VehicleID
(Required) 		External Vehicle Identifier—must be unique within the fleet account & partner cloud. 
Alphanumeric
Name
(Required) 		External Vehicle Name—must be unique within the fleet account & partner cloud. 
string

Response

Name Description Data Type
Id Unique, system-generated identifier for unique vehicle 
Int
Name Vehicle Name that was added into the fleet account 
Alphanumeric
VehicleId Vehicle Id that was added into the fleet account 
Alphanumeric
ModifiedOn Indicates the last time the vehicle was modified 
DateTime

Sample Request 

[
  {
    "vehicleId": "veh1",
    "Name": "vehicle 1"
  },
  {
    "vehicleId": "veh2",
    "Name": "vehicle 2"
  }
]

Sample Response 

{
  "error": {
    "message": "The request finished without adding duplicate vehicleIds for the Partner",
    "code": -12,
    "duplicate_ids": ["veh1"]
  },
  "data": [
    {
      "Id": 304954,
      "Name": "vehicle 2",
      "VehicleId": "veh2",
      "ModifiedOn": "2019-03-28T21:02:19.03"
    }
  ]
}

Error Codes

Message Description
The request finished without adding duplicate vehicleIds for the Partner This error is thrown when vehicleIds already exist within the Partner.

Update Vehicles

PUT /vehicles

Updates a Vehicle Name that is associated with a specific Vehicle ID. The Name must be unique within the fleet.

Request

Authorization: bearer {token}

Name Description Data Type
VehicleID
(Required) 		External Vehicle Identifier 
Alphanumeric
Name
(Required) 		External Vehicle Name 
string

Response

Name Description Data Type
Id Unique, system-generated identifier for unique vehicle 
Int
Name Vehicle Name that was updated 
Alphanumeric
VehicleId Vehicle Id of the vehicle that was updated 
Alphanumeric
ModifiedOn Indicates the last time the vehicle was modified 
DateTime

Sample Request 

[
  {
    "vehicleId": "veh1",
    "Name": "vehicle new 1"
  },
  {
    "vehicleId": "veh3",
    "Name": "vehicle 3"
  }
]

Sample Response 

{
  "error": {
    "message": "The request finished without updating non-existent vehicleIds",
    "code": -11,
    "ids_not_found": ["veh3"]
  },
  "data": [
    {
      "Id": 304953,
      "Name": "vehicle new 1",
      "VehicleId": "veh1",
      "ModifiedOn": "2019-03-28T20:44:54.673"
    }
  ]
}

Error Codes

Message Description
The request finished without updating non-existent vehicleIds This error is thrown when vehicleIds do not exist within the account.

Get a List of Vehicles

GET /vehicles

Gets a list of Vehicle IDs and Vehicle Names from an account.

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 vehicleId or vehicleName. 
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 vehicle 
string
vehicleId Vehicle Id of the vehicle 
Int
vehicleGroupId The id for the vehicle group to which a vehicle belongs. 
Int
vehicleGroupName The name for the vehicle group to which a vehicle belongs. 
string
modifiedOn Indicates the last time the vehicle record was modified 
DateTime

Sample Response 

{
    "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles",
    "offset": 0,
    "limit": 20,
    "size": 9,
    "first": {
        "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles?offset=0&limit=20"
    },
    "data": [
        {
            "id": 415950,
            "name": "vehicle_assign/unassign11661782258",
            "vehicleId": "vehidassign11661782258",
            "modifiedOn": "2022-08-29T14:10:58.113"
        },
        {
            "id": 415955,
            "name": "vehicle_assign/unassign11661782278",
            "vehicleId": "vehidassign11661782278",
            "modifiedOn": "2022-08-29T14:11:18.023"
        },
        {
            "id": 420249,
            "name": "vehicle_assign/unassign11673474504",
            "vehicleId": "vehidassign11673474504",
            "modifiedOn": "2023-01-11T22:01:43.63",
            "vehicleGroups": [
                {
                    "vehicleGroupId": 771579,
                    "vehicleGroupName": "vehgroupname1673474496641"
                }
            ]
        },
        {
            "id": 415951,
            "name": "vehicle_assign/unassign21661782258",
            "vehicleId": "vehidassign21661782258",
            "modifiedOn": "2022-08-29T14:10:58.303",
            "vehicleGroups": [
                {
                    "vehicleGroupId": 766948,
                    "vehicleGroupName": "vehgroupname1661782257589"
                }
            ]
        },
        {
            "id": 415956,
            "name": "vehicle_assign/unassign21661782278",
            "vehicleId": "vehidassign21661782278",
            "modifiedOn": "2022-08-29T14:11:18.273",
            "vehicleGroups": [
                {
                    "vehicleGroupId": 766951,
                    "vehicleGroupName": "vehgroupname1661782276757"
                },
                {
                    "vehicleGroupId": 771579,
                    "vehicleGroupName": "vehgroupname1673474496641"
                }
            ]
        },
        {
            "id": 815954,
            "name": "vehicle_assign/unassign41661782261",
            "vehicleId": "vehidassign41661782261",
            "modifiedOn": "2022-08-29T14:11:01.053",
            "vehicleGroups": [
                {
                    "vehicleGroupId": 766948,
                    "vehicleGroupName": "vehgroupname1661782257589"
                }
            ]
        },
        {
            "id": 820247,
            "name": "vehicleDynamic",
            "vehicleId": "veh1673474411894",
            "modifiedOn": "2023-01-11T22:00:12.183"
        }
    ]
}

Delete a Vehicle

DELETE /vehicles

Delete a vehicle by its vehicleId.

Request

Authorization: bearer {token}

Name Description Data Type
vehicleId Vehicle ID of the vehicle 
Int

Response

Name Description Data Type
message Text indicating the result of deleting a vehicle 
string

Sample Response 

{
  "message": "Successfully deleted vehicle with Id: 304953"
}

Error Codes

Message Description
No vehicle found with Id: {} The vehicleId passed in the request to delete was not found in the account.
Last updated July 6, 2023.
Contents