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>'
  })
};

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>"
}
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>"
}
'

{
  "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": {}
}

PATCH

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>'
  })
};

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>"
}
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>"
}
'

{
  "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

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 dataExample: "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 typeExample: "550e8400-e29b-41d4-a716-446655440001"

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

Show Fuel Unit Object

string

Unit UUID

string

Unit name (e.g. litre_(l), kilogram_(kg))

string

Unit category

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

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"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

404 Not Found

Cause: Vehicle not found in organization

{
  "code": "VEHICLE_NOT_FOUND",
  "detail": "Vehicle with id=UUID('...') not found"
}

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

{
  "detail": [
    {
      "loc": ["body", "type"],
      "msg": "value is not a valid enumeration member; permitted: 'passenger', 'freight'",
      "type": "type_error.enum"
    }
  ]
}

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.

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"
)

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

​Update Vehicle

​Request

​Path Parameters

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Update Vehicle Ownership Status

​Update Fuel Type and Recalculate Emissions

​Update Multiple Vehicles Simultaneously

​Rename Vehicle Fleet

​Related Endpoints

List Vehicles

Create Vehicle

Delete Vehicle

Vehicle Fuels

Update Vehicle

Request

Path Parameters

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Update Vehicle Ownership Status

Update Fuel Type and Recalculate Emissions

Update Multiple Vehicles Simultaneously

Rename Vehicle Fleet

Related Endpoints