Create Vehicle - Dcycle Platform Docs

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

← Vehicles API Create a new vehicle in your organization’s fleet. Creating a vehicle calculates nothing: its emissions come from its consumptions, so co2e is 0 until it has some. To create many at once, use Create Vehicles (v2).

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 alpha-2 country code (e.g. ES), where the vehicle is used: it picks the emission factors of its consumptionsExamples: "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 dataDespite the name, this field holds the id of a custom emission group, not of an individual factor. Retrieve available options from GET /custom_emission_groups/lightExample: "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

Emissions of the vehicle’s consumptions in kg CO2e: 0 for a new vehicle

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 in Company settings → API Keys.

404 Not Found

Cause: The organization in x-organization-id does not exist

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

Solution: Verify the x-organization-id header. Take unknown_vehicle_id from List Unknown Vehicles and vehicle_fuel_id from List Vehicle Fuels: this route does not check them, and an id that does not exist fails the request. Create Vehicles (v2) checks every reference.

422 Validation Error

Cause: A missing required field or an invalid value, or a plate already in use

{
  "code": "LICENSE_PLATE_ALREADY_EXISTS",
  "detail": "A vehicle with the same license plate already exists."
}

Solution: Send every required field. A plate can be used by one enabled vehicle of the organization at a time (LICENSE_PLATE_ALREADY_EXISTS). custom_emission_factor_id and custom_ef_record_id are mutually exclusive.

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

​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

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