Homes Eligible Rebates Payload
Defined in: homesEligibleRebate.schema.json
Type: object
Additional Properties Allowed: False
| Property | Type | Required | Format | Title |
|---|---|---|---|---|
| address_id | string |
 |
uuid |
Address id |
| applicant_id | string |
|
Applicant id | |
| building_project_type | enum |
|
Building project type | |
| claimant_type | enum |
|
Claimant type | |
| construction_type | enum |
|
Construction type | |
| contractor_company_name | string |
|
Contractor company name | |
| contractor_dac_incentive | number |
Contractor DAC incentive | ||
| contractor_name | string |
|
Contractor name | |
| dwelling_unit_income_bucket | enum |
Dwelling unit income bucket | ||
| estimated_percent_energy_savings | number |
|||
| estimated_post_retrofit_energy_usage_kwh_equivalent | integer |
Estimated post-retrofit energy usage kwh equivalent | ||
| estimated_post_retrofit_site_energy_usages_by_fuel_type | estimated_post_retrofit_item | Estimated Post Retrofit Item | ||
| external_rebate_id | string |
External rebate id | ||
| is_contractor_eligible | boolean |
|
Is contractor eligible | |
| is_disadvantaged_community | boolean |
Is disadvantaged community | ||
| measured_pre_retrofit_energy_usage_kwh_equivalent | integer |
Measured pre-retrofit energy usage kwh equivalent | ||
| measured_pre_retrofit_site_energy_usages_by_fuel_type | measured_pre-retrofit_site_energy_usages_by_fuel_type | Measured pre-retrofit site energy usages by fuel type | ||
| mf_building_income_bucket | enum |
Multifamily building income bucket | ||
| modeled_percent_energy_savings | number |
|||
| modeled_post_retrofit_energy_usage_kwh_equivalent | integer |
Modeled post-retrofit energy usage kwh equivalent | ||
| modeled_post_retrofit_site_energy_usages_by_fuel_type | modeled_post-retrofit_site_energy_usages_by_fuel_type | Modeled post-retrofit site energy usages by fuel type | ||
| modeled_pre_retrofit_energy_usage_kwh_equivalent | integer |
Modeled pre-retrofit energy usage kwh equivalent | ||
| num_occupied_units | integer |
Num occupied units | ||
| modeled_pre_retrofit_site_energy_usages_by_fuel_type | modeled_pre-retrofit_site_energy_usages_by_fuel_type | Modeled pre-retrofit site energy usages by fuel type | ||
| modeling_software_used | string |
Modeling software used | ||
| num_units | integer |
Num units | ||
| num_units_meeting_income_bucket | integer |
Num units meeting income bucket | ||
| portfolio_id | string |
uuid |
Portfolio id | |
| project_id | string |
Project id | ||
| rebate_type | enum |
|
Rebate type | |
| reservation_amount | number |
Measured reservation amount | ||
| software_used_to_estimate_post_retrofit_energy_usage | string |
Software used to estimate measured savings | ||
| state_attests_proof_of_identity_ownership_income | boolean |
|
State attests proof of identity ownership income | |
| unit_name_or_number | string |
Unit name or number | ||
| upgrades | homes_upgrades | |
Homes upgrades |
allOf Requirement
Conditional Validation
address_id
A unique identifier associated with the address of the building at which the upgrade(s) will be installed. This id must be obtained using the address-service endpoint.
- is required
- Type:
string
applicant_id
This identifier is unique to the applicant (the building owner or renter that is to benefit from the rebate). It must be obtained from the API /applicant endpoint.
- is required
- Type:
string
building_project_type
This describes both the type of the building and, in the multifamily case, whether this reservation applies to the whole building or to a single unit. For the MULTIFAMILY_CENTRAL case, the income bucket for the building, mf_income_bucket, is used. Otherwise, the income bucket for the dwelling unit, dwelling_unit_income_bucket, is used.
- is required
- Type:
enum
| Value |
|---|
MANUFACTURED |
MULTIFAMILY_CENTRAL |
MULTIFAMILY_IN_UNIT |
SINGLE_FAMILY_ATTACHED |
SINGLE_FAMILY_DETACHED |
claimant_type
The type of person or entity that is initiating the rebate process on behalf of the applicant.
- is required
- Type:
enum
| Value |
|---|
AGGREGATOR |
CONTRACTOR |
HOMEOWNER |
MULTIFAMILY_BUILDING_OWNER |
OTHER |
construction_type
Set to NEW if the building is less than one year old. Otherwise, set to EXISTING.
- is required
- Type:
enum
| Value |
|---|
EXISTING |
NEW |
contractor_company_name
The name of the primary contracting company for the project.
- is required
- Type:
string
Minimum Length: 1
Maximum Length: 64
contractor_dac_incentive
This is the amount the state will pay to a contractor as a disadvantaged-community incentive.
- is not required
- Type:
number
Must be multiple of: 0.01
Minimum Number: 0
contractor_name
The name of the primary contractor for the project.
- is required
- Type:
string
Minimum Length: 1
Maximum Length: 64
dwelling_unit_income_bucket
The household income level of the applicant compared to the area median income (AMI).
- is not required
- Type:
enum
| Value |
|---|
80%_AMI_AND_GREATER |
LESS_THAN_80%_AMI |
estimated_percent_energy_savings
An estimate for the percent measured energy savings where total energy use is first converted to source energy in a manner determined by the state. To avoid an immediate breaking change, this field is currently optional when rebate_type is MEASURED and otherwise not allowed – either this field or the two fields measured_pre_retrofit_energy_usage_kwh_equivalent and estimated_post_retrofit_energy_usage_kwh_equivalent must be specified when rebate_type is MEASURED. The behavior starting mid to late January 2025 will be: this field is required for rebate_type MEASURED and otherwise not allowed.
- is not required
- Type:
number
Maximum Number: 100
estimated_post_retrofit_energy_usage_kwh_equivalent
This field is deprecated and will be removed in a future release. Use estimated_post_retrofit_site_energy_usages_by_fuel_type instead. This is the total estimated (expected) annual energy usage converted to kWh-equivalent for the home or multifamily building post-retrofit. This field is used for MEASURED reservations only.
- is not required
- Type:
integer
Minimum Number: 0
estimated_post_retrofit_site_energy_usages_by_fuel_type
An array of estimated post-retrofit site energy usage objects. Each entry represents a different fuel type. To avoid an immediate breaking change, this field is currently optional when rebate_type is MEASURED and otherwise not allowed. The behavior starting mid to late January 2025 will be: this field is required when rebate_type is MEASURED and otherwise not allowed. Please begin using this field asap.
- is not required
- Type: estimated_post_retrofit_item
external_rebate_id
This is an optional field that a state can use for their own purposes to identify a rebate or rebate reservation.
- is not required
- Type:
string
Minimum Length: 1
Maximum Length: 64
is_contractor_eligible
The contractor is eligible if they are on the state's approved list.
- is required
- Type:
boolean
is_disadvantaged_community
This field should only be used by states that have been approved by the DOE to do so. If provided, this will override the is_disadvantaged_community value from the address-service.
- is not required
- Type:
boolean
measured_pre_retrofit_energy_usage_kwh_equivalent
This field is deprecated and will be removed in a future release. Use measured_pre_retrofit_site_energy_usages_by_fuel_type instead. This is the total actual annual energy usage converted to kWh-equivalent for the home or multifamily building prior to the retrofit - based on normalized utility bill data. This field is used for MEASURED reservations only.
- is not required
- Type:
integer
Minimum Number: 0
measured_pre_retrofit_site_energy_usages_by_fuel_type
An array of measured pre-retrofit site energy usage objects. Each entry represents a different site fuel type. To avoid an immediate breaking change, this field is currently optional when rebate_type is MEASURED and otherwise not allowed. The behavior starting mid to late January 2025 will be: this field is required when rebate_type is MEASURED and otherwise not allowed. Please begin using this field asap.
- is not required
- Type: measured_pre-retrofit_site_energy_usages_by_fuel_type
mf_building_income_bucket
Choose the lowest area median income (AMI) range for which at least 50% of the household units fall into the range or lower. For example, consider a five-unit apartment building for which two units fall in the LESS_THAN_80%_AMI range and three fall in the 80%_AMI_AND_GREATER. Then the 80%_AMI_AND_GREATER range should be chosen because more than half of the units fall into this range or lower.
- is not required
- Type:
enum
| Value |
|---|
80%_AMI_AND_GREATER |
LESS_THAN_80%_AMI |
modeled_percent_energy_savings
The calculated percent modeled energy savings where total energy use is first converted to source energy in a manner determined by the state. To avoid an immediate breaking change, this field is currently optional when rebate_type is MODELED and otherwise not allowed – either this field or the two modeled_...kwh_equalent fields must be specified when _rebate_type is MODELED. The behavior starting mid to late January 2025 will be: this field is required when rebate_type is MODELED and otherwise not allowed. Please begin using this field asap.
- is not required
- Type:
number
Maximum Number: 100
modeled_post_retrofit_energy_usage_kwh_equivalent
This field is deprecated and will be removed in a future release. Use modeled_post_retrofit_site_energy_usages_by_fuel_type instead. This is the total annual modeled energy usage converted to kWh-equivalent for the home or multifamily building post-retrofit. This field is used for MODELED reservations only.
- is not required
- Type:
integer
Minimum Number: 0
modeled_post_retrofit_site_energy_usages_by_fuel_type
An array of modeled post-retrofit site energy usage objects. Each entry represents a different fuel type. To avoid an immediate breaking change, this field is currently optional when rebate_type is MODELED and otherwise not allowed. The behavior starting mid to late January 2025 will be: this field is required when rebate_type is MODELED and otherwise not allowed. Please begin using this field asap.
- is not required
- Type: modeled_post-retrofit_site_energy_usages_by_fuel_type
modeled_pre_retrofit_energy_usage_kwh_equivalent
This field is deprecated and will be removed in a future release. Use modeled_pre_retrofit_site_energy_usages_by_fuel_type instead. This is the total annual modeled energy usage converted to kWh-equivalent for the home or multifamily building as-found (prior to the retrofit). This field is used for MODELED reservations only.
- is not required
- Type:
integer
Minimum Number: 0
num_occupied_units
This is the number of occupied units in a multifamily building. Note: This field should be used for building_project_type MULTIFAMILY_CENTRAL or MULTIFAMILY_IN_UNIT_PART_OF_BUILDING_PROJECT. Although it is currently optional in these cases, it will be required in a future release.
- is not required
- Type:
integer
Minimum Number: 0
Maximum Number: 1000
modeled_pre_retrofit_site_energy_usages_by_fuel_type
An array of modeled pre-retrofit site energy usage objects. Each entry represents a different site fuel type. To avoid an immediate breaking change, this field is currently optional when rebate_type is MODELED and otherwise not allowed. The behavior starting mid to late January 2025 will be: this field is required when rebate_type is MODELED and otherwise not allowed. Please begin using this field asap.
- is not required
- Type: modeled_pre-retrofit_site_energy_usages_by_fuel_type
modeling_software_used
Enter the name of the software used to model energy usage and savings when rebate_type is MODELED. For single-family building types this must be DOE-approved BPI-compliant software. Refer to program guidance for other building types. This field is NOT allowed unless rebate_type is MODELED.
- is not required
- Type:
string
Minimum Length: 2
Maximum Length: 64
num_units
This is the total number of units in a multifamily building. This field is required when building_project_type is any of the enumerated values that has a "MULTIFAMILY" prefix. Otherwise, the field should be omitted.
- is not required
- Type:
integer
Minimum Number: 2
Maximum Number: 1000
num_units_meeting_income_bucket
This is the number of occupied units in a multifamily building for which the household income falls within the income range represented by mf_income_bucket or is lower.
- is not required
- Type:
integer
Minimum Number: 1
Maximum Number: 1000
portfolio_id
Multiple reservations for MEASURED HOMES projects can be tied together into a portfolio by assigning the same portfolio_id value to each reservation in the portfolio.
- is not required
- Type:
string
project_id
This is a unique string supplied by the API user that is used to associate one or more reservations to a single project. Note: it is recommended that a uuid be used to avoid duplication, but the API user can use any other system that they find convenient, provided that it is unique for the state.
- is not required
- Type:
string
Minimum Length: 6
Maximum Length: 36
rebate_type
The HOMES rebates have two distinct options for determining savings and rebate amounts, MODELED vs MEASURED.
- is required
- Type:
enum
| Value |
|---|
MEASURED |
MODELED |
reservation_amount
The API user-specified reservation amount for a MEASURED rebate. This field is required for rebate_type MEASURED and otherwise not allowed. The API does not calculate a reservation amount in the MEASURED case. The value provided here will be reserved in the system for the rebate. Do NOT include any incentive amount.
- is not required
- Type:
number
Must be multiple of: 0.01
Exclusive Minimum: 0
software_used_to_estimate_post_retrofit_energy_usage
This field is required when rebate_type is MEASURED.
- is not required
- Type:
string
Minimum Length: 2
Maximum Length: 64
state_attests_proof_of_identity_ownership_income
The state attests that they have obtained the required proof of identify, proof of ownership, and proof of income for this rebate.
- is required
- Type:
boolean
Constant: True
unit_name_or_number
This is the unit designator for a unit in a multifamily building. It should also be used in situations where multiple homes share a street address and are distinguished only by a Lot# or other special designation. Do NOT include words or abbreviations such as 'APT' or 'UNIT'. For example, if the unit is referred to as 'APT 7B', then unit_name_or_number should be '7B'.
- is not required
- Type:
string
Minimum Length: 1
Maximum Length: 32
upgrades
List all the upgrades from the enumeration that apply to the HOMES project.
- is required
- Type: homes_upgrades
Items should be unique: True
Minimum number of items: 1