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

vehicle_id

uuid

required

The UUID of the vehicle to updateExample: 550e8400-e29b-41d4-a716-446655440000

Headers

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

All parameters are optional. Only include fields you want to update.

name

string

Custom name or alias for the vehicleExample: "Updated Fleet Car Name"

type

string

Type of vehicle usageAvailable values: passenger, freightExample: "passenger"

ownership

string

Vehicle ownership typeAvailable values: owned, rentedExample: "owned"

license_plate

string

Vehicle registration/license plate numberExample: "XYZ-9999"

country

string

ISO 3166-1 country code (2-3 characters)Examples: "US", "GB", "ES", "DE"Example: "ES"

vehicle_fuel_id

uuid

UUID of the vehicle fuel typeRetrieve available options from GET /v1/vehicles/fuelsExample: "660e8400-e29b-41d4-a716-446655440000"

custom_emission_factor_id

uuid

UUID of a custom emission factorFor organizations with custom emission dataExample: "770e8400-e29b-41d4-a716-446655440000"

registration_year

integer

Year of vehicle registration (YYYY format)Example: 2023

market_segment

string

Vehicle market segment for classificationAvailable values: mini, supermini, lower_medium, upper_medium, executive, luxury, sports, dual_purpose_4x4, mpvExample: "upper_medium"

size

string

Vehicle size categoryAvailable values: small_car, medium, large_car, average_carExample: "medium"

unknown_vehicle_id

uuid

UUID of the unknown vehicle typeExample: "550e8400-e29b-41d4-a716-446655440001"

Response

string

Unique identifier (UUID) for the vehicle

name

string | null

Custom name or alias for the vehicle

type

string

Type of vehicle usage: passenger or freight

ownership

string

Ownership type: owned or rented

license_plate

string

Vehicle registration/license plate number

country

string

ISO 3166-1 country code

status

string

Current status: active, archived, or error

co2e

number

Updated CO2 equivalent emissions in kg CO2e

vehicle_fuel_id

string | null

UUID of the fuel type

registration_year

integer | null

Year of vehicle registration

market_segment

string | null

Vehicle market segment classification

size

string | null

Vehicle size category

created_at

datetime

Timestamp when the vehicle was created

updated_at

datetime

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

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",
  "unknown_vehicle_type": null,
  "registration_year": 2023,
  "market_segment": "executive",
  "size": "medium",
  "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

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Update Vehicle

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

List Vehicles

Create Vehicle

Delete Vehicle

Vehicle Fuels

Introduction

Logistics

Vehicles

Unknown Vehicles

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

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