Data Imports

Data Imports: Event File Uploads

Backfill usage events in bulk by uploading CSV files. Use this when migrating historical usage into Solvimon, or when catching up after a gap in your event pipeline.

Why this matters

File uploads are primarily intended to backfill data: importing historical usage during a migration, or repairing a gap after an outage. For ongoing, real-time usage reporting, use the Event Ingestion API instead; it validates and matches events as they happen.

How it works

Every event you ingest is matched to a meter, and every field that meter expects must be populated for the event to be accepted. Because the required columns depend on the meter, Solvimon generates a CSV template per meter with the correct headers: customer reference, event reference, timestamp, and the meter’s value and property references.

You download the template, fill it with your event data, and upload it as a file. Solvimon processes the file line by line; each valid line becomes a usage event, and invalid lines are reported so you can correct and re-upload them. The same validation applies as with API ingestion.

Implementation

Via API

1

Download the CSV template for your meter

Retrieve the template with the meter data file endpoint:

Download template
$curl https://test.api.solvimon.com/v1/meters/{meter_id}/meter-data-file \
>  -H "X-API-KEY: <apiKey>"

The response is a CSV file containing the headers required for the meter.

You can also obtain this file by navigating to the file tab in Desk and selecting upload. After selecting a meter, an option will appear for downloading the template CSV.

Meter template download from file upload

For example:

Template response
1customer_reference,pricing_plan_subscription_id (optional),pricing_plan_subscription_reference (optional),reference (unique),timestamp (optional),meter_value.reference.event_count

The exact headers depend on the meter’s values and properties. Headers not marked as optional are required.

2

Fill the template with your event data

Add one row per usage event. Keep the template’s column headers and ordering unchanged, and make sure every event reference is unique. See timestamp formatting for the expected timestamp format.

3

Upload the file

Upload the completed CSV with the create file endpoint. The file content is sent BASE64 encoded, and meter_data.meter_id links the file to the meter it should be ingested against:

Upload file
$curl -X POST https://test.api.solvimon.com/v1/files \
>  -H "X-API-KEY: <apiKey>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "type": "METER_DATA",
>    "file_name": "usage-backfill-2026-06.csv",
>    "content_type": "text/csv",
>    "content": "Y3VzdG9tZXJfcmVmZXJlbmNlLGV2ZW50X3JlZm...",
>    "meter_data": {
>      "meter_id": "metr_61Sx9pqJnwo42rzGV7past"
>    }
>  }'
Response
1{
2  "object_type": "file",
3  "id": "file_51Qx2pqJnwo42rzGV7abcd",
4  "file_name": "usage-backfill-2026-06.csv",
5  "type": "METER_DATA",
6  "status": "CREATED",
7  "number_of_lines": 1250,
8  "created_at": "2026-06-30T09:41:00Z"
9}
4

Verify processing

Poll the file status until it reaches DONE:

Check file status
$curl https://test.api.solvimon.com/v1/files/{file_id} \
>  -H "X-API-KEY: <apiKey>"

If the status is ERROR, retrieve the individual file lines to see which rows failed and why:

Inspect failed lines
$curl https://test.api.solvimon.com/v1/files/{file_id}/lines \
>  -H "X-API-KEY: <apiKey>"

Successfully processed events appear on the Events page in Desk, matched to their meter.

Via Desk

The same flow is available in Desk under Files → Upload file (desk.solvimon.com/files/upload): selecting a meter shows a card from which you can download that meter’s template, and the upload screen tracks the processing status of each file. See the usage file uploads guide for the full Desk walkthrough.

CSV formatting

Solvimon assumes the following CSV formatting. If your files are formatted differently, contact us before uploading.

CSV formatting propertyDescription
DelimiterThe character delimiting individual cells in the CSV data. This may only be a 1-character string. For tab-delimited data enter \\t. By default we assume this to be ,.
Double QuoteWhether two consecutive quote characters within a quoted value represent a single quote character. By default we assume this to be the case.
EncodingThe character encoding of the CSV data. By default we assume this to be utf8.
Escape CharacterThe character used for escaping special characters. By default we disallow escaping.
False ValuesA set of case-sensitive strings that should be interpreted as false values. By default this is set to the following set: n, no, f, false, off, 0.
True ValuesA set of case-sensitive strings that should be interpreted as true values. By default this is set to the following set: y, yes, t, true, on, 1.
Null ValuesA set of case-sensitive strings that should be interpreted as null values. By default we interpret NA as a null value.
Quote CharacterThe character used for quoting CSV values. By default we assume this to be using double quoting ".

Edge cases

  • Custom column names and ordering. If you can’t produce files matching the template exactly, contact us to set up a custom mapping so your files are processed according to your own format.
  • Backfilling near a billing period close. Usage can only be ingested while the invoice for that period is still editable. If you are backfilling data for a period that is about to close, review the timing considerations before uploading.

Do not change the column headers from the template. The headers are how Solvimon maps your data to the meter; a file with modified headers will not be accepted.