Home Energy Scoring‎ > ‎API Definitions‎ > ‎API Methods‎ > ‎< 2017.1‎ > ‎


This method creates a new building from a set of building inputs created in HPXML (taking the place of both submit_address and submit_inputs) and returns a building_id. The HPXML must be converted to a Base 64 encoded payload.  Although you can specify more than one building in the HPXML format only one building may be loaded with each call.  By default the first building will be loaded.
user_keyAPI key for accessstring32Yes
qualified_assessor_idID of the assessor creating this housestring20Yes
hpxml_building_idWhich Building/BuildingID in hpxml to convert if there is more than one Building elementstringNoDefault is the first Building element
hpxmlHPXML inputs (encoded in Base64 format)stringYes

  • Address must be checked using a geocoding service to be a valid address before submission
  • NREL has documented the field mapping of HPXML to Home Energy Score inputs here
  • The Home Energy Scoring Tool does not validate the HPXML and if there are mapping problems (i.e. invalid enumerations, out of range values etc.) only a very general error will be returned, so the HPXML inputs should be done with care.


building_idID of the created building
resultOK, FAIL
messageERROR:TranslationError: hpxml error text

HPXML Translation Errors

Error TextMeaning
 API key is not authorized You need to submit a valid API key
 Assessor id ##### is not valid You need to submit a valid qualified_assessor_id
 failed to validate against all the following  HPXML schemas: hpxml-2.1.0, hpxml-1.1.1 
 ZipCode missing