[Beta] Bill Upload Auto Onboarding

Onboard sites by uploading utility bills

The Bill Upload Auto Onboarding API endpoint simplifies the onboarding process by allowing you to upload utility bill PDFs instead of manually selecting rate plans. This single API call replaces the need to call utility/get, homes/create, and solar/create separately.

When to Use Bill Upload

The bill ingestion API is particularly useful if:

1. You prefer to collect utility bill PDFs instead of going through the manual rate plan selection process
2. You or your customer are having trouble determining which rate plan they are on
3. Our listed confidence level for that site’s rate plan is less than you are comfortable with
4. We don’t yet list the rate plan your customer is on

Rate Plan Database Updates

For any rate plan in the U.S. or Canada, if you upload a bill, we will ensure that rate plan is in our database and accurate. We often get this updated within an hour (but in no cases slower than 24 hours).

API Endpoint

[POST] /v1/homes/bill-upload

Request

{
  "name": "Your Site Name",
  "zipcode": "95313",
  "customerClass": "residential",  // residential | commercial | industrial
  "billPDFs": ["https://example.com/bill1.pdf", "https://example.com/bill2.pdf"],

  "solarSystemSizeKw": 5,
  "isNonNetMetered": false,

  // Optional fields
  "utilityEIAId": "14328",
  "ratePlanId": "662955dff338bcedec0dbfe7",

  // Optional fields (residential)
  "hasEvCharger": true,  // boolean | null | undefined
  "hasElectricHeater": false,
  "hasSmartWaterHeater": null,
  "hasElectricWaterHeater": true,
  "hasAC": true,
  "acType": "central",  // central | window | split | other

  // Optional fields (commercial & industrial)
  "peakDemand": 250  // kW
}

Request Fields

Required Fields

• name: The name of the site/home
• zipcode: The zip code of the site
• customerClass: The customer class - residential, commercial, or industrial
• billPDFs: Array of URLs pointing to the utility bill PDF(s)

Solar Fields

• solarSystemSizeKw: Size of the solar system in kilowatts
• isNonNetMetered: Boolean indicating if the solar system is non-net metered

Optional Fields

• utilityEIAId: The utility EIA ID (if known)
• ratePlanId: The rate plan ID (if known)

Residential Optional Fields

• hasEvCharger: Boolean indicating if the site has an EV charger
• hasElectricHeater: Boolean indicating if the site has an electric heater
• hasSmartWaterHeater: Boolean indicating if the site has a smart water heater
• hasElectricWaterHeater: Boolean indicating if the site has an electric water heater
• hasAC: Boolean indicating if the site has air conditioning
• acType: Type of AC system - central, window, split, or other

Commercial & Industrial Optional Fields

• peakDemand: Peak demand in kilowatts (kW)

Response

{
  "id": "ws_home_7bc31940df8a4615b2dc9e84f3a92c51",
  "status": "processing"  // processing | completed | failed
}

The response includes the home ID that was created. The status indicates whether the bill processing is complete. Once processing is complete, you can immediately start receiving Price Signal data.

Important Notes

Privately Negotiated Rate Plans: If the rate plan is privately negotiated (either PPA or with a retailer/ESCO in a deregulated context), we may need additional information to generate accurate tariff data. In such cases, our support team will reach out for clarification.

Bill Processing Time: While we typically process bills within an hour, it can take up to 24 hours in some cases. During this time, the site status will be processing. Once complete, the status will update to completed and you can begin using the site for price signals and optimizations.

Comparison with Multi-Step Onboarding

This single API call replaces the traditional multi-step onboarding process:

Traditional Process	Bill Upload Process
1. Call utility/get to fetch utilities and rate plans	Single API call with bill PDFs
2. Call homes/create to create the home
3. Call solar/create (if applicable)
4. Wait for rate plan verification	Automatic rate plan extraction and verification

The bill upload method is especially valuable when you want to streamline the user experience or when rate plan identification is challenging.