> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# 🧪 Update Vehicle

PATCH https://api.catenatelematics.com/v2/telematics/vehicles/{id}
Content-Type: application/json

Update an existing vehicle. By default, the vehicle will be updated asynchronously, and you can check the status of the operation using the returned operation ID.

Reference: https://catena.ferndocs.com/api-reference/telematics/fleet-operations-tracking/update-vehicle

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `id` (string, required) — The unique identifier of the vehicle

### Query parameters

- `is_sync` (boolean, optional, default: false) — Whether to process the request synchronously. If `true`, Catena will attempt to create or update the resource immediately with the TSP and return the result in the response. When performing synchronous operations, you are responsible for handling any necessary retries in case of transient failures.If `false` (default), Catena will create an asynchronous operation, and you can check the status of the operation using the returned operation ID.

### Body (application/json)

This endpoint expects a VehicleUpdate.

- `connection_id` (string, required) — Unique identifier of the connection at Catena Telematics which will be used to create this resource. A connection represents a Fleet/TSP pairing.
- `vehicle_name` (string, optional, nullable) — Display name or unit number for the vehicle.
- `oem` (string, optional, nullable) — Manufacturer (OEM) of the vehicle.
- `model_type` (string, optional, nullable) — Manufacturer model or type designation (e.g., 'Class 8 Tractor', 'Pickup').
- `model_year` (integer, optional, nullable) — Model year (four-digit, e.g., 2022).
- `vin` (string, optional, nullable) — Vehicle Identification Number (VIN), typically 17 characters; if available.
- `engine_vin` (string, optional, nullable) — Engine serial number or engine VIN, if available.
- `license_plate_region` (string, optional, nullable) — Plate region/subdivision (state/province code, e.g., 'CA', 'ON').
- `license_plate_country` (string, optional, nullable) — Plate country code (ISO-3166-1 alpha-3, e.g., 'USA', 'CAN').
- `license_plate_number` (string, optional, nullable) — License plate number (e.g., 'HMT-3570').
- `is_active` (boolean, optional, nullable) — Indicates whether the vehicle is currently active/in service.
- `status` (enum, optional, nullable) — Operational status label (e.g., 'IN_SERVICE', 'OUT_OF_SERVICE', 'MAINTENANCE').
  - Allowed values: `IN_SERVICE`, `OUT_OF_SERVICE`, `IN_REPAIR`, `IN_TRANSIT`, `IN_USE`, `IN_STORAGE`, `STANDING`, `SPARE`
- `notes` (string, optional, nullable) — Free-text notes about the vehicle (plain text).
- `eld_id` (string, optional, nullable) — Telematics/ELD device identifier associated with this vehicle, if any.
- `eld_serial_number` (string, optional, nullable) — Telematics/ELD device serial number, if any.
- `eld_device_type` (string, optional, nullable) — Telematics/ELD device type or model family (vendor-specific).
- `eld_product_id` (string, optional, nullable) — Telematics/ELD vendor product identifier (catalog/model code).
- `total_axles` (integer, optional, nullable) — Total number of axles on the vehicle.
- `external_id` (string, optional, nullable) — External vehicle identifier as known in the TSP or customer's system.
- `speed_unit` (string, optional, nullable) — Unit of measure for speed metrics (e.g., 'km/h', 'mph').
- `odometer_unit` (string, optional, nullable) — Unit of measure for odometer readings (e.g., 'km', 'mi').
- `fuel_unit` (string, optional, nullable) — Unit of measure for fuel quantities (e.g., 'gallons', 'liters').
- `fuel_capacity` (string, optional, nullable) — Fuel capacity as provided by the source (text with units, e.g., '100 gallons').
- `engine_type` (enum, optional, nullable) — Engine/fuel type (e.g., 'diesel', 'gasoline', 'electric', 'hybrid').
  - Allowed values: `GASOLINE`, `GASOLINE`, `GASOLINE`, `DIESEL`, `DIESEL`, `DIESEL`, `ETHANOL`, `ETHANOL`, `ETHANOL`, `METHANOL`, `METHANOL`, `PROPANE`, `LPG`, `CNG`, `LNG`, `HYDROGEN`, `ELECTRICITY`, `HYBRID`

