API docs by Redocly

System Surveyor API (v3)

Download OpenAPI specification:

How to Use Our REST APIs.

System Surveyor's APIs enable bi-directional communication with it's platform. These APIs provide a software layer connecting and optimizing the network to allow your users to create / edit / retrieve sites & surveys, along with all of the associated data.

The domain name for our API is https://openapi.systemsurveyor.com. This needs to be prefixed to all requests.

In order to utilize these APIs, you must have an Enterprise account, with a valid plan. Your account administrator must create an access_token for you, which is required for each request.

Auth

Authenticate

Login to System Surveyor using JWT token authentication

If SSO is live for the user's account users will be redirected to login with SSO instead of with username/password authentication.

Request Body schema: application/json
required
email
required
string
password
required
string
force_login
boolean
captcha_token
string

The captcha token is used to verify that the user is not a bot. This token is generated by the client-side captcha library and should be sent to the server for verification.

This field is optional and should only be used by the web client.

Responses

Request samples

Content type
application/json
{
  • "email": "johndoe@gmail.com",
  • "password": "Qwerty123",
  • "force_login": true,
  • "captcha_token": "string"
}

Response samples

Content type
application/json
{
  • "user_id": 950945,
  • "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoiYWNjZXNzIiwidXNlcl9pZCI6MjAwOSwicm9sZSI6MiwiZXhwIjoxODA1MjEwMzY0LCJpYXQiOjE2NDk2OTAzNjQsInRlYW1fcm9sZXMiOnsiMTg1NSI6MiwiMjA3NCI6MiwiMTAwMjgiOjJ9fQ.k--bt3XHKLRNDZMl3Jmc0qwiJQp_B5XEAecxPUNoCiCfirD6G82Fes8nbtoxCFBm1-Y2Dj6hy036b_B8DemSQk0SdpXuCF-jFb2LRouzohGZ-psiJ40DBe7JLwRNtq09nmLcEvtUIokOpcHiPTsqdnlXt8bAea09ECC9quYZ3ufnH6Gpr_P4EBOqE_I-FwbUqCHCiakbqlXDkim1FTs03wdGVIC7nY8Ika-w3q5ZFK88dqrKtmuK-c0uXnYfQfqelohLJTKfZiGc52qvIUX3FRdusecJQbijJeqJDjX7_Zfa1YYzYx9BC5dqb53J4bbAMUuYHEiMy4Thf4cAJGzG9g",
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsInVzZXJfaWQiOjIwMDksInJvbGUiOjIsImV4cCI6NTM5MDQ0MTAzNjQsImlhdCI6MTY0OTY5MDM2NH0.3Dmrn6_IxHS-EzSGGNAAXFuPRQ0GKjbgmWjK2F4i0hm1iI-DV1aMulonGmHRFDIl33sZYjHQjyLE4LN2quKC6ThjrvkEfgDGaYaIXbTk0mxm1VzqUUbocTuK_N8DITsvhDw31XPAiQ4Sz0mI9rxNb84zdHOgeaVdVZR9K3ssXWKuU9pAk2qEPJiCIw9cJQcjIGNcGlUpphOey5KddDqkq17uZNcA0uJMi6QPvDHZi7rBYXVOPwNY_xqWjrubMMto2vgbWcNOKIzRs00o1TsSTVKhZOwAzctjTIijKnwXvghzLgROiyR5OIT7ZgTVmr7HYhhb7GCyH7LgVLfeKGELew",
  • "first_login_ts": 0
}

Get refresh token

Returns a new valid access token given a valid refresh token.

Authorizations:
jwt
header Parameters
object
Request Body schema: application/json
required
refresh_token
required
string

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsInJvbGUiOjIsInVzZXJfaWQiOjMwNDcsImV4cCI6MTYyNTkwODg3MywiaWF0IjoxNjI1MzA0MDczfQ.AhgGvP9vyJmwXpo3f1_q3yI1rvP47LFV_UPL9FcGbWKa8tfR9nop6rqSXBRNx1ZflM-rNUbQB63DQqRIXXXvPo0df3u9CQsrcMkNllmBzfoCv_vBlcx0k53CmUz0A9tINF5ypA30i57uUVQmvOf0JEf83-Xi6DkjCf2_e7mzc_Ab4XcYVpRrFUxuV5i1L0OL7U-V9CjcA1J92rzB6ZCPUi9v8vdziOcEdCYZRzGM1oxO07rpZkPj_0KOeuh7ecqW3s51z8R6_Sj8bOz0TuAnrDBmArfzbS3TRrNPBKtADhV62oCbRF8PuNjGZa89V6V_TkJmrZsMCZiHGXRPn63Dig"
}

