Create and Modify Vehicles

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 an optional Vehicle Name.

Direct CoPilot customer/fleet account

Vehicle IDs are required to be unique within the fleet, whereas Vehicle Name is not required to be unique.

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

Request

Authorization: bearer {token}

NameDescriptionData Type
VehicleID
(Required)
External Vehicle Identifier—must be unique within the fleet account & partner cloud.Alphanumeric
Name
(Optional)
External Vehicle Name—need not be unique within the fleet account & partner cloud.string

Response

NameDescriptionData Type
IdUnique, system-generated identifier for unique vehicleInt
NameVehicle Name that was added into the fleet accountAlphanumeric
VehicleIdVehicle Id that was added into the fleet accountAlphanumeric
ModifiedOnIndicates the last time the vehicle was modifiedDateTime

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.

Request

Authorization: bearer {token}

NameDescriptionData Type
VehicleID
(Required)
External Vehicle IdentifierAlphanumeric
Name
(Optional)
External Vehicle Namestring

Response

NameDescriptionData Type
IdUnique, system-generated identifier for unique vehicleInt
NameVehicle Name that was updatedAlphanumeric
VehicleIdVehicle Id of the vehicle that was updatedAlphanumeric
ModifiedOnIndicates the last time the vehicle was modifiedDateTime

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 requestAlphanumeric
limitPagination parameter indicating the number of results to return in the response for this requestInt
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 URLstring
offsetPagination parameter indicating the cursor position at which the response beginsInt
limitPagination parameter indicating the number of results in the responseInt
sizePagination parameter indicating the total number of pages that are available in the responseInt
firstPagination parameter with a link to get the first page of the results in the responsestring
nextPagination parameter with a link to get the next page of the results in the responsestring
previousPagination parameter with a link to get the previous page of the results in the responsestring
lastPagination parameter with a link to get the last page of the results in the responsestring
idUnique system generated identifier for unique vehicleInt
nameName of the vehiclestring
vehicleIdVehicle Id of the vehicleInt
modifiedOnIndicates the last time the vehicle record was modifiedDateTime

Sample Response

{
  "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles",
  "offset": 50,
  "limit": 15,
  "size": 255,
  "first": {
    "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles?offset=0&limit=15"
  },
  "previous": {
    "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles?offset=35&limit=15"
  },
  "next": {
    "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles?offset=65&limit=15"
  },
  "last": {
    "href": "https://fleets.trimblemaps.com/api/assets/v1/vehicles?offset=240&limit=15"
  },
  "data": [
    {
      "id": 77864,
      "name": "111111",
      "vehicleId": "111111",
      "modifiedOn": "2017-09-12T17:59:04.453"
    },
    {
      "id": 3626,
      "name": "1114885",
      "vehicleId": "1114885",
      "modifiedOn": "2016-01-19T21:21:47.303"
    }
  ]
}

Delete a Vehicle

DELETE /vehicles

Delete a vehicle by its vehicleId.

Request

Authorization: bearer {token}

NameDescriptionData Type
vehicleIdVehicle ID of the vehicleInt

Response

NameDescriptionData Type
messageText indicating the result of deleting a vehiclestring

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 September 20, 2019.