retrieve_buildings_by_id

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.

Parameters

NameDescriptionTypeRequiredOptions
 session_token Get from the get_session_token methodstringYes 
user_keyAPI key for accessstringYes
 rows_per_page Number of buildings to retrieve, up to 1000. Defaults to 1000 if not passed. intNo 
 page_number Page number to retrieve (skips the first rows_per_page * page_number records). Defaults to 1 if not passed. intNo 
 archive false: Only return non-archived buildings
 true: Only return archived buildings
 Omitted: If this field is not included in the request, both archived and non-archived buildings will be included in the response.

(see archive_buildings_by_id) 
 boolean No 
 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 or a comma-separated list of user IDs. 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 
 min_date If passed, filter such that only buildings with creation dates on or after this date are accepted date No 
 max_date If passed, filter such that only buildings with creation dates on or before this date are accepted date No 
 min_building_id If passed, filter such that only buildings with IDs greater than or equal to this value are returned int No 
 max_building_id If passed, filter such that only buildings with IDs less than or equal to this value are returned int 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. This may be a comma-separated list if you wish to include multiple assessment types in the result. string No initial, final, qa, alternative, test, corrected, mentor

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



Response

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

ElementDescription
idThe building ID
 parent_id If the building was created by copying another building, that building's ID will be returned in this field.
 ultimate_ancestor_id If the building was created by copying another building, the ID of the original building will be returned in this field.
 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
 archived true: The building is archived. false: The building is not archived.
 locked true: The building is locked. false: The building is not locked.




Roles

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

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