Response samples

Content type
application/json
{
  • "token": "eyJ0eXNiOiJKV1QiXCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsInJvbGUiOjIsInVzZXJfaWQiOjMwNDcsImV4cCI6MTYyNTkwODg3MywiaWF0IjoxNjI1MzA0MDczfQ.AhgGvP9vyJmwXpo3f1_q3yI1rvP47LFV_UPL9FcGbWKa8tfR9nop6rqSXBRNx1ZflM-rNUbQB63DQqRIXXXvPo0df3u9CQsrcMkNllmBzfoCv_vBlcx0k53CmUz0A9tINF5ypA30i57uUVQmvOf0JEf83-Xi6DkjCf2_e7mzc_Ab4XcYVpRrFUxuV5i1L0OL7U-V9CjcA1J92rzB6ZCPUi9v8vdziOcEdCYZRzGM1oxO07rpZkPj_0KOeuh7ecqW3s51z8R6_Sj8bOz0TuAnrDBmArfzbS3TRrNPBKtADhV62oCbRF8PuNjGZa89V6V_TkJmrZsMCZiHGXRPn63Dig",
  • "refresh_token": "wqJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsInJvbGUiOjIsInVzZXJfaWQiOjMwNDcsImV4cCI6MTYyNTkwODg3MywiaWF0IjoxNjI1MzA0MDczfQ.AhgGvP9vyJmwXpo3f1_q3yI1rvP47LFV_UPL9FcGbWKa8tfR9nop6rqSXBRNx1ZflM-rNUbQB63DQqRIXXXvPo0df3u9CQsrcMkNllmBzfoCv_vBlcx0k53CmUz0A9tINF5ypA30i57uUVQmvOf0JEf83-Xi6DkjCf2_e7mzc_Ab4XcYVpRrFUxuV5i1L0OL7U-V9CjcA1J92rzB6ZCPUi9v8vdziOcEdCYZRzGM1oxO07rpZkPj_0KOeuh7ecqW3s51z8R6_Sj8bOz0TuAnrDBmArfzbS3TRrNPBKtADhV62oCbRF8PuNjGZa89V6V_TkJmrZsMCZiHGXRPn63Dig"
}

Reports

Get Current User Reports

Returns all reports that have been created by the current user.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Report

Allows scheduling Excel or JSON reports.

