Home Energy Scoring‎ > ‎API Definitions‎ > ‎API Methods‎ > ‎2017.2‎ > ‎


This method's name is a historical artifact - it was originally intended to retrieve all buildings associated with a user ID. It has evolved to allow many more filter options, and retrieves a small snippet of information related to each building matching the filter.  The retrieve_* methods can then be used to get more complete information about the buildings if desired.


 session_token Get from the get_session_token methodstringYes 
user_keyAPI key for accessstringYes
 rows_per_page Number of buildings to retrieve intYes 
 page_number Page number to retrieve (skips the first rows_per_page * page_number records) int Yes 
 archive 0: Only return non-archived buildings
 1: Only return archived buildings
(see archive_buildings_by_id) 
 int Yes 0 or 1
 qualified_assessor_id The assessor whose buildings are to be retrieved. For users with the Admin role, this field is optional and may be set to any user ID. For users with the Assessor role, this field is mandatory and must be set to the assessor's own ID.

Technically a Partner is permitted to use this method, but it is recommended to use the retrieve_buildings_by_partner method, instead, which automatically retrieves all results for a Partner. If you do call this as a Partner, you must pass qualified_assessor_id and it must only contain assessors that are assigned to your Partner.

Note: If you're thinking it's silly that assessors have to pass their own ID, we agree. There's an odd bit of technical debt that required it to be done this way, and we're as sad about it as you are.
 intDepends on user role 
 date_range If passed, filter on buildings that were created within this date range (endpoints inclusive). The format looks like "2000-12-31_2001-12-31" (Two YYYY-MM-DD dates separated by an underscore) stringNo  
 building_id_range If passed, filter on buildings whose IDs fall within this range. The format is #######_####### (two building IDs separated by an underscore) string No 
 address If passed, filter on buildings whose street address, city, state, or zip code contain the passed string. string No 
 assessment_type If passed, filter on assessment type string No initial, final, qa, alternative, test, corrected, mentor

 locked If passed, filter on locked (if 1) or unlocked (if 0). A building is considered locked if commit_results has successfully been run for the building. int No 0 or 1
 external_building_id If passed, filter on buildings whose external_building_id field is set and contains this string string No 


This method returns a collection of buildings_by_id_result elements, each of which contains the following:

idThe building ID
 external_building_id The building's external building ID, if it has one
 qualified_assessor_id The user name of the assessor who created the building
 create_date The date the building was created
 assessment_date The date the assessment was performed
 assessment_type initial, final, qa, alternative, test, corrected, or mentor
 address Address: Street & house number
 city Address: City
 region_code Address: State
 postal_code Address: Zip code
 locked 1: The building is locked. 0: The building is not locked.


Method access is limited by the roles assigned the user to whom the session token was assigned

AssessorMust pass user's own qualified_assessor_id
PartnerAccess allowed, see qualified_assessor_id above for details
 Admin Access allowed