Bulk Vehicle Import (CSV)

The bulk import feature allows you to add multiple vehicles to your fleet at once using a CSV file. This is ideal for initial fleet setup, fleet expansions, or migrating from another system.

Accessing the Import Feature

Navigate to Dashboard > Vehicles
Click Import CSV button in the top-right corner
The import dialog will open

CSV File Requirements

File Format

Format: CSV (Comma-Separated Values)
Encoding: UTF-8 (recommended)
Delimiter: Comma (,)
Header Row: First row must contain column names

Required Columns

Only one column is required:

Column	Description	Example
`vehicle_number`	Unique identifier for the vehicle	"VH-001", "SCOOTER-123"

Important

Each vehicle must have a unique vehicle_number. Duplicates will update existing records rather than create new ones.

Optional Columns (Actively Imported)

These columns are fully supported by the import function:

Column	Description	Example
`vehicle_model_id`	Model ID (numeric) or model name (text)	"1" or "Levy Max"
`vehicle_model`	Model name (alternative to vehicle_model_id)	"Levy Max Pro"
`iot_imei`	IMEI of linked IoT device	"123456789012345"
`vin`	Vehicle Identification Number	"1HGBH41JXMN109186"

Default Values on Import

When vehicles are imported, the following defaults are set:

Field	Default Value
`status`	"offline"
`battery_level`	0
`iot_battery_pct`	0
`vehicle_odometer`	"0"

Note

To set additional values like battery levels, GPS coordinates, or custom statuses, update vehicles individually after import or use the API.

Sample CSV Templates

Minimal Template

vehicle_number
VH-001
VH-002
VH-003
VH-004
VH-005

Basic Template with IoT

vehicle_number,iot_imei,vehicle_model
VH-001,123456789012345,Levy Max
VH-002,123456789012346,Levy Max
VH-003,123456789012347,Levy Max Pro
VH-004,123456789012348,Levy Max Pro
VH-005,123456789012349,Segway E22

Full Template

vehicle_number,vehicle_model,iot_imei,vin
VH-001,Levy Max,123456789012345,1HGBH41JXMN109186
VH-002,Levy Max,123456789012346,1HGBH41JXMN109187
VH-003,Levy Max Pro,123456789012347,1HGBH41JXMN109188
VH-004,Levy Max Pro,123456789012348,1HGBH41JXMN109189
VH-005,Segway E22,123456789012349,1HGBH41JXMN109190

Status Note

All imported vehicles start with status "offline". Update individual vehicle statuses after import via the dashboard or API.

Import Process

Step 1: Prepare Your CSV File

Create a CSV file following the format above
Ensure vehicle_number column is present and all values are unique
Verify data accuracy before import

Step 2: Upload the File

Click Import CSV on the Vehicles page
Select your CSV file
The system will parse and validate the file

Step 3: Review Preview

Before importing, you'll see:

Number of vehicles to import
Any validation errors
Warnings about potential issues

Step 4: Confirm Import

Click Import to proceed
Wait for the import to complete
Review the results summary

Step 5: Verify Results

After import, you'll see:

Imported count: Successfully added/updated vehicles
Failed count: Vehicles that couldn't be imported
Failure details: Specific errors for failed rows

How Import Handles Existing Vehicles

The import uses "upsert" logic (update or insert):

New Vehicles

If vehicle_number doesn't exist, a new vehicle is created
Vehicle is assigned to the selected subaccount
Initial status is set to "offline"

Existing Vehicles

If vehicle_number already exists, the record is updated
Only provided fields are updated
Existing data for unprovided fields is preserved
updated_at timestamp is refreshed

Example: If you import a CSV with just vehicle_number and iot_imei for an existing vehicle, only the iot_imei is updated - all other fields remain unchanged.

Linking IoT Devices During Import

Automatic Linking

When you provide an iot_imei in your CSV:

The system looks for an existing IoT device with that IMEI
If found and unlinked, it associates with the vehicle
If found and already linked to another vehicle, the import may fail for that row

Best Practice

Create IoT devices first via the IoT Devices page
Note the IMEI for each device
Include IMEIs in your vehicle import CSV
Devices will be automatically linked

Specifying Vehicle Models

You can specify the vehicle model in two ways:

By Model ID

If you know the model ID (from the Vehicle Models page):

vehicle_number,vehicle_model_id
VH-001,123
VH-002,123
VH-003,456

By Model Name

You can use the model name instead:

vehicle_number,vehicle_model_id
VH-001,Levy Max
VH-002,Levy Max
VH-003,Levy Max Pro

Or use the vehicle_model column:

vehicle_number,vehicle_model
VH-001,Levy Max
VH-002,Levy Max
VH-003,Levy Max Pro

The import function will attempt to match by name if a numeric ID isn't provided.

Error Handling

Common Validation Errors

Error	Cause	Solution
"Vehicle number is required"	Empty or missing vehicle_number	Ensure all rows have vehicle_number
"Invalid IMEI format"	IMEI not 15 digits	Check IMEI format
"Model not found"	Model ID/name doesn't exist	Create the model first or fix the name
"Duplicate vehicle number"	Same vehicle_number in CSV twice	Remove duplicate rows

Partial Import Behavior

Import is not atomic - successful rows are imported even if some fail
Failed rows are reported with specific error messages
You can fix failed rows and re-import (updates are safe)

API Reference

Endpoint

POST /api/vehicles/import

Request Body

{
  "csv_data": [
    {
      "vehicle_number": "VH-001",
      "iot_imei": "123456789012345",
      "vehicle_model": "Levy Max"
    },
    {
      "vehicle_number": "VH-002",
      "iot_imei": "123456789012346",
      "vehicle_model": "Levy Max"
    }
  ],
  "subaccount_id": "uuid-of-target-subaccount"
}

Response

{
  "success": true,
  "message": "Successfully imported 2 vehicle(s)",
  "imported_count": 2,
  "failed_count": 0,
  "failures": [],
  "results": [
    {
      "success": true,
      "vehicle_uuid": "uuid-1",
      "vehicle_number": "VH-001",
      "error_message": null
    },
    {
      "success": true,
      "vehicle_uuid": "uuid-2",
      "vehicle_number": "VH-002",
      "error_message": null
    }
  ]
}