Building Surveys
This Survey Definitions API is intended to allow programmatic creation and editing for surveys. We anticipate consumers of this API will use it as a platform on top of which they may build applications around surveys.
As this API covers creation, modification, activation, and publishing. The goal is to facilitate all steps in the survey lifecycle leading up to response collection.
Heads up
Qualtrics provides endpoints under both
/surveys/and/survey-definitions/namespaces. Endpoints in/survey-definitions/represent the survey in a different format, and with more granularity and completeness than the/surveys/namespace.
Survey Definition API Tenets
Use of HTTP Methods
| Verb | Action |
|---|---|
GET | Retrieve |
PUT | Update or Remove (some endpoints) |
POST | Create |
DELETE | Remove |
Use of HTTP Status Codes
| Verb | Action |
|---|---|
200 OK | Request was successful. |
400 Bad Request | Request was malformed. Error details are in the body content. Most often the request body contained an invalid parameter or definition. |
401 Unauthorized | Request credentials were invalid. Could be a problem with API access, credential mismatch, wrong datacenter in the hostname, or other authentication problems. |
403 Forbidden | Request credentials were authenticated, but the user was unauthorized to perform the operation. |
404 Not Found | Request was to a resource that does not exist. |
500 Internal Server Error | Qualtrics systems had an internal, unexpected error. |
Other | For any status code not defined here, check the general API V3 response code meaning definitions. |
The Survey Definition Structure
The survey definition has many elements, with many options and configurations on each. Some elements work together to provide complete functionality in the respondent experience.
Each type of element has its own set of endpoints, (e.g. Questions) with a definition determined by a predefined schema. Any request body that does not match the schema will have a 400 level response with details about how the body mismatched the schema.
Below we explain the purpose for each element supported by our API, and provide links to the specific docs for each available action.
Definition Elements Purpose
| Element | Purpose |
|---|---|
| Question | The prompt to display to a respondent along with possible inputs and their accompanying configurations. |
| Flow | Defines the order of presentation in the respondent experience. Also allows many behind-the-scenes operations such as Web Service integrations and respondent authenticators. |
| Block | A grouping of Questions with some configuration options. Blocks are the connection between Questions and Flow. |
| Options | Configuration about how the survey should behave (back button, theming, etc..) and how to handle various respondent scenarios (incompletes). |
| Quota Groups | Configure multiple quotas. Set up how to handle responses matching multiple quotas, and whether the quotas are visible in a public dashboard. |
| Quotas | Count responses from custom groups of people. Screen out respondents from completing your survey based on custom logic and criteria. |
| Metadata | Meta information about the survey that links to other Qualtrics entities such as User and Brand. |
| Survey | Container for all elements, links to other Qualtrics entities. The Metadata (above) describes existing Surveys. |
| Languages | The possible languages that the Survey can be localized into. |
| Translations | The words used to localize a given Question's prompts and inputs into a Language. |
API Endpoints Overview
| Element | Retrieve | Create | Update | Remove |
|---|---|---|---|---|
| Question | GET & LIST | POST | PUT | DELETE |
| Flow | GET | ✖️ | PUT-flow & PUT-element | ✖️ |
| Block | GET | POST | PUT | DELETE |
| Options | GET | ✖️ | PUT | ✖️ |
| Quota Groups) | GET | POST | PUT | DELETE |
| Quotas | GET & LIST | POST | PUT | DELETE |
| Metadata | GET | ✖️ | ✖️ | ✖️ |
| Survey | GET & LIST | POST | PUT | DELETE |
| Version | GET & LIST | POST | ✖️ | ✖️ |
| Languages | GET | ✖️ | PUT | ✖️ |
| Translations | GET | ✖️ | PUT | ✖️ |
Pro Tip
If there is a feature not shown in any examples, you can recreate that feature through the Survey Editor UI. Performing a
GETon the whole survey will return the complete feature definition, which can be used as a template when consuming this API.
Getting Started - Next Steps
Now that you have a good picture of the purpose and capabilities of this API, you're ready to use our simple getting started walkthrough. It will take you through the main steps of creating, configuring, modifying, and publishing your survey.
Good luck and happy surveying!