Legacy Excel reports (reports that are processed by https://github.com/systemsurveyor/ssv-reporting) cannot be scheduled using this endpoint. They need to be scheduled using POST /v2/report.

Authorizations:
jwt
Request Body schema: application/json
required
site_id
string

External ID of the report's site

survey_ids
Array of strings

List of external IDs of surveys in the report

output
string
Enum: "xls" "json"

Output format for the report

scope
string
Enum: "site" "survey"

Whether the report is a site report or survey report

report_name
string

Name given to the new report

report_definition_id
required
string

External ID of the report definition the new report belongs to

Responses

Request samples

Content type
application/json
{
  • "site_id": "de6e23c1-68e8-47eb-a2ef-78b472ec090d",
  • "survey_ids": [
    ],
  • "output": "xls",
  • "scope": "site",
  • "report_name": "My Bill of Materials report",
  • "report_definition_id": "f89b13b6-52cc-49de-90a2-cccda01bb0aa"
}

Response samples

Content type
application/json
{
  • "report_id": 2545
}

Get Report File

Retrieves a report result file after it has been generated. The user must have read access on the site the report was generated for

Authorizations:
jwt
query Parameters
path
required
string
Example: path=/www/data/export/pdf/12398/2024/1/b5d05d5a-d665-4adc-b5b9-60d1c296c695.pdf

Responses

Sites

Get User Sites and Site Folders

Returns all archived/unarchived sites and folders across all teams of a user.

Explanation of usage of filters:

Filtered by favorites:

  • All sites that are in workbench but not in a folder
  • All folders that have a site under them that is in the workbench
  • Don't return sites that are in workbench but also in a folder

Filtered by folder and favorites:

  • All sites in the folder that are in the workbench

Filtered by folder:

  • All sites in folder
Authorizations:
jwt
query Parameters
q
string
Example: q=foobar

Search

page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

filter[modified_after]
integer
Example: filter[modified_after]=1645157198

Return only sites that have been created, modified, or favorited (added to workbench) after an specific datetime (in UTC Epoch format).

filter[favorites_only]
integer
Example: filter[favorites_only]=1

Filters results to only include sites the user has added to their workbench

filter[folder_id]
string
Example: filter[folder_id]=963dcf8a-9c99-4da0-adeb-12b86d99b122

Returns only sites that belong to a specific folder

filter[accessible_after]
integer
Example: filter[accessible_after]=56489413165

Returns only sites and folders where the user has been granted access to after a specified time

Responses

Response samples

Content type
application/json
{
  • "sites": [
    ]
}

Delete Sites

Allows for batch deleting of sites (and all related data).

Users must be team members and have write access on all sites to be deleted, otherwise the entire operation will fail. Guest users are not allowed to batch delete sites.

Authorizations:
jwt
Request Body schema: application/json
required
Array
string

Site external ID

Responses

Request samples

Content type
application/json
[
  • "b14663f6-9ad1-40c0-8a1a-32f2e19b1ccb"
]

Get Current User's Sites

Returns all archived/unarchived sites that the current user has access to across all teams.

Authorizations:
jwt
query Parameters
page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

filter[modified_after]
integer
Example: filter[modified_after]=1645157198

Return only sites that have been created, modified, granted access to, or favorited after an specific datetime (in UTC Epoch format).

filter[favorites_only]
integer
Example: filter[favorites_only]=1

Filters results to only include sites the user has added to their workbench

Responses

Response samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "address": "123 Main St, Austin, TX 78701",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454,
  • "created_at": 3143434,
  • "modified_at": 45490509,
  • "survey_count": 53,
  • "favorited_ts": 1645157198
}

Create or Update Site

Creates a new site with a specific site_id or updates the site if it already exists. To create a site, pass a new UUID for the site_id. To update a site, pass the existing UUID for the site_id. You may pass a folder_external_id field in the payload to create the site inside that folder.

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Site ID

Request Body schema: application/json
required
id
string
name
string
city
string
state
string
zip_code
string
label
string
tags
Array of any
is_active
boolean
reference_id
string
custom_site_id
string
customer_external_id
string
team_id
integer

Responses

Request samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454
}

Response samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "address": "123 Main St, Austin, TX 78701",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454,
  • "created_at": 3143434,
  • "modified_at": 45490509
}

Patch Site

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Site ID

Request Body schema: application/json
required
id
string
name
string
city
string
state
string
zip_code
string
label
string
tags
Array of any
is_active
boolean
reference_id
string
custom_site_id
string
customer_external_id
string
team_id
integer

Responses

Request samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454
}

Response samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "address": "123 Main St, Austin, TX 78701",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454,
  • "created_at": 3143434,
  • "modified_at": 45490509
}

Delete Site

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Site ID

Responses

Get Site

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 074bb7b5-86d2-4ea6-9851-7f8a4397844f

Responses

Response samples

Content type
application/json
{
  • "id": "c3bfec95-bfaf-4c3c-b97d-403e71ea0f41",
  • "name": "Austin Airport",
  • "city": "Austin",
  • "state": "Texas",
  • "zip_code": "string",
  • "address": "123 Main St, Austin, TX 78701",
  • "label": "string",
  • "tags": [
    ],
  • "is_active": true,
  • "reference_id": "ref-12345",
  • "custom_site_id": "string",
  • "customer_external_id": "string",
  • "team_id": 454,
  • "created_at": 3143434,
  • "modified_at": 45490509
}

Add Sites to Favorites

Adds a list of sites to the user's workbench. Sites that are already in the workbench will be ignored.

