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.

Request

Authorization: bearer {token}

NameDescriptionData 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

NameDescriptionData Type
IdUnique, system-generated identifier for unique vehicle 
Int
NameVehicle Name that was added into the fleet account 
Alphanumeric
VehicleIdVehicle Id that was added into the fleet account 
Alphanumeric
ModifiedOnIndicates 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

MessageDescription
The request finished without adding duplicate vehicleIds for the PartnerThis 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}

NameDescriptionData Type
VehicleID
(Required)		External Vehicle Identifier 
Alphanumeric
Name
(Required)		External Vehicle Name 
string

Response

NameDescriptionData Type
IdUnique, system-generated identifier for unique vehicle 
Int
NameVehicle Name that was updated 
Alphanumeric
VehicleIdVehicle Id of the vehicle that was updated 
Alphanumeric
ModifiedOnIndicates 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

MessageDescription
The request finished without updating non-existent vehicleIdsThis 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}

NameDescriptionData Type
offsetPagination parameter indicating the cursor position to begin with in the response for this request 
Alphanumeric
limitPagination parameter indicating the number of results to return in the response for this request 
Int
sortExpressionThe parameter based on which sorting should be performed. Pass either vehicleId or vehicleName. 
string
sortDirectionSort the results in ascending or descending order. Pass either ASC or DESC. 
string

Response

NameDescriptionData Type
hrefRequest URL 
string
offsetPagination parameter indicating the cursor position at which the response begins 
Int
limitPagination parameter indicating the number of results in the response 
Int
sizePagination parameter indicating the total number of pages that are available in the response 
Int
firstPagination parameter with a link to get the first page of the results in the response 
string
nextPagination parameter with a link to get the next page of the results in the response 
string
previousPagination parameter with a link to get the previous page of the results in the response 
string
lastPagination parameter with a link to get the last page of the results in the response 
string
idUnique system generated identifier for unique vehicle 
Int
nameName of the vehicle 
string
vehicleIdVehicle Id of the vehicle 
Int
vehicleGroupIdThe id for the vehicle group to which a vehicle belongs. 
Int
vehicleGroupNameThe name for the vehicle group to which a vehicle belongs. 
string
modifiedOnIndicates 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}

NameDescriptionData Type
vehicleIdVehicle ID of the vehicle 
Int

Response

NameDescriptionData Type
messageText indicating the result of deleting a vehicle 
string

Sample Response 

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

Error Codes

MessageDescription
No vehicle found with Id: {}The vehicleId passed in the request to delete was not found in the account.
Last updated February 17, 2023.
Contents