Update Vehicle
const options = {
method: 'PATCH',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
type: '<string>',
ownership: '<string>',
license_plate: '<string>',
country: '<string>',
vehicle_fuel_id: '<string>',
custom_emission_factor_id: '<string>',
registration_year: 123,
market_segment: '<string>',
size: '<string>',
unknown_vehicle_id: '<string>',
organization_id: '<string>'
})
};
fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}"
payload = {
"name": "<string>",
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"vehicle_fuel_id": "<string>",
"custom_emission_factor_id": "<string>",
"registration_year": 123,
"market_segment": "<string>",
"size": "<string>",
"unknown_vehicle_id": "<string>",
"organization_id": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)curl --request PATCH \
--url https://api.dcycle.io/v1/vehicles/{vehicle_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"name": "<string>",
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"vehicle_fuel_id": "<string>",
"custom_emission_factor_id": "<string>",
"registration_year": 123,
"market_segment": "<string>",
"size": "<string>",
"unknown_vehicle_id": "<string>",
"organization_id": "<string>"
}
'{
"id": "<string>",
"name": {},
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"status": "<string>",
"co2e": 123,
"vehicle_fuel_id": {},
"vehicle_fuel": {},
"vehicle_fuel_units": {
"id": "<string>",
"name": "<string>",
"type": "<string>"
},
"unknown_vehicle_id": {},
"unknown_vehicle_type": {},
"custom_emission_factor_id": {},
"registration_year": {},
"market_segment": {},
"size": {},
"error_messages": {},
"file_id": {},
"file_name": {},
"created_at": {},
"updated_at": {}
}Update Vehicle
Modify vehicle details and update fleet information
PATCH
/
v1
/
vehicles
/
{vehicle_id}
Update Vehicle
const options = {
method: 'PATCH',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
type: '<string>',
ownership: '<string>',
license_plate: '<string>',
country: '<string>',
vehicle_fuel_id: '<string>',
custom_emission_factor_id: '<string>',
registration_year: 123,
market_segment: '<string>',
size: '<string>',
unknown_vehicle_id: '<string>',
organization_id: '<string>'
})
};
fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}"
payload = {
"name": "<string>",
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"vehicle_fuel_id": "<string>",
"custom_emission_factor_id": "<string>",
"registration_year": 123,
"market_segment": "<string>",
"size": "<string>",
"unknown_vehicle_id": "<string>",
"organization_id": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)curl --request PATCH \
--url https://api.dcycle.io/v1/vehicles/{vehicle_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"name": "<string>",
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"vehicle_fuel_id": "<string>",
"custom_emission_factor_id": "<string>",
"registration_year": 123,
"market_segment": "<string>",
"size": "<string>",
"unknown_vehicle_id": "<string>",
"organization_id": "<string>"
}
'{
"id": "<string>",
"name": {},
"type": "<string>",
"ownership": "<string>",
"license_plate": "<string>",
"country": "<string>",
"status": "<string>",
"co2e": 123,
"vehicle_fuel_id": {},
"vehicle_fuel": {},
"vehicle_fuel_units": {
"id": "<string>",
"name": "<string>",
"type": "<string>"
},
"unknown_vehicle_id": {},
"unknown_vehicle_type": {},
"custom_emission_factor_id": {},
"registration_year": {},
"market_segment": {},
"size": {},
"error_messages": {},
"file_id": {},
"file_name": {},
"created_at": {},
"updated_at": {}
}← Vehicles API
Update specific fields of an existing vehicle. All fields are optional - only include fields you want to modify. Omitted fields will retain their current values.
Solution: Verify your API key is valid and active. Get a new one in Company settings → API Keys.
Solution: Send the request from the parent organization (
Solution: Verify that the vehicle ID is correct and belongs to your organization. Use the List Vehicles endpoint to get valid IDs.
Solution: Ensure enum values are exactly as specified. Use valid country codes (2-3 characters) and permitted values for
CO2e Recalculation: When you update fields like
vehicle_fuel_id, registration_year, or market_segment, CO2e emissions are automatically recalculated.Request
Path Parameters
uuid
required
The UUID of the vehicle to updateExample:
550e8400-e29b-41d4-a716-446655440000Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faBody Parameters
All parameters are optional. Only include fields you want to update.string
Custom name or alias for the vehicleExample:
"Updated Fleet Car Name"string
Type of vehicle usageAvailable values:
passenger, freightExample: "passenger"string
Vehicle ownership typeAvailable values:
owned, rentedExample: "owned"string
Vehicle registration/license plate numberExample:
"XYZ-9999"string
ISO 3166-1 country code (2-3 characters)Examples:
"US", "GB", "ES", "DE"Example: "ES"uuid
UUID of the vehicle fuel typeRetrieve available options from
GET /v1/vehicle-fuelsExample: "660e8400-e29b-41d4-a716-446655440000"uuid
UUID of a custom emission factorFor organizations with custom emission dataDespite the name, this field holds the id of a custom emission group, not of an individual
factor. Retrieve available options from
GET /custom_emission_groups/lightExample: "770e8400-e29b-41d4-a716-446655440000"integer
Year of vehicle registration (YYYY format)Example:
2023string
Vehicle market segment for classificationAvailable values:
mini, supermini, lower_medium, upper_medium, executive, luxury, sports, dual_purpose_4x4, mpvExample: "upper_medium"string
Vehicle size categoryAvailable values:
small_car, medium, large_car, average_carExample: "medium"uuid
UUID of the unknown vehicle typeRetrieve available options from
GET /v1/unknown-vehiclesExample: "550e8400-e29b-41d4-a716-446655440001"uuid
Move the vehicle to this organization. Must be the header organization or one of its accepted, enabled descendant organizations.The move keeps the vehicle’s id, its consumptions, measure periods and custom-column values; its emissions are re-attributed to the target organization and recalculated there. Sending the vehicle’s current organization changes nothing.Moving requires a user session (an API key without a user is refused) with a non-Viewer membership in the header organization. A move is refused when an enabled vehicle of the target already uses the license plate, when the vehicle’s custom emission factor is not available to the target, when the vehicle is linked to a land management unit, or when one of its custom-column values cannot be carried into the target.Example:
"a8315ef3-dd50-43f8-b7ce-d839e68d51fb"Response
string
Unique identifier (UUID) for the vehicle
string | null
Custom name or alias for the vehicle
string
Type of vehicle usage:
passenger or freightstring
Ownership type:
owned or rentedstring
Vehicle registration/license plate number
string
ISO 3166-1 country code
string
Current status:
active, archived, or errornumber
Updated CO2 equivalent emissions in kg CO2e
string | null
UUID of the fuel type
string | null
Fuel type name (e.g.
diesel, petrol, electric)array[object] | null
string | null
UUID of the unknown vehicle type
string | null
String name of the unknown vehicle type (e.g.
Truck, Van)string | null
UUID of the custom emission factor applied, if any
integer | null
Year of vehicle registration
string | null
Vehicle market segment classification
string | null
Vehicle size category
array[string] | null
Error codes when status is
errorstring | null
UUID of the import file, if created via CSV import
string | null
Name of the import file, if created via CSV import
datetime
Timestamp when the vehicle was created
datetime | null
Timestamp when the vehicle was last updated
Example
curl -X PATCH "https://api.dcycle.io/v1/vehicles/550e8400-e29b-41d4-a716-446655440000" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Fleet Car #1",
"registration_year": 2023,
"market_segment": "executive"
}'
import requests
import os
api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")
vehicle_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {
"x-api-key": api_key,
"x-organization-id": org_id,
"Content-Type": "application/json"
}
payload = {
"name": "Updated Fleet Car #1",
"registration_year": 2023,
"market_segment": "executive"
}
response = requests.patch(
f"https://api.dcycle.io/v1/vehicles/{vehicle_id}",
headers=headers,
json=payload
)
vehicle = response.json()
print(f"Vehicle updated: {vehicle['id']}")
print(f"New CO2e: {vehicle['co2e']} kg")
const axios = require('axios');
const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const vehicleId = "550e8400-e29b-41d4-a716-446655440000";
const headers = {
'x-api-key': apiKey,
'x-organization-id': orgId,
'Content-Type': 'application/json'
};
const payload = {
name: "Updated Fleet Car #1",
registration_year: 2023,
market_segment: "executive"
};
axios.patch(
`https://api.dcycle.io/v1/vehicles/${vehicleId}`,
payload,
{ headers }
)
.then(response => {
const vehicle = response.data;
console.log(`Vehicle updated: ${vehicle.id}`);
console.log(`New CO2e: ${vehicle.co2e} kg`);
})
.catch(error => console.error(error));
Successful Response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Updated Fleet Car #1",
"type": "passenger",
"ownership": "owned",
"license_plate": "ABC-1234",
"country": "ES",
"status": "active",
"co2e": 248.3,
"vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000",
"vehicle_fuel": "diesel",
"vehicle_fuel_units": [
{ "id": "unit-uuid", "name": "litres", "type": "volume" }
],
"unknown_vehicle_id": null,
"unknown_vehicle_type": null,
"custom_emission_factor_id": null,
"registration_year": 2023,
"market_segment": "executive",
"size": "medium",
"error_messages": null,
"file_id": null,
"file_name": null,
"created_at": "2024-11-24T10:30:00Z",
"updated_at": "2024-11-24T15:45:00Z"
}
Common Errors
401 Unauthorized
Cause: Missing or invalid API key{
"detail": "Invalid API key",
"code": "INVALID_API_KEY"
}
403 Forbidden (moving a vehicle)
Cause:organization_id is not the header organization or one of its accepted, enabled descendants (a parent, a sibling or another company), or the caller may not write into another organization: an API key without a user (CROSS_ORG_WRITE_REQUIRES_USER), a Viewer (VIEWER_CANNOT_WRITE) or a user without membership in the header organization (LOGGED_USER_NOT_MEMBER).
{
"detail": "Target organization is not in the header organization's writable family."
}
x-organization-id) with a user session, and pick the target among its subsidiaries.
404 Not Found
Cause: Vehicle not found in organization{
"code": "VEHICLE_NOT_FOUND",
"detail": "Vehicle with id=UUID('...') not found"
}
422 Validation Error
Cause: Invalid values for enumerated fields{
"detail": [
{
"loc": ["body", "type"],
"msg": "value is not a valid enumeration member; permitted: 'passenger', 'freight'",
"type": "type_error.enum"
}
]
}
type, ownership, market_segment, and size.
When moving a vehicle (organization_id), a 422 also reports what the vehicle carries that the target cannot take: LICENSE_PLATE_ALREADY_EXISTS (an enabled vehicle of the target has the plate) or CUSTOM_EMISSION_FACTOR_NOT_FOUND_OR_DISABLED (its custom emission group is not available to the target).
409 Conflict (moving a vehicle)
| Code | Cause | Solution |
|---|---|---|
VEHICLE_LINKED_TO_LAND_MANAGEMENT | The vehicle is linked to a land management unit of its current organization | Unlink it from the unit first |
VEHICLE_MOVE_CUSTOM_COLUMN_CONFLICT | A custom column holding a value exists in the target with another type or without that option, or holds a relation/user that belongs to the current organization | Clear the value or rename the column, then retry |
Use Cases
Update Vehicle Ownership Status
Change vehicle ownership from owned to rented:def change_vehicle_ownership(vehicle_id, new_ownership):
"""Update vehicle ownership status"""
payload = {"ownership": new_ownership}
response = requests.patch(
f"https://api.dcycle.io/v1/vehicles/{vehicle_id}",
headers=headers,
json=payload
)
return response.json()
# Change to rented
updated = change_vehicle_ownership(
"550e8400-e29b-41d4-a716-446655440000",
"rented"
)
print(f"Updated: {updated['license_plate']} now {updated['ownership']}")
Update Fuel Type and Recalculate Emissions
Switch a vehicle to electric fuel to see emissions change:def switch_to_electric(vehicle_id, electric_fuel_id):
"""Switch vehicle to electric fuel"""
payload = {"vehicle_fuel_id": electric_fuel_id}
response = requests.patch(
f"https://api.dcycle.io/v1/vehicles/{vehicle_id}",
headers=headers,
json=payload
)
vehicle = response.json()
return {
"vehicle_id": vehicle["id"],
"new_fuel": "electric",
"co2e": vehicle["co2e"]
}
# Get electric fuel ID first, then switch
electric_vehicle = switch_to_electric(
"550e8400-e29b-41d4-a716-446655440000",
"880e8400-e29b-41d4-a716-446655440000"
)
print(f"New CO2e after electric switch: {electric_vehicle['co2e']} kg")
Update Multiple Vehicles Simultaneously
Update vehicles in bulk:def bulk_update_vehicles(updates):
"""Update multiple vehicles with new information"""
results = []
for vehicle_id, update_payload in updates.items():
response = requests.patch(
f"https://api.dcycle.io/v1/vehicles/{vehicle_id}",
headers=headers,
json=update_payload
)
if response.status_code == 200:
results.append(response.json())
else:
print(f"Failed to update vehicle {vehicle_id}")
return results
# Bulk update example
updates = {
"550e8400-e29b-41d4-a716-446655440000": {
"registration_year": 2023,
"market_segment": "executive"
},
"550e8400-e29b-41d4-a716-446655440001": {
"ownership": "rented",
"name": "Rental Van"
}
}
updated_vehicles = bulk_update_vehicles(updates)
print(f"Updated {len(updated_vehicles)} vehicles")
Rename Vehicle Fleet
Update vehicle names for better organization:def rename_vehicle(vehicle_id, new_name):
"""Rename a vehicle"""
response = requests.patch(
f"https://api.dcycle.io/v1/vehicles/{vehicle_id}",
headers=headers,
json={"name": new_name}
)
return response.json()
# Rename vehicles
rename_vehicle(
"550e8400-e29b-41d4-a716-446655440000",
"Executive Car - Spain HQ"
)
Related Endpoints
List Vehicles
Retrieve all vehicles with filtering and pagination
Create Vehicle
Add a new vehicle to your fleet
Delete Vehicle
Remove a vehicle from your fleet
Vehicle Fuels
Get available fuel types
Was this page helpful?