Authorizations:
jwt
Request Body schema: application/json
required
Array
string

Site external ID

Responses

Request samples

Content type
application/json
[
  • "b14663f6-9ad1-40c0-8a1a-32f2e19b1ccb"
]

Remove Sites From Favorites

Removes sites from the current user's workbench. Sites that are not in the users workbench and are requested for removal will be ignored.

Authorizations:
jwt
Request Body schema: application/json
required
Array
string

Site ID

Responses

Request samples

Content type
application/json
[
  • "b14663f6-9ad1-40c0-8a1a-32f2e19b1ccb"
]

Get User Favorite Sites

Returns all of the current user's favorite sites across all teams. Results are ordered by most recently favorited.

Query Parameters:

  • filter[modified_after]: Return only sites that have been added or removed from favorites after the specified timestamp.
Authorizations:
jwt
query Parameters
page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

filter[modified_after]
integer
Example: filter[modified_after]=1645157198

Return only sites that have been added or removed from favorites after the specified timestamp.

Responses

Response samples

Content type
application/json
{
  • "favorite_sites": [
    ],
  • "unfavorited_sites": [
    ]
}

Get User Deleted Sites

Returns all sites and folders that have been deleted that a user had access to across all teams.

When called without a filter, returns all the deleted sites from entries found in the site audit table. Result are ordered by most recently deleted.

Authorizations:
jwt
query Parameters
page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

filter[deleted_after]
integer
Example: filter[deleted_after]=1645157198

Returns all sites and folders deleted after the input timestamp.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Surveys

Get Site Surveys and Folders

Returns all surveys and folders for a specific site. These are shown in the site overview page.

Surveys that belong to folders will not be included in the response, unless a search is being made.

Results are ordered by title ascending by default if no sorting is specified.

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Site ID

query Parameters
filter[status]
string
Enum: "archived" "open"

Return only surveys in a specific status (archived or open).

filter[external_folder_id]
string
Example: filter[external_folder_id]=b14663f6-9ad1-40c0-8a1a-32f2e19b1ccb

Filter surveys by folder using string of external_id (UUID)

filter[modified_after]
number
Example: filter[modified_after]=1658776598

Return only surveys and folders that have been created or modified after a timestamp (in UTC Epoch format).

filter[deleted_after]
number
Example: filter[deleted_after]=1658776598

Return surveys and folders that have been deleted after the specified timestamp.

sort
string
Enum: "id" "title" "document_image_url" "preview_image" "editor_id" "editor_first_name" "editor_last_name" "label" "element_count" "is_folder" "is_archived" "created_at" "modified_at" "status" "survey_count"
Example: sort=sort=-is_folder,name,editor_first_name

Sort by column names (comma separated). Use - prefix on column name to sort descending

q
string
Example: q=foobar

Search

page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

Responses

Response samples

Content type
application/json
{}

Delete Survey

Deletes a survey and all its related objects. Also expires any shares of the survey.

Only team members with write access can delete surveys, guest users cannot delete surveys.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Responses

Get Survey

Retrieves an entire survey object

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Responses

Response samples

Content type
application/json
{
  • "id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "title": "Harvard University",
  • "label": "string",
  • "reference_id": "string",
  • "description": "string",
  • "summary": "string",
  • "location": "string",
  • "status": "open",
  • "sync_status": "synced",
  • "site": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "team_id": 4590,
  • "customer_external_id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "icon_size": 0,
  • "is_archived": true,
  • "unit": "metric",
  • "version": 0,
  • "margin_range": 0,
  • "floorplan_scale": 0,
  • "preview_image": "2015/07/14/wyN60NaasBo320V7cNxcswXX.png",
  • "floorplan_url": "string",
  • "created_at": 0,
  • "modified_at": 0,
  • "modified_source": "web",
  • "boundaries": [
    ],
  • "elements": [
    ],
  • "annotations": [
    ],
  • "users": []
}

Lock Survey

Sets an editor lock on a survey so that other users cannot edit it. If the survey already has an editor lock from another user, the user requesting the lock will need to request the current editor to release the lock.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Responses

Remove Survey Lock

Removes a survey's current editor

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Responses

Clone Survey