## Response

### 200

The vehicle was updated successfully.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

### 202

The request to update the vehicle has been accepted and is being processed.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

## Errors

### 400 Bad Request Error

Bad Request

- `code` (integer, optional, default: 400)
- `message` (string, optional, default: Bad Request)
- `detail` (string, optional, nullable)

### 401 Unauthorized Error

Unauthorized

- `code` (integer, optional, default: 401)
- `message` (string, optional, default: Unauthorized)
- `detail` (string, optional, nullable)

### 403 Forbidden Error

Forbidden

- `code` (integer, optional, default: 403)
- `message` (string, optional, default: Forbidden)
- `detail` (string, optional, nullable)

### 404 Not Found Error

Not Found

- `code` (integer, optional, default: 404)
- `message` (string, optional, default: Not Found)
- `detail` (string, optional, nullable)

### 405 Method Not Allowed Error

Method Not Allowed

- `code` (integer, optional, default: 405)
- `message` (string, optional, default: Method Not Allowed)
- `detail` (string, optional, nullable)

### 409 Conflict Error

Conflict

- `code` (integer, optional, default: 409)
- `message` (string, optional, default: Conflict)
- `detail` (string, optional, nullable)

### 422 Unprocessable Entity Error

Unprocessable Entity

- `code` (integer, optional, default: 422)
- `message` (string, optional, default: Invalid Request Body)
- `detail` (list of ValidationErrorDetail, optional, nullable)

### 429 Too Many Requests Error

Too Many Requests

- `code` (integer, optional, default: 429)
- `message` (string, optional, default: Too Many Requests)
- `detail` (RetryAfterDetail, optional, nullable)

### 500 Internal Server Error

Internal Server Error

- `message` (string, optional, default: Internal Server Error)

### 501 Not Implemented Error

Not Implemented

- `code` (integer, optional, default: 501)
- `message` (string, optional, default: Not Implemented)
- `detail` (string, optional, nullable)

### 502 Bad Gateway Error

The request to update the vehicle could not be processed at this time. Please see the response for more details.

- `partner_id` (string, required) — The ID of the partner that created the operation.
- `connection_id` (string, required) — The ID of the connection
- `resource` (enum, required) — The type of resource to operate on (e.g., vehicle, driver).
  - Allowed values: `asset`, `document`, `driver_association`, `driver_vehicle_association`, `driver_event_log`, `driver_safety_event`, `dvir_log`, `dvir_log_defect`, `engine_log`, `engine_status`, `fuel_transaction`, `fuel_card`, `fleet_info`, `hos_availability`, `hos_daily_log`, `hos_daily_snapshot`, `hos_event`, `hos_event_annotation`, `hos_event_attachment`, `hos_violation`, `ifta_summary`, `location_segment`, `message`, `group_message`, `user`, `vehicle`, `vehicle_location`, `vehicle_sensor`, `vehicle_region_segment`, `trailer`, `trailer_association`, `trailer_vehicle_association`, `trailer_location`, `trailer_status`, `workflow`
- `operation_type` (enum, required) — The type of operation to perform (e.g., create, update).
  - Allowed values: `create`, `update`
- `payload` (map from string to any, required) — The payload of the operation, containing the resource attributes to be created or updated.
- `id` (string, optional) — Unique identifier for the resource operation.
- `created_at` (datetime, optional) — Immutable: The datetime the record was created in Catena Telematics.
- `updated_at` (datetime, optional) — The datetime the record was last modified in Catena Telematics.
- `deleted_at` (datetime, optional, nullable) — The datetime the record was logically deleted from Catena Telematics.
- `resource_id` (string, optional, nullable) — Unique identifier of the record. Can be `null` for create operations where the source does not exist yet.
- `source_id` (string, optional, nullable) — The unique identifier of the resource in the source system. Required for update operations.
- `status` (enum, optional) — The status of the operation
  - Allowed values: `pending`, `success`, `failed`
