Create Vehicle

Create a new vehicle in your organization’s fleet. The system will automatically calculate CO2e emissions based on the vehicle’s characteristics.

Required Setup: Before creating a vehicle, ensure you have retrieved the necessary references:

Unknown vehicle type IDs from /v1/vehicles/unknown
Fuel type IDs from /v1/vehicles/fuels

Request

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

name

string

Custom name or alias for the vehicleExample: "Company Fleet Car #1"

type

string

required

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

ownership

string

required

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

license_plate

string

required

Vehicle registration/license plate numberExample: "ABC-1234"

unknown_vehicle_id

uuid

required

UUID of the unknown vehicle type for categorizationRetrieve available options from GET /v1/vehicles/unknownExample: "550e8400-e29b-41d4-a716-446655440000"

country

string

required

ISO 3166-1 country code (2-3 characters) for regional emission calculationsExamples: "US", "GB", "ES", "DE"

vehicle_fuel_id

uuid

UUID of the vehicle fuel type (required if custom_emission_factor_id not provided)Retrieve available options from GET /v1/vehicles/fuelsExamples: petrol, diesel, electric, hybridExample: "660e8400-e29b-41d4-a716-446655440000"

custom_emission_factor_id

uuid

UUID of a custom emission factor (required if vehicle_fuel_id not provided)For organizations with custom emission dataExample: "770e8400-e29b-41d4-a716-446655440000"

registration_year

integer

Year of vehicle registration (YYYY format)Used for age-based emission factors and vehicle classificationExample: 2022

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"

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 of the vehicle (newly created vehicles are active)

co2e

number

Calculated 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 POST "https://api.dcycle.io/v1/vehicles" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Fleet Car #1",
    "type": "passenger",
    "ownership": "owned",
    "license_plate": "ABC-1234",
    "country": "ES",
    "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
    "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000",
    "registration_year": 2022,
    "market_segment": "upper_medium",
    "size": "medium"
  }'

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Company Fleet Car #1",
  "type": "passenger",
  "ownership": "owned",
  "license_plate": "ABC-1234",
  "country": "ES",
  "status": "active",
  "co2e": 245.5,
  "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000",
  "unknown_vehicle_type": null,
  "registration_year": 2022,
  "market_segment": "upper_medium",
  "size": "medium",
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30: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: Organization not found or invalid UUID reference

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

Solution: Verify that the x-organization-id header contains a valid organization UUID, and that the unknown_vehicle_id and vehicle_fuel_id are valid.

422 Validation Error

Cause: Missing required parameters or invalid values

{
  "detail": [
    {
      "loc": ["body", "vehicle_fuel_id"],
      "msg": "Either vehicle_fuel_id or custom_emission_factor_id must be provided",
      "type": "value_error"
    }
  ]
}

Solution: Ensure all required fields are provided. Either vehicle_fuel_id or custom_emission_factor_id must be specified. Country code should be 2-3 characters.

Use Cases

Add a Passenger Vehicle to Fleet

Create a new company car with full details:

def add_company_car(license_plate, registration_year, fuel_type_id):
    """Add a new passenger vehicle to the fleet"""
    payload = {
        "name": f"Company Car - {license_plate}",
        "type": "passenger",
        "ownership": "owned",
        "license_plate": license_plate,
        "country": "ES",
        "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
        "vehicle_fuel_id": fuel_type_id,
        "registration_year": registration_year,
        "market_segment": "upper_medium"
    }

    response = requests.post(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        json=payload
    )

    return response.json()

# Add vehicle
vehicle = add_company_car("ABC-1234", 2022, "660e8400-e29b-41d4-a716-446655440000")
print(f"Created vehicle with CO2e: {vehicle['co2e']} kg")

Register a Fleet Vehicle with Custom Emissions

Add a vehicle using a custom emission factor:

def add_custom_vehicle(license_plate, custom_factor_id):
    """Add a vehicle with custom emission factor"""
    payload = {
        "name": f"Fleet Vehicle - {license_plate}",
        "type": "freight",
        "ownership": "owned",
        "license_plate": license_plate,
        "country": "ES",
        "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440001",
        "custom_emission_factor_id": custom_factor_id,
        "size": "large_car"
    }

    response = requests.post(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        json=payload
    )

    return response.json()

Bulk Add Multiple Vehicles

Add multiple vehicles in a batch operation:

def bulk_add_vehicles(vehicles_data):
    """Add multiple vehicles to the fleet"""
    created_vehicles = []

    for vehicle_info in vehicles_data:
        response = requests.post(
            "https://api.dcycle.io/v1/vehicles",
            headers=headers,
            json=vehicle_info
        )

        if response.status_code == 201:
            created_vehicles.append(response.json())
        else:
            print(f"Failed to create vehicle: {response.text}")

    return created_vehicles

# Bulk add vehicles
vehicles = [
    {
        "name": "Vehicle 1",
        "type": "passenger",
        "ownership": "owned",
        "license_plate": "ABC-1234",
        "country": "ES",
        "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
        "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000"
    },
    {
        "name": "Vehicle 2",
        "type": "freight",
        "ownership": "rented",
        "license_plate": "XYZ-5678",
        "country": "ES",
        "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440001",
        "vehicle_fuel_id": "760e8400-e29b-41d4-a716-446655440000"
    }
]

created = bulk_add_vehicles(vehicles)
print(f"Created {len(created)} vehicles")

List Vehicles

Retrieve all vehicles with filtering and pagination

Update Vehicle

Modify vehicle details

Unknown Vehicles

Get available vehicle types

Vehicle Fuels

Get available fuel types

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Create Vehicle

Create Vehicle

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Add a Passenger Vehicle to Fleet

Register a Fleet Vehicle with Custom Emissions

Bulk Add Multiple Vehicles

List Vehicles

Update Vehicle

Unknown Vehicles

Vehicle Fuels

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

​Create Vehicle

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Add a Passenger Vehicle to Fleet

​Register a Fleet Vehicle with Custom Emissions

​Bulk Add Multiple Vehicles

​Related Endpoints

List Vehicles

Update Vehicle

Unknown Vehicles

Vehicle Fuels

Create Vehicle

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Add a Passenger Vehicle to Fleet

Register a Fleet Vehicle with Custom Emissions

Bulk Add Multiple Vehicles

Related Endpoints