Skip to main content
POST
Bulk Upload Vehicles

Bulk Upload Vehicles

Upload hundreds of vehicles at once via a CSV file. This endpoint returns a presigned S3 URL so you can upload your file, which will be processed asynchronously.
This method is recommended for bulk uploads. Vehicles are persisted in the database and emissions are calculated automatically based on consumption data.

Upload Flow

1

Request presigned URL

Make a POST request to /api/v1/vehicles/bulk/csv with your file name
2

Upload to S3

Use the presigned URL to upload your CSV directly to S3 (PUT request)
3

Asynchronous processing

The system processes your file in the background, creating vehicles and validating data
4

Verify results

Check your fleet with the List Vehicles endpoint

Step 1: Request Presigned URL

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Body Parameters

string
required
Name of the CSV file you’re going to uploadExample: "company_fleet_2024.csv"

Response

string
Presigned S3 URL to upload the vehicles file
string
Sanitized file name (alphanumeric only)
string
File UUID for tracking
string
Full S3 key where file will be stored
string
Confirmation message

Example

Successful Response

Step 2: Upload CSV to S3

Use the presigned URL to upload your CSV file directly to S3:
The presigned URL expires in 15 minutes. Make sure to upload the file within that time.

CSV Format

The CSV must follow this structure for creating vehicles:

Required Columns

Optional Columns

Column Details

is_known:
  • true: Vehicle from Dcycle’s known vehicles database. Must provide known_vehicle_id.
  • false: Custom vehicle. System will create an unknown vehicle entry.
type:
  • passenger: Company cars, executive vehicles, personal use
  • freight: Delivery vans, trucks, commercial vehicles
ownership:
  • owned: Vehicles owned by your organization
  • rented: Leased or rented vehicles
market_segment (optional, for passenger vehicles):
  • mini - City cars
  • supermini - Small cars
  • lower_medium - Compact cars
  • upper_medium - Mid-size cars
  • executive - Large cars
  • luxury - Premium cars
  • sports - Sports cars
  • dual_purpose_4x4 - SUVs
  • mpv - Minivans

Download Template

Download CSV Template

Template with correct format and sample data

Step 3: Asynchronous Processing

Once the CSV is uploaded:
  1. Validation: The system validates format, vehicle IDs, and data
  2. Processing: Each row is processed and vehicles are created
  3. Emission Calculation: CO2e values initialized to 0 (updated when consumption data is added)
  4. Notification: (Coming soon) You’ll receive a webhook when complete
Processing can take from a few seconds to several minutes depending on file size.

Step 4: Verify Results

After processing, you can query your vehicles:

Complete Example Script

Common Errors

400 Bad Request - Missing file_name

Cause: Field required
Solution: Include the file_name parameter in the request body.

403 Forbidden - URL Expired

Cause: The presigned URL expired (15 minutes) Solution: Request a new presigned URL and upload the file immediately.

422 Validation Error - CSV Format

Cause: The CSV has incorrect format or missing required columns Solution: Verify that your CSV has all required columns (type, ownership, country, is_known) and correct format.

422 Validation Error - Invalid Vehicle ID

Cause: known_vehicle_id doesn’t exist in the known vehicles database Solution: Use the Known Vehicles endpoint to get valid vehicle IDs, or set is_known: false to create a custom vehicle.

Limits and Recommendations

For very large fleets (>10k vehicles), consider splitting them into multiple smaller CSVs.

Best Practices

Data Preparation

  1. Clean license plates: Remove special characters, use consistent format
  2. Validate vehicle IDs: Check that known_vehicle_id exists before upload
  3. Consistent naming: Use standardized vehicle names (e.g., “Van #1”, “Van #2”)
  4. Complete data: Include as many optional fields as possible for better reporting

Error Handling

After upload, check for vehicles with status: "error":

Incremental Updates

To update existing vehicles or add new ones:
  1. Export current fleet to CSV
  2. Modify or add rows
  3. Re-upload (existing vehicles will be updated by license plate)

Special Notes

Known vs Unknown Vehicles

Known Vehicles (is_known: true):
  • Must provide valid known_vehicle_id
  • Emission factors are based on manufacturer data
  • Includes detailed specifications (engine size, power, etc.)
Unknown Vehicles (is_known: false):
  • System creates generic vehicle entry
  • Emission factors based on vehicle type and fuel
  • Less accurate but flexible for custom vehicles

Vehicle Status After Upload

Vehicles created via CSV will have:
  • status: "active" if successful, "error" if validation failed
  • co2e: 0.0 initially (updated when consumption data is added)
  • created_at: Upload timestamp

Adding Consumption Data

After creating vehicles, add fuel consumption data using the Create Invoice endpoint with type: "recharge" for electric vehicles or facility fuels for combustion vehicles.

Country Codes

Use ISO 3166-1 alpha-2 country codes:
  • Spain: ES
  • France: FR
  • Germany: DE
  • United Kingdom: GB
  • United States: US

List Vehicles

View uploaded vehicles

Create Invoice

Add fuel consumption data

List Facilities

View your facilities

Authentication

Learn about API authentication