# WattBuy Documentation > Documentation for WattBuy ## API Reference - [Introduction](https://wattbuy.readme.io/reference/getting-started-with-your-api.md): Welcome to the WattBuy APIs! 💡 - [Your Developer Account](https://wattbuy.readme.io/reference/creating-an-account.md) - [Terms of Use](https://wattbuy.readme.io/reference/terms-of-service.md) - [Utility Information Lookup](https://wattbuy.readme.io/reference/get_electricity-info-1.md): This endpoint returns the key details about the electric utility serving a particular location. Pass in a user’s location and return the utility name, phone number, web address, and any other key information available. Both US and Canadian locations are supported. For a Canadian location the response includes a `country` field set to "ca". - [Electricity Usage Estimate](https://wattbuy.readme.io/reference/get_electricity-estimation-1.md): This endpoint returns a home’s expected electricity usage (in kWh) over a 12-month period, as well as the carbon footprint, utility rate, expected bill, and more. Our best-in-class machine learning model is trained on millions of data points and is constantly being updated with new information to create a personalized estimation output to every home. There are a number of ways this API can be used, depending on the amount of data you already have. Case 1 (Zip Code Only): The minimum input required is a zip code. This allows us to apply weather and climate data in order to return a usage prediction for the average home in the area Case 2 (Full Address): This is the most common use case. You provide the address of the user and we take care of the rest! We use the address to fill in the rest of the fields for you. Case 3 (Housing Data): If you don't have the address but you know some other characteristics of the home (square footage, bedrooms, etc), you can manually enter those as well and we'll apply whatever you have to the model. Case 4 (Address and Housing Data): For the best results, you can enter both the address and the housing data. We'll trust any housing data you give us, and use the address to attempt to fill in any empty fields. - [Electricity Solar Estimate](https://wattbuy.readme.io/reference/get_electricity-solar-estimation.md): This endpoint returns our recommended solar panel size and estimated production of that solar panel system. Simply input the address of the home and we'll handle the rest. We do the work of estimating the available roof space as well as the solar efficiency of that specific location. The estimated optimal size of the solar panel system is returned in the "m2_decided" response field. The estimated monthly production of that system can be found in "solar_production_monthly". This field is a list of solar production values for each month, January through December. If you'd like net usage, these solar values can be subtracted from our total usage estimate response. - [Carbon Footprint Estimate](https://wattbuy.readme.io/reference/get_electricity-carbon-footprint.md): This endpoint returns information about a particular home's carbon footprint impact. Just enter a home's address information and we'll handle the rest. We look up the building characteristics of that particular home, along with climate characteristics and the fuel mix of the area's electricity generation to provide a personalized estimate. If you don't need that level of specificity, you can also just enter the state and we'll return the fuel mix to give you a general idea of the carbon impact of electricity in that state. In the response, "carbon_foot_print" is the estimated annual carbon footprint (in pounds) for that home. Additionally, "estimated_generation_data" represents the estimated mix of fuel sources for that home, where "value" is the percentage of electricity that a particular fuel source generates in that area. - [ESI ID Lookup](https://wattbuy.readme.io/reference/get_electricity-info-esi-1.md): This endpoint takes an address as input and returns the ESI ID and utility name. - [Retail Rate Database](https://wattbuy.readme.io/reference/get_electricity-retail-rates.md): This endpoint returns the tariffs (structures) and rates (costs) to purchase electricity from electrical utilities in the United States. The bulk of our retail rates are for residential customers (though there may be some overlap with small commercial or other electricity users). We include all types of utilities, including investor owned utilities, municipal utilities, and coops. Our data includes component charges, the source of the data, and the recency. We include time-varying rates, also known as “time of use” rates, and provide the structure of peak versus non-peak Our Retail Rate Database contains electricity rates for 95% of US customers (over 1700 utility companies). Our database uses a human-augmented machine learning approach to pull the latest rates whenever they become available and we are continually feeding in new rates as well as updating existing rates. Users can employ this data to estimate the cost of electricity based on a set usage. It can also be used to determine based on changes in electricity usage, for instance from energy efficiency upgrades. This data can be combined with the electricity usage estimate (link) to estimate the cost of electricity for nearly any home in the US. - [Surplus Generation Rate Database](https://wattbuy.readme.io/reference/get_electricity-generation-rate.md): This endpoint returns the surplus generation rate for electricity utilities in the United States, also sometimes referred to as the net metering rate. The bulk of our surplus generation rates are for residential customers, usually with rooftop solar, but some of the generation rates may be helpful also for small commercial customers, or for customers with wind or other generation facilities. Our data includes the rates, the parameters employed by utilities to calculate the total value, the sources of the data, the recency of collection, and when it is not possible to directly calculate the surplus generation rate, we identify the type of estimation that was used to calculate the estimate. If a rate varies with time, we include the structure so that users are able to calculate the value of surplus for a period of time, over a calendar year. Our surplus generation rate database includes sixty of the utilities with the largest number of customers generating surplus generation. We collect this data with a human-augmented machine learning approach to collect the latest data concerning surplus generation valuations, and it is verified by an independent energy consultancy. Users can employ this data to estimate the value of surplus generated electricity, based on a production curve. It can also be used to test the value of different production curves, for instance to determine the increased return on investment if a larger rooftop solar system is installed. This data can be combined with the electricity solar estimate and the electricity usage estimate to calculate the value of surplus solar production for nearly every home in the US. - [Request Rate](https://wattbuy.readme.io/reference/post_electricity-request-rate.md): This endpoint can be used to submit a request for WattBuy to prioritize adding a particular rate to our retail rate database. - [Get All Electricity Details For A Property](https://wattbuy.readme.io/reference/get_electricity.md): This endpoint combines our electricity estimation, solar, cost, and carbon footprint APIs into one call. This allows us to efficiently re-use components of the calculations and return all data quicker than calling all the APIs separately. If given address not found it will return 204 status If given address has mutliple matches it will return 400 status with relavent addresses - [Retrieve residential incentive programs](https://wattbuy.readme.io/reference/post_incentives.md): Returns upfront rebates and ongoing (DR/VPP) programs available to a residential customer at a given location, across all electrification-relevant technologies (solar, battery, EV, heat pump, water heater, insulation, appliance, etc.). The response includes: - `upfront[]` — at-purchase rebates and tax credits, ordered by confidence + provider preference + max amount - `ongoing[]` — recurring/performance programs (demand response, VPP, time-of-use bonuses) - `totals` — estimated dollar values when `system_cost` and/or `system_size_kw` are provided - `meta` — debug info: which aggregators expanded the result, confidence floor used **Aggregator expansion**: when the customer's utility belongs to one or more aggregators (Mass Save, TVA EnergyRight, Energize CT, etc.), programs administered by those aggregators are automatically included. Same routing applies to ongoing programs (aggregator_id, installer_service_eids scoping for installer-VPPs like Sunrun-SCE). **Confidence filtering**: by default only `HIGH` records surface. Pass `min_confidence: 'MEDIUM'` (or lower) to opt in to less-certain records. Confidence reflects whether the record is authority-confirmed (HIGH) versus hint-only from third-party databases like DSIRE (MEDIUM). The `VERIFIED` tier was historically present but consolidated into `HIGH` in May 2026 — `VERIFIED` is still accepted as a valid `min_confidence` for backwards compatibility but produces the same set as `HIGH`. - [Submit feedback on an incentive record](https://wattbuy.readme.io/reference/post_incentives-feedback.md): Customers and partners report data quality issues — wrong amount, expired program, missing program, etc. Feedback is queued internally for review. At least one of `canonical_id`, `ongoing_id`, or `user_message` must be provided so we can act on the report. - [Offers](https://wattbuy.readme.io/reference/get_offers.md) - [Marketplace Deeplink](https://wattbuy.readme.io/reference/post_plans-link.md) - [Get Form Fields](https://wattbuy.readme.io/reference/get_form.md): Returns the fields required to submit an offer enrollment for the given `offer_id`. The field schema varies by offer — pass the `offer_id` from the offers endpoint and use the returned fields to construct the POST /form request body. ## Offer Categories ### Retail Electricity (Dereg) Offers Key features include: 1. Input Fields: Provides all required and optional fields for the enrollment form. 2. Validation Rules: Each field includes appropriate validation rules in regex format. 3. Field Options: Some fields come with supported options and their corresponding labels. 4. Conditional Fields: Certain fields are required based on dependent keys and values (`dependent_key` / `dependent_value` — see below). 5. Agreement Fields: Includes necessary text and agreement fields for terms of service. 6. Service Types & Dates: Includes supported service types (switch, forward switch, move, priority move) with corresponding available dates. (For Texas only) 7. Utility Validations: - For Non-Texas: Specific validation rules for Utility Account Numbers (UAN) - For Texas: ESIID (Electric Service Identifier) validation rules 8. Optional Fields: Includes fields for deposit, autopay, and deposit with autopay scenarios. These are particularly useful for validating card details when the enrollment requires deposit, autopay, deposit with autopay or deposit waiver based on credit-check response. Payment Metrix: |Supplier|Deposit Options|Autopay Options|DepositAutopay Options| |--------|---------------|---------------|----------------------| |Payless Power|credit card|credit card|credit card| |Chariot Energy|credit card/deposit waiver||| |4Change Energy|credit card|credit card|credit card| |Veteran Energy|credit card|credit card|credit card| |Express Energy|credit card|credit card|credit card| ## Conditional Field Schemas ### `dependent_key` / `dependent_value` (dereg offers) A field with `dependent_key` and `dependent_value` is only shown (and required) when the referenced sibling field equals the given value. ``` socialSecurity: dependent_key: selectSsnDl # watch this field dependent_value: socialSecurity # show me when it equals this ``` ### `cascading_group` (chained dropdowns) A field with `cascading_group` participates in a multi-level chained dropdown. Each level filters the options of the next level based on the selected value. | Property | Meaning | |----------|---------| | `group` | Logical group name — fields sharing a group are chained | | `level` | Position in the chain (1 = root, 2 = first child, …) | | `parent` | Key of the field whose selected value selects options here | | `options_map` | Map from parent value → array of valid options for this field | **Important difference from `dependent_key`:** - `dependent_key` hides/shows a field based on a binary condition (show or hide). - `cascading_group` narrows the *allowed options* of a field based on the parent selection. The field is always visible; its option list changes dynamically. **Vehicle selection cascade:** Three chained levels: `vehicleMake` (level 1) → `vehicleModel` (level 2) → `vehicleYear` (level 3). Makes and models are sorted alphabetically; years are sorted newest-first. - [Submit an Offer Enrollment](https://wattbuy.readme.io/reference/post_form.md): Submits an enrollment for the given offer. Before making this call, GET /form should already have been called to retrieve the required fields for the offer. The request body should contain the form fields as defined in the GET /form response for the selected `offer_id`. The response shape varies by offer category. Note: This API should use the enroll.wattbuy.com base URL rather than apis.wattbuy.com. It is also recommended that you use QA (qaenroll.wattbuy.com) for development. For retail electricity offers, this endpoint returns the code, status, sub status, agent, and metadata. The metadata includes: - Customer info fields - WattBuy order_id for further reference - reference_id from the supplier (if provided by the supplier) - status_reason if the order fails - deposit amount and payment link if a deposit is required Order Status Metrix: |Code|Status|Sub Status|Description| |----|------|----------|--------| |S1|SUBMITTED|Approved|The enrollment has been successfully submitted to the supplier but service has not started| |S2|SUBMITTED|Approved with Deposit Needed|The enrollment has been successfully submitted to the supplier but a deposit is needed to turn on service| |S3|SUBMITTED|Approved with Deposit Waiver Needed|The enrollment has been successfully submitted to the supplier but a deposit waiver is needed to turn on service| |F3|FAILED|Declined|The enrollment has been declined by the supplier| - [Order Status](https://wattbuy.readme.io/reference/get_status.md): This API provides the current status of a previously submitted order. Order Status Metrix: |Code|Status|Sub Status|Description| |----|------|----------|--------| |S1|SUBMITTED|Approved|The enrollment has been successfully submitted to the supplier but service has not started| |S2|SUBMITTED|Approved with Deposit Needed|The enrollment has been successfully submitted to the supplier but a deposit is needed to turn on service| |S3|SUBMITTED|Approved with Deposit Waiver Needed|The enrollment has been successfully submitted to the supplier but a deposit waiver is needed to turn on service| |S4|SUBMITTED|Processing|| |F3|FAILED|Declined|The enrollment has been declined by the supplier| |A1|ACTIVE|Active|Electricity service is actively being provided to the user| |C1|CLOSED|Expired|The service term has expired| |C2|CLOSED|Declined|The enrollment has been declined by the supplier after the enrollment| |C3|CLOSED|Canceled|The enrollment has been canceled by the customer after the enrollment| - [Deregulated Plan Credit Check](https://wattbuy.readme.io/reference/post_credit-check.md): This API can optionally be called before submitting an order to determine whether a user will need to pay a deposit. The only query parameter is the selected plan_id and the request body is the same as when submitting an order. - [Submit an EV Charger Installation Request](https://wattbuy.readme.io/reference/submit-an-ev-charger-installation-request-1.md)