System Surveyor API (v3)

Returns the usage information for an account, aggregated across all of its teams: the number of active members, disabled members, pending invitations, and available subscription seats. A team_id query parameter can be provided to restrict the counts to a single team in the account. This is displayed in the "Manage Teams" page.

Returns all data for a specific site, along with its survey count.

Only users with at least read access on the site, or requests with a valid share token scoped to the site (a site share, or a survey share for a survey on the site), can access it.

Creates a site with the given external ID, or updates the existing site with that ID.

On creation the site is added to the creator's workbench and its team is granted write access. Tags in the payload are added to the site (tags that do not yet exist for the team are created); existing tags are never removed by this endpoint. A folder_external_id field can be included in the payload to move the site into that folder, which must belong to the same team as the site.

The user must be a member of the team given in the payload.

Soft deletes a site and all of its surveys.

The site disappears from all listings and can no longer be accessed, but the underlying records are retained.

Requires write access on the site.

Partially updates a site: only the fields present in the payload are changed.

Tags in the payload are added to the site (tags that do not yet exist for the team are created); existing tags are never removed by this endpoint.

Requires write access on the site.

Returns the bill of materials data for a site: element quantities aggregated by component model across the site's surveys. Survey elements without a component model value are ignored.

By default the response is a flat array of {component_model, quantity} objects aggregated across all surveys. With group_by_survey=true, quantities are aggregated per survey instead and each array entry holds a survey reference (id, title) and its components.

Requires read access on the site.

Query Parameters:

• surveys: Optional, repeatable survey external ID to restrict the BOM data to. All IDs must belong to surveys on this site. Defaults to all surveys on the site.
• installation_status: Optional, repeatable installation status to filter components by.
• system_type: Optional, repeatable system type to filter components by.
• group_by_survey: When true, aggregates and groups the bill of materials by survey.

Moves a site to a different folder or to the root level, within the same team or to a different team.

When team_id differs from the site's current team, the site is transferred to that team, which must belong to the same account; only account admins can move sites across teams. A transfer removes the site from every user's workbench, clears the editor of all surveys on the site, and moves the site's access grants and folders to the destination team.

The site is then placed in the folder given by folder_id, which must belong to the destination team, or at the root level when folder_id is omitted.

Requires write access on the site; moving within the same team requires no additional permission.

Returns the sites the current user has access to across all teams as a plain, flat JSON array without a pagination envelope. Each entry carries the site's data plus its survey_count and, when the site is in the user's workbench, its favorited_ts.

This is a legacy listing: unlike GET /sites it does not group results by folder and returns no meta or links — in fact, sites that are inside a folder are excluded entirely. New consumers should prefer GET /sites.

Results are ordered by most recently created.

Query Parameters:

• page[number]: Page to retrieve from the entire result set.
• page[size]: Max number of sites to return per page. Defaults to 100; all returns the entire result set unpaginated.
• filter[modified_after]: Only return sites created or modified, or whose access grants for the user changed, after the given timestamp (in UTC epoch seconds).
• filter[favorites_only]: When true, only return sites in the user's workbench.

Returns the folders and root-level sites that the user has access to across all teams, grouped for list display.

Folders are returned in the data.folders array and always come first; sites are returned in the data.sites array. Sites within folders are not part of the listing — only their folder is, with site_count reporting its member count and survey_count the total number of surveys across its member sites.

Pagination treats folders and root sites as the paginated entries, with folders sorting first. meta holds total_sites, the total number of sites the user can access (across both root and in-folder sites) matching the q search and teams filter, and total_favorites, the favorited subset of that count. total is the number of paginated entries (folders plus root sites) and total_pages is the number of pages; both reflect the active filters. A page[size] of all returns the entire result set unpaginated.

The sort param orders the listing by name, owner, team, modified_at or survey_count (prefix with - for descending). Folders always come before sites; the ordering is applied within each group.

Returns the sites and folders that have been deleted across all teams the user is an active member of.

The listing combines soft-deleted sites and folders with sites that were hard deleted from the database, which are recovered from the site audit table. Each entry holds the record's id, name, type (site or folder) and deleted_at timestamp. Results are ordered by most recently deleted.

Query Parameters:

• page[number]: Page to retrieve from the entire result set.
• page[size]: Max number of entries to return per page. Defaults to 100; all returns the entire result set unpaginated.
• filter[deleted_after]: Only return sites and folders deleted after the given timestamp (in UTC epoch seconds).

Returns a complete serialization of a survey and all of its related information, including its elements, floorplans, and site details.

Only users with read access to the survey's site, or requests authenticated with a valid share token whose scope includes this survey (a share of this survey, or of its site), can access the survey.

Requests authenticated with a public API access token receive the same payload except that element canvas positions are omitted. If the survey has no preview image yet, fetching it also triggers background generation of one.

Schedules a background job that syncs a survey to the complete state provided in the request payload. Existing surveys are updated to match the new state; if no survey with the given ID exists, a new survey is created. Only the survey editor or team admins can sync an existing survey. A new survey can be created within a folder by including a folder_id field in the payload, referencing a folder in the same site. If a sync job for the survey is already queued or running, no new job is scheduled and the existing job is returned with a 200 status code; in that case the request payload will NOT be synced, and clients holding a newer survey state should sync again after the returned job finishes.

Returns the current status of a survey sync background job, previously scheduled with the Schedule Survey Sync endpoint. Clients should poll this endpoint to determine the outcome of a sync: a job in the errored status includes an error message describing why the sync failed.

