Skip to main content
PATCH
Update Vehicle
← 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.
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-446655440000

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body 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: 2023
string
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 freight
string
Ownership type: owned or rented
string
Vehicle registration/license plate number
string
ISO 3166-1 country code
string
Current status: active, archived, or error
number
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
Available fuel units for this vehicle’s fuel type
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 error
string | 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

Successful Response

Common Errors

401 Unauthorized

Cause: Missing or invalid API key
Solution: Verify your API key is valid and active. Get a new one in Company settings → API Keys.

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).
Solution: Send the request from the parent organization (x-organization-id) with a user session, and pick the target among its subsidiaries.

404 Not Found

Cause: Vehicle not found in organization
Solution: Verify that the vehicle ID is correct and belongs to your organization. Use the List Vehicles endpoint to get valid IDs.

422 Validation Error

Cause: Invalid values for enumerated fields
Solution: Ensure enum values are exactly as specified. Use valid country codes (2-3 characters) and permitted values for 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)

Use Cases

Update Vehicle Ownership Status

Change vehicle ownership from owned to rented:

Update Fuel Type and Recalculate Emissions

Switch a vehicle to electric fuel to see emissions change:

Update Multiple Vehicles Simultaneously

Update vehicles in bulk:

Rename Vehicle Fleet

Update vehicle names for better organization:

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