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

Assessment Type

To begin a HEScore session an assessment type must be selected. The assessment type is determined from HPXML via the XMLTransactionHeaderInformation/Transaction and Building/ProjectStatus/EventType element using the following mapping:

Assessment Type mapping
XML Transaction Type HPXML Event Type HEScore Assessment Type
create audit initial
proposed workscope alternative
approved workscope alternative
construction-period testing/daily test out test
job completion testing/final inspection final
quality assurance/monitoring qa
update any corrected

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.