- `logs` (list of ResourceOperationLog, optional) — Log entries for each attempt to execute this operation.

## Types

### ResourceOperationLog

API response model for a resource operation log entry.

- `id` (string, required) — Unique identifier for the log entry.
- `created_at` (datetime, required) — Timestamp when the log entry was created.
- `updated_at` (datetime, required) — Timestamp when the log entry was last updated.
- `resource_operation_id` (string, required) — The ID of the resource operation this log entry belongs to.
- `status` (enum, required) — The status of the operation attempt.
  - Allowed values: `success`, `failed`
- `error_type` (enum, optional, nullable) — The type of error that occurred, if any.
  - Allowed values: `auth`, `validation`, `network`, `tsp`
- `error_details` (string, optional, nullable) — Detailed information about the error, if any.
- `response_status_code` (integer, optional, nullable) — HTTP status code returned by the TSP, if available.
- `response_headers` (map from string to string, optional, nullable) — HTTP response headers from the TSP (e.g. rate limit state).

### ValidationErrorDetail

- `path` (string, required)
- `input` (string, required)
- `message` (string, required)
- `error_type` (string, required)

### RetryAfterDetail

- `retry_after_seconds` (integer, required)
- `message` (string, required)

## Examples

### Example 1

**Request**

```json
{
  "connection_id": "string"
}
```

**Response**

```json
{
  "partner_id": "string",
  "connection_id": "string",
  "resource": "asset",
  "operation_type": "create",
  "payload": {},
  "id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "deleted_at": "2024-01-15T09:30:00Z",
  "resource_id": "string",
  "source_id": "string",
  "status": "pending",
  "logs": [
    {
      "id": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "resource_operation_id": "string",
      "status": "success",
      "error_type": "auth",
      "error_details": "string",
      "response_status_code": 1,
      "response_headers": {}
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.catenatelematics.com/v2/telematics/vehicles/id"

payload = { "connection_id": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.catenatelematics.com/v2/telematics/vehicles/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"connection_id":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.catenatelematics.com/v2/telematics/vehicles/id"

	payload := strings.NewReader("{\n  \"connection_id\": \"string\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.catenatelematics.com/v2/telematics/vehicles/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.catenatelematics.com/v2/telematics/vehicles/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.catenatelematics.com/v2/telematics/vehicles/id', [
  'body' => '{
  "connection_id": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.catenatelematics.com/v2/telematics/vehicles/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"connection_id\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["connection_id": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/vehicles/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Request**

```json
{
  "connection_id": "string"
}
```

**Response**

```json
{
  "partner_id": "string",
  "connection_id": "string",
  "resource": "asset",
  "operation_type": "create",
  "payload": {},
  "id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "deleted_at": "2024-01-15T09:30:00Z",
  "resource_id": "string",
  "source_id": "string",
  "status": "pending",
  "logs": [
    {
      "id": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "resource_operation_id": "string",
      "status": "success",
      "error_type": "auth",
      "error_details": "string",
      "response_status_code": 1,
      "response_headers": {}
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.catenatelematics.com/v2/telematics/vehicles/id"

payload = { "connection_id": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.catenatelematics.com/v2/telematics/vehicles/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"connection_id":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.catenatelematics.com/v2/telematics/vehicles/id"

	payload := strings.NewReader("{\n  \"connection_id\": \"string\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.catenatelematics.com/v2/telematics/vehicles/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"connection_id\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.catenatelematics.com/v2/telematics/vehicles/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"connection_id\": \"string\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.catenatelematics.com/v2/telematics/vehicles/id', [
  'body' => '{
  "connection_id": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.catenatelematics.com/v2/telematics/vehicles/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"connection_id\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["connection_id": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.catenatelematics.com/v2/telematics/vehicles/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```