Skip to main content
The Bill Upload Auto Onboarding API endpoint simplifies the onboarding process by allowing you to upload utility bill PDFs instead of asking users to identify a rate plan themselves. 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 utility and rate-plan lookup 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": "<selected ratePlans[].id>",

  // 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 (5-digit; ZIP+4 like 53717-1125 is accepted and normalized)
  • customerClass: The customer class - residential, commercial, or industrial
  • billPDFs: Array of URLs pointing to the utility bill PDF(s). URLs must be https:// and publicly reachable, each PDF 10MB or smaller, maximum 5 PDFs per request

​
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: Optional. If you already called /v1/utility/get, choose the correct entry from ratePlans and pass that plan’s ratePlans[].id value. The returned ratePlans[].rateID field is the semantic tariff reference; ratePlans[].id is the value to send here.

​
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 field id is the newly created home ID, shown as homeId in later requests. The status indicates whether the bill processing is complete. Once processing is complete, you can immediately start receiving Price Signal data.

​
Checking Processing Status

Poll the status endpoint with the returned home ID: [POST] /v1/homes/bill-upload/{homeId}/status 
{
  "id": "ws_home_7bc31940df8a4615b2dc9e84f3a92c51",
  "status": "completed", // processing | completed | failed
  "utilityId": "14328",
  "ratePlanId": "<matched ratePlans[].id>",
  "pendingReason": null,
  "failureReason": null,
  "warnings": ["BILL_PDF_DROPPED:https://example.com/bill2.pdf:FILE_TOO_LARGE"]
}
While the rate plan is still being identified (or being added to our database), status stays processing and pendingReason explains why (for example RATE_PLAN_NOT_MATCHED during the 24-hour resolution window) — a populated pendingReason is informational, not an error. failed is reserved for unrecoverable problems with the uploaded files (for example, a URL that does not return a readable PDF); failureReason is only non-null when status is failed. The optional warnings array lists non-fatal anomalies, such as individual PDFs that were skipped while the rest of the upload succeeded.

​
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 ProcessBill Upload Process
1. Call utility/get to fetch utilities and rate plansSingle API call with bill PDFs
2. Call homes/create to create the home
3. Call solar/create (if applicable)
4. Wait for rate plan verificationAutomatic 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.