Import¶

The Import API supports bulk data ingestion via CSV files and batch PDF uploads. Use these endpoints to onboard properties and bills at scale. All endpoints require authentication and are prefixed with /import.

GET /import/template¶

Download a CSV template for bulk property import. The template includes all supported columns with header descriptions.


Auth required	Yes

Example Request¶

curl -o property_import_template.csv \
  https://app.meterbase.io/api/v1/import/template \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK (Content-Type: text/csv)

name,address,city,state,zip_code,property_type,sqft,unit_count,year_built,portfolio_id,utility_account_number,meter_number,monthly_usage_kwh,monthly_demand_kw,has_solar,solar_capacity_kw
Sunset Apartments,123 Main St,Los Angeles,CA,90001,residential,24000,32,1998,pf_abc123,,,,,,
Harbor View Plaza,456 Ocean Ave,Santa Monica,CA,90401,commercial,85000,,2005,pf_abc123,,,,,,

Template Columns

The only required columns are name, address, city, state, zip_code, and property_type. All other columns are optional and can be left blank.

POST /import/properties¶

Upload a CSV file to create multiple properties in one request.


Auth required	Yes
Content-Type	`multipart/form-data`

Request Body (Form Data)¶

Field	Type	Required	Description
`file`	file	Yes	CSV file following the template format (max 5 MB)
`portfolio_id`	string	No	Default portfolio for all imported properties (can be overridden per row in the CSV)

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/import/properties \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/properties.csv" \
  -F "portfolio_id=pf_abc123"

Example Response¶

200 OK

{
  "total_rows": 25,
  "imported": 23,
  "failed": 2,
  "properties_created": [
    {
      "row": 1,
      "id": "prop_imp_001",
      "name": "Sunset Apartments"
    },
    {
      "row": 2,
      "id": "prop_imp_002",
      "name": "Harbor View Plaza"
    }
  ],
  "errors": [
    {
      "row": 14,
      "field": "state",
      "message": "Invalid state code: 'California'. Use 2-letter code (e.g., 'CA')."
    },
    {
      "row": 22,
      "field": "zip_code",
      "message": "Invalid ZIP code format: '9001'. Must be 5 digits."
    }
  ]
}

Partial Success

The import processes all valid rows even if some rows fail. Check the errors array for details on failed rows.

Error Cases¶

Status	Detail	Cause
`400`	`"File must be a CSV"`	Non-CSV file uploaded
`400`	`"File too large (max 5 MB)"`	File exceeds size limit
`400`	`"CSV has no data rows"`	Empty CSV (headers only)
`422`	`"Missing required columns: name, address"`	Required columns missing from CSV header

POST /import/bills¶

Upload multiple utility bill PDFs in a single request. Each PDF is processed using AI extraction and linked to the specified property.


Auth required	Yes
Content-Type	`multipart/form-data`

Request Body (Form Data)¶

Field	Type	Required	Description
`files`	file[]	Yes	One or more PDF files (max 10 MB each, max 20 files per request)
`property_id`	string	Yes	Property ID to associate all uploaded bills with

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/import/bills \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@/path/to/bill_jan.pdf" \
  -F "files=@/path/to/bill_feb.pdf" \
  -F "files=@/path/to/bill_mar.pdf" \
  -F "property_id=prop_abc123"

Example Response¶

200 OK

{
  "total_files": 3,
  "processed": 3,
  "succeeded": 2,
  "failed": 1,
  "bills_created": [
    {
      "filename": "bill_jan.pdf",
      "bill_id": "bill_imp_001",
      "billing_period": "2026-01-01 to 2026-01-31",
      "total_amount": 2980.50,
      "confidence": 0.96
    },
    {
      "filename": "bill_feb.pdf",
      "bill_id": "bill_imp_002",
      "billing_period": "2026-02-01 to 2026-02-28",
      "total_amount": 3247.85,
      "confidence": 0.93
    }
  ],
  "errors": [
    {
      "filename": "bill_mar.pdf",
      "message": "Could not extract bill data. File may be scanned at low resolution."
    }
  ]
}

Processing Time

Each PDF is processed through the AI extraction pipeline. Expect 5-15 seconds per file. For large batches, the request may take several minutes.

Error Cases¶

Status	Detail	Cause
`400`	`"All files must be PDFs"`	Non-PDF file in the batch
`400`	`"Maximum 20 files per request"`	Too many files
`400`	`"File too large (max 10 MB): bill_mar.pdf"`	Individual file exceeds limit
`404`	`"Property not found"`	Invalid `property_id`