The Surveys API

This section contains a detailed description of the Confirmit Surveys REST API available for handling of Surveys and Survey Data.

Parts of the documentation has been automatically generated based on the OpenApi specification (formerly known as Swagger).

Click Swagger for a live experience of the documentation.

Survey Info

The '/v1/surveys' - endpoint allows the client (user) to list surveys the client has access to. The response will contain basic information about each survey.

The '/v1/surveys/{surveyId}' - endpoint will return more details for a specific survey.

Survey Launch

The '/v1/surveys/{surveyId}/launches' - endpoint can be used to launch surveys, cancel launches and get information about launch processes.

When you have finished constructing your survey schema and you want to test it, you must first create a survey database. This process is called launching. Note that every time you make changes in the schema, you must update the database by re-launching the survey.

Survey Import / Export

The '/v1/surveys' - endpoint can be used to import survey definition.

The '*/v1/surveys/{surveyId}' - endpoint can be used to export survey definition by Id.

It is possible to get zipped XML survey definition by requesting an export endpoint and providing survey Id. A similar ZIP file with XML survey definition can be used to create a new survey. This is done by requesting an import endpoint and providing a zip file. A survey Id of created instance is returned.

Survey Data

Survey Data consists of Respondents and Responses. In general a respondent contains information about a person taking a survey, while a response contains the data the person answered in the survey. Both respondent and response data are represented as SurveyDataRecords.

Survey Data Schema

A Survey Data Schema contains the metadata for each datacell in a SurveyDataRecord. The schema contains data levels, and each level contains sets of keys and variables.

Respondent Data Schema

The '/v1/surveys/{surveyId}/respondents/schema' - endpoint returns the schema for respondent data. The schema contains only one level with Name='respondent'. There are three types of respondent variables; system-, background- and user-variables.

  • System variables are created by Confirmit when setting up the survey database.

  • Background variables are variables created when designing the survey in Survey Designer. These variables are not displayed in the survey, but copied from the respondent record to the response record during runtime of the survey.

  • User variables are extra information about a respondent. These variables can either be added when uploading respondents from a file, or they can be added using the '/v1/surveys/{surveyId}/respondents/uservariables' - endpoint.

Response Data Schema

The '/v1/surveys/{surveyId}/responses/schema' - endpoint returns the schema for response data. As the survey can have loops, and loops inside loops, the schema is hierarchical where each level has a Children property containing a list of the Loops on that level. A Loop is again represented as a level. The top level in the schema is called 'response' and has all the questions that are not in a loop. The loop levels have a name based on the id of the loop in the survey.

Each level in the schema has a Variables property. Some of the variables are system variables, like 'status' and 'interview_start', whereas the other variables will match the questions in the survey.

Respondent Data

The '/v1/surveys/{surveyId}/respondents/data' - endpoint can be used to handle Respondent Data. Both read and write operations are supported.

When reading/writing respondent data, you can specify which variables to read or write. Variables not mentioned in the operation will not be touched.

Response Data

The '/v1/surveys/{surveyId}/responses/data' - endpoint can be used to handle Response Data. Both read and write operations are supported.

Response Data contains the answers each respondent provided when taking a survey. The response from the endpoint contains SurveyDataRecords where each record is a hierarchical representation of the respondents answers.