Address and Requesting a New Session

The first step in starting a HEScore transaction is to call the submit_address API call.


The building address is found in HPXML under the Building/Site/Address element. The sub elements there easily translate into the expected address format for HEScore.

         <SiteID id="id1"/>
            <Address1>123 Main St.</Address1>

HPXML allows for two lines of address elements. If both are used, the lines will be concatenated with a space between for submission to the HEScore building_address.address field. All of the HPXML elements shown in the above code snippet are required with the exception of Address2. Additionally, if a zip plus 4 code is entered in HPXML, it will be trimmed to just the 5 digit zip code before being passed to HEScore.

Mentor Assessment Type

In v2015 HEScore introduced a new assessment type called “mentor”. It is used for new assessors in training when an assessment is supervised by a more qualified assessor. There is no equivalent way to communicate this scenario in HPXML. To work around this issue, the translator will look for a specifically named element in the extension of Building/ProjectStatus:


Upon finding this HEScoreMentorAssessment element, the HEScore assessment type will be set to “mentor” regardless of the mapping above.

External Building ID

The value of Building/extension/HESExternalID or Building/BuildingID/SendingSystemIdentifierValue, if present, is copied into the building_address.external_building_id field in HEScore. Preference is given to the extension element if both are present. This is optional, but may be useful for those wanting to pass an additional building identifier for their own tracking purposes.