Schedules an asynchronous job to clone an existing survey, copying all elements and related objects into a new survey.

All the binary files related to elements such as images and PDFs will also be cloned and assigned new paths.

An optional folder_id query parameter can be passed to specify the folder where the new survey will be placed. The folder must be in the same site as the survey being cloned.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey external ID

query Parameters
folder_id
string
Example: folder_id=86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Folder external ID

Responses

Response samples

Content type
application/json
{
  • "job_id": "86af1f1d-4f19-4c6c-afd6-e5ee041666ce"
}

Get Clone Survey Job Status

Returns the status of a clone survey job.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 123e4567-e89b-12d3-a456-426614174000

Survey external ID

job_id
required
string
Example: 123e4567-e89b-12d3-a456-426614174000

Clone job ID

Responses

Response samples

Content type
application/json
{
  • "status": "completed"
}

Move or Copy Survey

Moves a survey into a site or folder (that can contain surveys).

The list of possible sites and folders the survey can be moved to is provided by get_survey_move_destinations endpoint.

If the destination is a site, the user must have write access and the site should be in the same team as the site the survey belongs to. If the destination is a folder, the folder must be in the same team as the survey's site.

A copy operation can be performed instead by using a copy query parameter. This will create a new survey and move it to the specified destination, leaving the original survey intact. The new survey's external ID will be returned in the response.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

query Parameters
copy
boolean
Default: false

If set to true, the survey will be copied instead of moved. The original survey will remain intact.

Request Body schema: application/json
required
destination_id
required
string

External ID of the destination site or folder.

Responses

Request samples

Content type
application/json
{
  • "destination_id": "86af1f1d-4f19-4c6c-afd6-e5ee041666ce"
}

Response samples

Content type
application/json
{
  • "new_survey_id": "86af1f1d-4f19-4c6c-afd6-e5ee041666ce"
}

Schedule Survey Import

Schedules a new survey import job from an Excel file. Import jobs are done on existing surveys only.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Request Body schema:
required
Schema not provided

Responses

Response samples

Content type
application/json
{
  • "job_id": "86af1f1d-4f19-4c6c-afd6-e5ee041666ce"
}

Schedule Survey Export

Schedules a new survey export job.

The response will include the scheduled job's ID which the client can use to poll the get_survey_export endpoint for the finished result export file.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey ID

Responses

Response samples

Content type
application/json
{
  • "job_id": "86af1f1d-4f19-4c6c-afd6-e5ee041666ce"
}

Get Survey Move Destinations

Returns a list of all possible sites and folders that the user can move a survey to, within the same team of the survey.

Sites and folders that surveys can be moved to will be grouped by site folders, which are folders that can contain sites.

Authorizations:
jwt
path Parameters
survey_id
required
string
Example: 074bb7b5-86d2-4ea6-9851-7f8a4397844f

Responses

Sync Survey

Syncing works by creating a new survey with a unique identifier generated by the client, or updating the existing survey with that identifier if it exists along with all related elements, comments, annotations, etc. This operation overwrites all existing data related to the survey and replaces it with new objects created from the incoming request. Newly created surveys can also be directly placed inside folders by passing a folder_id value in the request payload.

Floorplans can be set for the survey by specifying the path in floorplan_url field. If no file exists in this path within the storage, the request will fail.

Only the survey editor can sync an existing survey.

Syncing Photo & PDF URLs

Due to backwards compatibility issues, in order to set survey element photos paths on sync the field photos needs to be used in the request instead of photo_urls. Likewise for PDFs a pdfs field must be used instead of pdf_urls

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Site external ID

survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey external ID

Request Body schema: application/json
required
title
required
string
label
string
reference_id
string
description
string
summary
string
location
string
status
string
Enum: "open" "archived"
icon_size
required
integer
unit
string
Enum: "metric" "imperial"
margin_range
required
number
floorplan_scale
number
floorplan_url
string
modified_source
string
Enum: "web" "tablet" "import" "api"
Array of objects (survey_boundary)
Array of objects (survey_element)
Array of objects (survey_annotation)

Responses

Request samples

