Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt

Use this file to discover all available pages before exploring further.

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
  • 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: 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.

​
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.