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.

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION

INTERACTIVE MAPS

Create and Modify Vehicles

Add Vehicles

POST /vehicles

Request

Response

Sample Request

Sample Response

Error Codes

Update Vehicles

PUT /vehicles

Request

Response

Sample Request

Sample Response

Error Codes

Get a List of Vehicles

GET /vehicles

Request

Response

Sample Response

Delete a Vehicle

DELETE /vehicles

Request

Response

Sample Response

Error Codes