Content type
application/json
{
  • "title": "Harvard University",
  • "label": "string",
  • "reference_id": "string",
  • "description": "string",
  • "summary": "string",
  • "location": "string",
  • "status": "open",
  • "icon_size": 0,
  • "unit": "metric",
  • "margin_range": 0,
  • "floorplan_scale": 0,
  • "floorplan_url": "string",
  • "modified_source": "web",
  • "boundaries": [
    ],
  • "elements": [
    ],
  • "annotations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "title": "Harvard University",
  • "label": "string",
  • "reference_id": "string",
  • "description": "string",
  • "summary": "string",
  • "location": "string",
  • "status": "open",
  • "sync_status": "synced",
  • "site": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "team_id": 4590,
  • "customer_external_id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "icon_size": 0,
  • "is_archived": true,
  • "unit": "metric",
  • "version": 0,
  • "margin_range": 0,
  • "floorplan_scale": 0,
  • "preview_image": "2015/07/14/wyN60NaasBo320V7cNxcswXX.png",
  • "floorplan_url": "string",
  • "created_at": 0,
  • "modified_at": 0,
  • "modified_source": "web",
  • "boundaries": [
    ],
  • "elements": [
    ],
  • "annotations": [
    ],
  • "users": []
}

Schedule Survey Sync

Allows scheduling a survey sync background job. A job ID will be returned after the job has been queued.

The request payload should contain the new complete state of the survey. If the new state is valid the survey will be asynchronously synced to this new state.

If the number of elements to sync exceeds the limit allowed by the current plan, a 422 error will be returned.

A sync job can be scheduled to create new surveys or sync existing ones. Only the survey editor can sync an existing survey.

In order to place a new survey within a folder, include a folder_id field containing the folder's external ID in the payload. The folder must be within the same site as the survey.

Syncing Photo URLs

Due to backwards compatibility issues, in order to set survey element photos paths on sync the field photos needs to be used in the request instead of photo_urls. Likewise for PDFs a pdfs field must be used instead of pdf_urls

Payload Compression

This endpoint can receive compressed payloads using GZIP compression algorithm. When sending gzip compressed payloads a Content-Encoding: gzip header must be used in the request.

Authorizations:
jwt
path Parameters
site_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Site external ID

survey_id
required
string
Example: 86af1f1d-4f19-4c6c-afd6-e5ee041666ce

Survey external ID

Request Body schema: application/json
required

The new survey structure to apply in the sync. Can be gzip compressed.

title
required
string
label
string
reference_id
string
description
string
summary
string
location
string
status
string
Enum: "open" "archived"
icon_size
required
integer
unit
string
Enum: "metric" "imperial"
margin_range
required
number
floorplan_scale
number
floorplan_url
string
modified_source
string
Enum: "web" "tablet" "import" "api"
Array of objects (survey_boundary)
Array of objects (survey_element)
Array of objects (survey_annotation)

Responses

Request samples

Content type
application/json
{
  • "title": "Harvard University",
  • "label": "string",
  • "reference_id": "string",
  • "description": "string",
  • "summary": "string",
  • "location": "string",
  • "status": "open",
  • "icon_size": 0,
  • "unit": "metric",
  • "margin_range": 0,
  • "floorplan_scale": 0,
  • "floorplan_url": "string",
  • "modified_source": "web",
  • "boundaries": [
    ],
  • "elements": [
    ],
  • "annotations": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": 9309340
}

Get Survey Sync Status

Allows polling the status of a scheduled sync job

Authorizations:
jwt
path Parameters
job_id
required
number <integer>
Example: 450540

Sync job ID

Responses

Response samples

Content type
application/json
{
  • "id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "title": "Harvard University",
  • "label": "string",
  • "reference_id": "string",
  • "description": "string",
  • "summary": "string",
  • "location": "string",
  • "status": "open",
  • "sync_status": "synced",
  • "site": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "team_id": 4590,
  • "customer_external_id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "icon_size": 0,
  • "is_archived": true,
  • "unit": "metric",
  • "version": 0,
  • "margin_range": 0,
  • "floorplan_scale": 0,
  • "preview_image": "2015/07/14/wyN60NaasBo320V7cNxcswXX.png",
  • "floorplan_url": "string",
  • "created_at": 0,
  • "modified_at": 0,
  • "modified_source": "web",
  • "boundaries": [
    ],
  • "elements": [
    ],
  • "annotations": [
    ],
  • "users": []
}