Returns a tree of all possible sites and folders that a survey can be moved or copied to within the same team, keyed by external ID.

Folders that contain sites are returned at the top level with their sites nested; sites that contain survey folders are returned with those folders nested. Sites that are not within any folder are returned at the top level.

Only sites where the user has write access are returned, and the user must have write access to the survey's current site.

Moves a survey into a site, or into a folder that can contain surveys. The request payload must contain a destination_id field with the external ID of the destination site or folder; the list of possible destinations is provided by the Get Survey Transfer Destinations endpoint.

If the destination is a site, the user must have write access to it and the survey is removed from any folder it was in. If the destination is a folder, it must belong to the same team as the survey's site, and the survey is moved into the folder and its site.

The user must have write access to the survey's current site.

Returns the elements of every system type, grouped by snake_cased system type name, plus a favorites group containing the elements the team has favorited.

Accessible to team members, team guests, and share-token requests whose shared survey or site belongs to the team. Responses are cached per team for one day.

Sends team invitations to one or more users by email address, assigning each a specific role (admin, team_admin, team_member, or team_member_with_infomask). An invitation email is sent to every newly invited user.

Any existing pending invitations for an invited email are cancelled first, so only one pending invitation exists per email at a time. Invitations for emails that already belong to an active team member are silently skipped.

Team membership cannot exceed the account's seat limit (the subscription's seat quantity, or the plan's maximum seats for free accounts). Once the seat limit is reached, any further invitations in the request are skipped and not created.

Only account or team admins can invite users, and an inviter cannot assign a role higher than their own (e.g. a team admin cannot invite an account admin).

Changes a team member's role to admin, team_admin, team_member, or team_member_with_infomask.

Only account or team admins can change roles. Users cannot change their own role, and cannot assign a role higher than their own (e.g. a team admin cannot promote someone to account admin).

A team must keep at least one account admin at all times, so demoting the team's only account admin is rejected.

Returns all teams the current user is an active member of, including the teams of sites the user has guest access to.

Results are ordered by most recently created.

Creates a new element profile or updates an existing one matched by name.

Element profiles are considered unique by name within a team and element: if a non-deleted profile with the request's name already exists for the team and element it is updated, otherwise a new profile is created. Accessories can be set when creating new element profiles; they are not modified on updates.

Only account admins and team admins can create or update element profiles.

Returns all element profiles for a team, wrapped in an element_profiles key.

Results are not paginated and are sorted by the sort order defined on each element profile.

Team members, team guests, and share grants (survey or site) with access to the team can retrieve the team's element profiles.

Query Parameters:

• q: Free-text search matching the profile name or the values of key attributes (Descriptive Label, Installation Status, Component Manufacturer, Component Model #).

Returns the accessories of all element profiles in a team for a specific element.

The response holds the requested page of accessories under ep_accessories and the total number of matching accessories under count.

Only team members and team guests can retrieve element profile accessories.

Query Parameters:

• q: Free-text search matching the accessory description, model, or manufacturer.
• page[number]: Page to retrieve from the entire result set.
• page[size]: Max number of accessories to return per page. Defaults to 100; a value of all returns the entire result set unpaginated.

Schedules a background element profile import job using an Element Profile Excel export file as input.

The request body must be the base64-encoded Excel (.xlsx) file. The import runs asynchronously: this endpoint returns the ID of the scheduled job once it has been queued, and the job's progress can later be checked using the import status endpoint.

Only account admins and team admins can import element profiles.

Query Parameters:

• validate_only: When 1, the background job only validates the input file; no changes are applied, and the changes the import would apply as well as any errors found are temporarily cached for inspection via the import status endpoint.
• append: When 1, the import does not delete any existing element profiles and only creates or updates the profiles included in the import file.

Returns a paginated list of all element profiles for a manufacturer.

Each entry includes the element profile's catalog data and the element it applies to.

Query Parameters:

• page[number]: Page to retrieve from the entire result set.
• page[size]: Max number of element profiles to return per page. Defaults to 100.

Imports and adopts manufacturer element profiles from the catalog into a team.

Each adopted profile is snapshotted into the team's library at its current catalog version. Profiles from multiple manufacturers can be adopted in a single request.

Re-adopting a profile a team has already adopted is a no-op: the existing snapshot is preserved and its version is not advanced. Adopting a newer manufacturer version is a deliberate action handled separately, never an implicit side effect of re-adoption.

Only account admins and team admins can adopt manufacturer element profiles.

Updates a team's existing element profile adoptions to the source profiles' current catalog version, data, and name.

This is the deliberate counterpart to re-adoption (which is a no-op): only adoptions the team already holds are advanced to the latest manufacturer snapshot. Profiles the team has not adopted, and unknown IDs, are silently ignored.

Only account admins and team admins can refresh adopted manufacturer element profiles.

Returns all active manufacturers along with a count of their element profiles.

Creates a new site or survey folder with the given external ID, or updates the existing folder if one is found.

Pass a team_id in the request body to create/update a site folder, or a site_external_id to create/update a survey folder; exactly one of the two is required. Site folders require the user to be a member of the team, and survey folders require write access on the site.

Returns 201 when the folder was created and 200 when an existing folder was updated.

Returns the system types the team has selected, ordered by the system type's sort value.

Results are cached per team for 24 hours, so recent changes to a team's selection may take up to a day to be reflected.

Team members, team guests, and share grants (survey or site) with access to the team can retrieve the team's selected system types.