Skip to main content
POST
/
v1
/
vehicles
Create Vehicle
const options = {
  method: 'POST',
  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>',
    unknown_vehicle_id: '<string>',
    country: '<string>',
    vehicle_fuel_id: '<string>',
    custom_emission_factor_id: '<string>',
    registration_year: 123,
    market_segment: '<string>',
    size: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/vehicles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "name": {},
  "type": "<string>",
  "ownership": "<string>",
  "license_plate": "<string>",
  "country": "<string>",
  "status": "<string>",
  "co2e": 123,
  "vehicle_fuel_id": {},
  "registration_year": {},
  "market_segment": {},
  "size": {},
  "created_at": {},
  "updated_at": {}
}

​
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

​
id
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