Skip to main content
POST
Bulk Upload Vehicle Consumptions

Bulk Upload Vehicle Consumptions

Upload hundreds of vehicle fuel consumption records 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. Consumption records are persisted in the database and emissions are calculated automatically based on fuel type and quantity.

Upload Flow

1

Request presigned URL

Make a POST request to /api/v1/vehicle_consumptions/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 consumption records and calculating emissions
4

Verify results

Check consumption records with the List Vehicle Consumptions 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: "2024_vehicle_fuel_records.csv"

Response

string
Presigned S3 URL to upload the consumption records 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 vehicle consumption records:

Required Columns

Optional Columns

Column Details

vehicle_id:
  • Must be a valid UUID from your vehicles list
  • Get valid vehicle IDs: GET /api/v1/vehicles
  • Vehicle must belong to your organization
quantity:
  • Must be positive number
  • No negative values allowed
  • Precision: up to 6 decimal places
unit_id:
  • Must be a valid UUID from the Units endpoint
  • Typically liquid units (L, gal) for combustion vehicles
  • Energy units (kWh) for electric vehicles
  • Get valid unit IDs: GET /api/v1/units
start_date & end_date:
  • Format: YYYY-MM-DD
  • Must be today or in the past
  • end_date must be >= start_date
  • Can be same day for single refueling events
  • Used to track consumption periods
custom_id (optional):
  • External reference for tracking
  • Examples: fuel card transaction ID, invoice number, receipt ID
  • Useful for reconciliation with fuel card systems
  • Max length: 255 characters
base_total_spend (optional):
  • Total monetary cost of the consumption
  • Negative values are accepted
  • Can be provided independently of currency_unit
currency_unit (optional):
  • Name of the currency for the spend amount
  • Must match a valid fiat currency unit name (e.g., euros_(eur), us_dollar_(usd), british_pound_(gbp))
  • Can be provided independently of base_total_spend
  • Get valid currency names: GET /api/v1/units?type=fiat_currency

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, units, and dates
  2. Processing: Each row is processed and consumption records are created
  3. Emission Calculation: CO2e values calculated using vehicle fuel type and emission factors
  4. Status Update: Records marked as active or error based on processing result
  5. Notification: (Coming soon) You’ll receive a webhook when complete
Processing can take from a few seconds to several minutes depending on file size and number of records.

Step 4: Verify Results

After processing, you can query consumption records for each vehicle:

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 (vehicle_id, quantity, unit_id, start_date, end_date) and correct format.

422 Validation Error - Invalid Vehicle ID

Cause: vehicle_id doesn’t exist or doesn’t belong to your organization Solution: Use the Vehicles endpoint to get valid vehicle IDs from your fleet.

422 Validation Error - Invalid Unit ID

Cause: unit_id doesn’t exist or is not compatible with vehicle fuel type Solution: Use the Units endpoint to get valid unit IDs. For liquid fuels use L, for electric use kWh.

422 Validation Error - Invalid Date

Cause: Date is in the future or incorrectly formatted Solution: Ensure all dates are today or in the past, and use YYYY-MM-DD format.

422 Validation Error - End Date Before Start Date

Cause: end_date is earlier than start_date Solution: Ensure end_date >= start_date.

Limits and Recommendations

For very large datasets (>100k records), consider splitting them into multiple smaller CSVs by vehicle or time period.

Best Practices

Data Preparation

  1. Get Vehicle IDs first: Query your vehicles before creating the CSV
  2. Get Unit IDs: Ensure unit IDs match vehicle fuel types (L for liquid fuels, kWh for electric)
  3. Validate dates: All dates must be today or in the past
  4. Use custom_id: Include external references (fuel card IDs) for reconciliation
  5. Group by refueling events: One row per refueling event or period

Error Handling

After upload, check for consumption records with status: "error":

Incremental Updates

To add new consumption records:
  1. Get latest consumption date for each vehicle
  2. Export new records from fuel card system
  3. Upload only new records (avoid duplicates)

Data Sources

Common sources for vehicle consumption data:
  • Fuel Card Systems: Transaction exports from providers (Shell, BP, Repsol)
  • Telematics: GPS fleet tracking systems with fuel monitoring
  • Manual Logs: Driver-reported fuel purchases
  • Accounting Systems: Fuel expense records
  • Electric Vehicle Charging: Charging station APIs or apps

Integration Examples

Fuel Card System Integration

Electric Vehicle Charging Integration

List Vehicle Consumptions

View uploaded consumption records

List Vehicles

Get vehicle IDs for your fleet

List Units

Get measurement units for consumptions

Authentication

Learn about API authentication