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

# [Beta] Bill Upload Auto Onboarding

> Onboard sites by uploading utility bills

<script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/46106422.js" />

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/docs/optimize_shifts_calculate_impacts/price_signal).

## Checking Processing Status

Poll the status endpoint with the returned home ID:

`[POST] /v1/homes/bill-upload/{homeId}/status`

```json theme={null}
{
  "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 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.