Teams

Get Current User Teams

Returns which teams a user is a part of, plan subscriptions, features access for the user as well as who owns the Team as the lead.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Team System Type Elements

Returns all the systemtype_elements for the given team

Authorizations:
jwt
path Parameters
team_id
required
number <integer>

The internal unique ID of the team

Responses

Response samples

Content type
application/json
{
  • "favorites": [
    ],
  • "infrastructure": [
    ],
  • "video_surveillance": [
    ],
  • "access_control": [
    ],
  • "fire_alarm": [
    ],
  • "communications": [
    ],
  • "building_management": [
    ],
  • "audio_visual": [
    ],
  • "facility_equipment": [
    ],
  • "healthcare": [
    ],
  • "information_technology": [
    ],
  • "intrusion_detection": [
    ]
}

Get Team Members

Returns information about all members of a team

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "company": "System Surveyor",
  • "email": "jdoe@gmail.com",
  • "avatar_url": "string",
  • "user_id": 140956,
  • "role": "admin",
  • "is_enable": true
}

Get Team Selected System Types

Authorizations:
jwt
path Parameters
team_id
required
number <integer>
Example: 309409

Team ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "abbreviation": "string",
  • "element_color": "string",
  • "sort": 0,
  • "elements": [
    ]
}

Element Profiles

Get Team Element Profiles

Returns all element profiles and accessories for a team.

Only team members are able to access element profiles for the specified team.

Results are ordered by sort_order field that is part of the element profile.

Authorizations:
jwt
path Parameters
team_id
required
integer
Example: 20730

Team internal ID

Responses

Response samples

Content type
application/json
{
  • "element_profiles": [
    ]
}

Get Element Profile Accessories

Returns all element profile accessories of a team for a specific element.

Results are sorted by description ascending by default.

Authorizations:
jwt
path Parameters
team_id
required
integer
Example: 20730

Team ID

element_id
required
integer
Example: 123

Element ID

query Parameters
q
string
Example: q=foobar

Search

page[number]
integer
Example: page[number]=2

Page Number

page[size]
integer
Example: page[size]=300

Page Size

Responses

Response samples

Content type
application/json
{
  • "count": 23,
  • "accessories": [
    ]
}

Schedule Element Profile Export

Schedule a background job for generating an Element Profile Excel export file for an element.

The generated export file can then be used to fill in new element profiles to be created using the import functionality.

Authorizations:
jwt
path Parameters
team_id
required
integer
element_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "job_id": "f804fa1f-fcbf-4d6d-85b4-d52995b83aac"
}

Get Element Profile Export

Fetches and returns an Element Profile export if it has been completed.

Authorizations:
jwt
path Parameters
job_id
required
string
Example: 4de325de-8e98-4e11-8a8b-ee163c717604

Responses

Get Element Profiles by Element

Returns all element profiles and accessories for a team and element.

Only team members are able to access element profiles for the specified team.

Results are ordered by sort_order field that is part of the element profile.

Authorizations:
jwt
path Parameters
team_id
required
string
Example: 20730

Team ID

element_id
required
string
Example: 170

Element ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Import Element Profiles

Schedules an Element Profile import job using an Element Profile Excel export file as input.

A validate_only=1 query param can be passed to make the background job only validate the input file. With this option, no importing process will be executed, changes to be applied by the importing process as well as any errors found will be temporarily cached. This data can later be checked using the get_import_status endpoint.

A append=1 query param can be passed to indicate that the import should not delete any existing element profiles and should only create or update the element profiles included in the import file.

Authorizations:
jwt
path Parameters
team_id
required
integer
element_id
required
integer
query Parameters
validate_only
integer

Only validate the import file and do not import any element profiles

append
integer

Only create new element profiles and do not delete existing profiles

Request Body schema: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
required
Schema not provided

Responses

Response samples

Content type
application/json
{
  • "job_id": "f804fa1f-fcbf-4d6d-85b4-d52995b83aac"
}

Get Element Profile Import Status

Allows querying the status of a scheduled Element Profile import job

