Bulk Upload Vehicles
Bulk Upload Vehicles
Get a presigned URL to upload multiple vehicles via CSV
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
Asynchronous processing
The system processes your file in the background, creating vehicles and validating data
Verify results
Check your fleet with the List Vehicles endpoint
Step 1: Request Presigned URL
Request
Headers
Your API key for authenticationExample:
sk_live_1234567890abcdefYour organization UUIDExample:
ff4adcc7-8172-45fe-9cf1-e90a6de53aa9Your user UUIDExample:
a1b2c3d4-e5f6-7890-abcd-ef1234567890Body Parameters
Name of the CSV file you’re going to uploadExample:
"company_fleet_2024.csv"Response
Presigned S3 URL to upload the vehicles file
Sanitized file name (alphanumeric only)
File UUID for tracking
Full S3 key where file will be stored
Confirmation message
Example
Successful Response
Step 2: Upload CSV to S3
Use the presigned URL to upload your CSV file directly to S3:CSV Format
The CSV must follow this structure for creating vehicles:Required Columns
| Column | Description | Valid Values | Example |
|---|---|---|---|
type | Vehicle usage type | passenger, freight | "freight" |
ownership | Ownership status | owned, rented | "owned" |
country | ISO 3166-1 alpha-2 country code | ES, FR, DE, etc. | "ES" |
is_known | Whether from known database | true, false | true |
Optional Columns
| Column | Description | Example |
|---|---|---|
name | Vehicle name or description | "Company Van #1" |
license_plate | License plate number | "1234-ABC" |
known_vehicle_id | UUID from known vehicles database (if is_known: true) | UUID string |
vehicle_fuel_id | UUID of fuel type | UUID string |
registration_year | Year first registered | 2020 |
market_segment | Market segment (for passenger vehicles) | mini, supermini, executive, etc. |
size | Vehicle size classification | small_car, medium, large_car, average_car |
Column Details
is_known:true: Vehicle from Dcycle’s known vehicles database. Must provideknown_vehicle_id.false: Custom vehicle. System will create an unknown vehicle entry.
passenger: Company cars, executive vehicles, personal usefreight: Delivery vans, trucks, commercial vehicles
owned: Vehicles owned by your organizationrented: Leased or rented vehicles
mini- City carssupermini- Small carslower_medium- Compact carsupper_medium- Mid-size carsexecutive- Large carsluxury- Premium carssports- Sports carsdual_purpose_4x4- SUVsmpv- Minivans
Download Template
Download CSV Template
Template with correct format and sample data
Step 3: Asynchronous Processing
Once the CSV is uploaded:- Validation: The system validates format, vehicle IDs, and data
- Processing: Each row is processed and vehicles are created
- Emission Calculation: CO2e values initialized to 0 (updated when consumption data is added)
- 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
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
| Limit | Value |
|---|---|
| Maximum file size | 100 MB |
| Maximum rows per CSV | 10,000 |
| URL expiration time | 15 minutes |
| Processing time | ~1 second per 50 vehicles |
Best Practices
Data Preparation
- Clean license plates: Remove special characters, use consistent format
- Validate vehicle IDs: Check that
known_vehicle_idexists before upload - Consistent naming: Use standardized vehicle names (e.g., “Van #1”, “Van #2”)
- Complete data: Include as many optional fields as possible for better reporting
Error Handling
After upload, check for vehicles withstatus: "error":
Incremental Updates
To update existing vehicles or add new ones:- Export current fleet to CSV
- Modify or add rows
- 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.)
- 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.0initially (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 withtype: "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
Related Endpoints
List Vehicles
View uploaded vehicles
Create Invoice
Add fuel consumption data
List Facilities
View your facilities
Authentication
Learn about API authentication

