System Surveyor API (v3)

Returns all active (non-revoked) public API access tokens for the account. Each entry includes the decrypted token value, the user whose permissions the token carries, its creator, and its expiration timestamp.

The account must have the Public API feature enabled. Only account admins can retrieve the account's access tokens.

Creates a long-lived (one year) public API access token for the account. The token is a JWT that carries the permissions of the user referenced by the required user_id field in the request body; a name for the token is also required.

The account must have the Public API feature enabled. Only account admins can create access tokens.

Revokes a public API access token. The token is soft-deleted and immediately blocklisted, so it can no longer be used to make API requests.

The account must have the Public API feature enabled. Only account admins can revoke access tokens.

Returns the calling user's active Prismatic integration access token for the account, creating a new one carrying the calling user's permissions if none exists. Returns 200 when an existing token is found and 201 when a new one is created.

The account must have the Integration Marketplace feature enabled. Any user who belongs to a team in the account can use this endpoint.

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 contacts and guest users for a site.

When a contact has already joined the site as a guest user, the contact data is merged with the user's account data and includes the permission and expiration date granted to the guest. Contacts that have been invited as guest users but have not accepted the invitation yet include their pending invitation's ID, along with the invited permission and expiration date. Guests whose site access has been revoked are still returned as plain contacts.

Requires read access on the site.

Creates a new invitation for a site contact to join the site as a guest user with a specific access permission (read or write), and sends the invitation email to the contact.

Any existing pending invitations for the contact on the site are cancelled, so only one pending invitation exists at a time. If the contact is already a guest user, or has reached the maximum number of sites they can join as a guest under the account's plan, a 422 is returned.

Only accounts with the guest user feature enabled can invite guests, and only admins or users with site write permission can perform the invitation.

Accepts a pending team or guest invitation on behalf of the invitee. This endpoint is unauthenticated but requires a valid reCAPTCHA captcha_token; the invitation must be pending and not expired.

If no user account exists for the invitee's email, first_name, last_name and password are required to create one - without them a 422 with a credentials_required indicator is returned, and the request must be retried with the credentials. If the invitee already has an account (for example from a previous guest invitation), the existing account is used and no credentials are needed.

Accepting a team invitation adds the invitee to the team with the invited role (subject to the subscription's seat limit) and clears any guest flags they held on the team's sites, keeping their existing site permissions. Accepting a guest invitation grants the invitee access to the site with the invited permission and adds the site to their workbench; guest users do not belong to a team.

On success, the response contains JWT login tokens when a new user account was created as part of the acceptance, and is an empty object otherwise.

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 survey share token 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.

Shares a site with a list of email addresses for a limited amount of time.

Each address in the payload's emails list receives an email with instructions on how to access the site, including an access token. The required expiration_date (UTC epoch seconds) sets when the share stops being viewable, and an optional message is included in the email.

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.

Creates a new site in a team.

The site is added to the creator's workbench and the team is granted write access on it. The site can be created inside a folder by passing the folder's external ID as a folder_id field in the payload; the folder must belong to the same team as the site.

The user must be a member of the team the site is created in.

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 all folders and 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, each referencing its containing folder through folder_id (null for sites that are not in a folder).

Pagination treats folders and sites outside of folders as the paginated entries, with folders sorting first. The sites within a folder are always returned in full alongside their folder and do not count towards the page size. 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 top-level 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 the actions the current user is allowed to perform on each site they have read access to.

The response is an object keyed by site external ID; each value is a map of boolean permission flags (e.g. user_can_edit_site, user_can_create_surveys, user_can_change_site_access, is_site_guest) derived from the user's site access, guest status, and team role.

Adds (POST) or removes (DELETE) a list of sites to/from the current user's workbench.

The request body is a plain JSON array of site external IDs. When favoriting, sites already in the workbench are silently ignored; IDs that do not match an existing, non-deleted site are skipped without error.

The user must have at least read access on all of the referenced sites.

Adds (POST) or removes (DELETE) a list of sites to/from the current user's workbench.

The request body is a plain JSON array of site external IDs. When favoriting, sites already in the workbench are silently ignored; IDs that do not match an existing, non-deleted site are skipped without error.

The user must have at least read access on all of the referenced sites.

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 survey share token for this survey, 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.

Returns all surveys across all sites of a team. Each entry contains only the survey's ID, title, and reference ID (custom_survey_id).

Only team members, or requests authenticated with a survey share token for a survey in the team, can list the team's surveys. Guest users cannot access this endpoint.

Query Parameters:

• has_reference_id: If true, only returns surveys that have a reference ID set.

Creates a new "Sample Site" in the team along with sample surveys, and returns the external IDs of the created site and surveys. This process usually occurs on new account creations.

The sample surveys are cloned from pre-selected existing surveys that serve as templates, and assigned to the new site.

Only account admins and team admins can create sample surveys.

Shares a survey with a list of email addresses for a given amount of time. A share grant is created for each address, and an email with instructions on how to access the survey is sent to each of them.

The request payload must contain an emails list and an expiration_date (UTC timestamp) after which the shares stop granting access. An optional message can be included in the emails.

Only users with write access to the survey's site can share the survey.

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.

Schedules a background job that copies a survey into a new survey, and returns the scheduled job's ID (job_id). Clients should poll the Get Copy Survey Job Status endpoint to determine the outcome of the copy. All binary files related to elements, such as images and PDFs, are also copied and assigned new paths.

The user must have write access to both the source and destination site (if any).

Query Parameters:

• dest: External ID of the destination site, or of a folder in a writable site, where the survey will be copied. If omitted, the survey is copied into the same site as the source survey.

Returns the current status of a copy survey background job, previously scheduled with the Copy Survey endpoint. The status field is one of scheduled, in_progress, completed, or errored.

Read access to the source survey's site is sufficient to poll copy job statuses. Job statuses expire one month after the job was scheduled, after which a 404 is returned.

Returns a list of available survey templates. These are the templates currently marked as belonging to survey with ID of 1 in the database (a temporary workaround until proper template management is implemented).

Responses are cached per version for up to 30 days.

Query Parameters:

• version: Templates version to return. Defaults to the latest version.

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 survey-share requests whose shared survey belongs to the team. Responses are cached per team for one day.

Removes an active team member from a team.

Only account or team admins can remove team members, and users cannot remove themselves from a team.

Editor locks for all surveys where the removed user is the current editor are released.

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 survey share grants 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.