Authorizations:
jwt
path Parameters
job_id
required
string
Example: 4de325de-8e98-4e11-8a8b-ee163c717604

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "filename": "f804fa1f-fcbf-4d6d-85b4-d52995b83aac.xlsx",
  • "errors": [
    ],
  • "changes": {
    }
}

Create Element Profile

Create a new Element Profile with accessories

Authorizations:
jwt
path Parameters
team_id
required
integer
element_id
required
integer
Request Body schema: application/json
required
name
required
string
is_default
boolean
sort
integer
object
Array of objects (element_profile_accessory)
team_id
integer
element_id
integer

Responses

Request samples

Content type
application/json
{
  • "name": "Video Camera Profile",
  • "is_default": true,
  • "sort": 0,
  • "content": {
    },
  • "accessories": [
    ],
  • "team_id": 0,
  • "element_id": 0
}

Response samples

Content type
application/json
{
  • "id": 1234,
  • "name": "Video Camera Profile",
  • "is_default": true,
  • "sort": 0,
  • "content": {
    },
  • "accessories": [
    ],
  • "created_by": 0,
  • "team_id": 0,
  • "element_id": 0,
  • "created_at": 0,
  • "modified_at": 0
}

Update Element Profile

Allows updating an existing Element Profile.

All current accessories of the Element Profile will be replaced by any new accessories sent in the request

Authorizations:
jwt
path Parameters
ep_id
required
integer
Example: 12309

ID of Element Profile

Request Body schema: application/json
required
name
required
string
is_default
boolean
sort
integer
object
Array of objects (element_profile_accessory)
team_id
integer
element_id
integer

Responses

Request samples

Content type
application/json
{
  • "name": "Video Camera Profile",
  • "is_default": true,
  • "sort": 0,
  • "content": {
    },
  • "accessories": [
    ],
  • "team_id": 0,
  • "element_id": 0
}

Response samples

Content type
application/json
{
  • "id": 1234,
  • "name": "Video Camera Profile",
  • "is_default": true,
  • "sort": 0,
  • "content": {
    },
  • "accessories": [
    ],
  • "created_by": 0,
  • "team_id": 0,
  • "element_id": 0,
  • "created_at": 0,
  • "modified_at": 0
}

Folders

Create or Update Folder

Creates a new site/survey folder or updates an existing one if found.

To create/update a site folder, pass a value for team_id field in the request payload, to create/update a survey folder pass a value for site_external_id field.

Authorizations:
jwt
path Parameters
folder_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Folder ID

Request Body schema: application/json
required
name
required
string

Folder name

label
string
site_external_id
string

Site external ID

team_id
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "site_external_id": "string",
  • "team_id": 0
}

Response samples

Content type
application/json
{
  • "id": "5f5eb9b1-7104-454f-b736-1ca962531b14",
  • "name": "string",
  • "label": "string",
  • "site_id": 0,
  • "team_id": 0,
  • "team": {
    },
  • "modified_at": 0
}

Delete Folder

Soft deletes a site folder or a survey folder.

Folder must be empty in order to be deleted.

Only account admins, team admins, and team members can delete folders. Only team members with write access can delete survey folders.

Authorizations:
jwt
path Parameters
folder_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Folder ID

Responses

Get Folder Sites

Returns the sites within a folder that the current user has access to.

Authorizations:
jwt
path Parameters
folder_id
required
string
Example: 40759717-c239-4504-a0a5-7e7f57220995

Folder ID

Responses

Users

Get Current User Data

Get data for the current authenticated user at a granular level.

The returned information includes information about the user that they provided at sign up as well as informationa about the teams they are a part of, company they are with and subscription they have with System Surveyor.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "id": 12094,
  • "user_name": "john_smith",
  • "first_name": "John",
  • "last_name": "Doe",
  • "title": "CEO",
  • "email": "foobar@gmail.com",
  • "company": "System Surveyor",
  • "mobile": "910-423-345",
  • "country": "United States of America (USA)",
  • "state": "Pennsylvania",
  • "city": "Los Angeles",
  • "avatar_url": "https://app.systemsurveyor.com/media/common/avatar.png",
  • "created_at": 1594652482,
  • "teams": [],
  • "accounts": [
    ]
}