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

import requests

url = "https://api.dcycle.io/v1/vehicles"

payload = {
    "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>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/vehicles \
  --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>",
  "unknown_vehicle_id": "<string>",
  "country": "<string>",
  "vehicle_fuel_id": "<string>",
  "custom_emission_factor_id": "<string>",
  "registration_year": 123,
  "market_segment": "<string>",
  "size": "<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": {}
}

POST

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

import requests

url = "https://api.dcycle.io/v1/vehicles"

payload = {
    "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>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/vehicles \
  --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>",
  "unknown_vehicle_id": "<string>",
  "country": "<string>",
  "vehicle_fuel_id": "<string>",
  "custom_emission_factor_id": "<string>",
  "registration_year": 123,
  "market_segment": "<string>",
  "size": "<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": {}
}

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/unknown-vehicles
Fuel type IDs from /v1/vehicle-fuels

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Body Parameters

string

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

string

required

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

string

required

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

string

required

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

uuid

required

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

string

required

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

uuid

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

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"

integer

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

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"

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

number

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

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id,
    "Content-Type": "application/json"
}

payload = {
    "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"
}

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

vehicle = response.json()
print(f"Vehicle created: {vehicle['id']}")
print(f"CO2e: {vehicle['co2e']} kg")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId,
  'Content-Type': 'application/json'
};

const payload = {
  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"
};

axios.post(
  'https://api.dcycle.io/v1/vehicles',
  payload,
  { headers }
)
.then(response => {
  const vehicle = response.data;
  console.log(`Vehicle created: ${vehicle.id}`);
  console.log(`CO2e: ${vehicle.co2e} kg`);
})
.catch(error => console.error(error));

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",
  "vehicle_fuel": "diesel",
  "vehicle_fuel_units": [
    { "id": "unit-uuid", "name": "litres", "type": "volume" }
  ],
  "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
  "unknown_vehicle_type": null,
  "custom_emission_factor_id": null,
  "registration_year": 2022,
  "market_segment": "upper_medium",
  "size": "medium",
  "error_messages": null,
  "file_id": null,
  "file_name": null,
  "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

​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