Managing Surveys
This guide walks through the Qualtrics APIs to manage your surveys. These survey APIs allow you to retrieve a list of your surveys (with the List Surveys API). You can get detailed information about a survey with the Get Survey API. The Update Survey API lets you change a survey's metadata, the Import Survey API lets you create a new survey by importing its definition, and the Import Survey From URL lets you import a survey from a website. Finally, you can delete a survey with the Delete Survey API.
Survey Responses
If you'd like to retrieve your users' responses to a survey, see Getting Survey Responses instead.
Sample code
The sample code in this document uses Python 3 and the requests library. If you have pip installed, you can use it to install requests:
Code and Qualtrics Support
Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.
pip install requests
Some installations (usually those with both Python 2 and Python 3 installed) require you to use pip3 instead:
pip3 install requests
(The pip command might also be called pip3.6 or something similar.)
Get Survey
You can get an individual survey's design using the Get Survey API. The information returned represents only the design of the survey and does not include details about how people answered your survey’s questions. For help getting your survey's responses, see Response Export Workflow.
For more information about the user interface for creating and editing surveys, see "Survey Module Overview".
Get Survey Format
No APIs allow the data returned by the Get Survey API to be re-imported (such as after modifying it).
The Get Survey API returns information that we'll break into two parts. The first part is information about the survey (its metadata). The second group of information is the survey's content (its design).
The metadata returned by the Get Survey API includes:
- The survey’s ID
- The survey’s name
- The survey owner’s ID
- The organization’s ID
- Whether the survey is active
- The creation date and time of the survey
- Its last modified date and time
- When the survey expires
(For more information about Qualtrics IDs, see Finding Your Qualtrics IDs.)
The information about the survey's design includes:
- Information about the survey’s questions such as type (see Question Types Overview) and the question and answer text (if applicable)
- The survey’s blocks (see Block Options Overview)
- The survey’s flow (see Survey Flow Overview)
- The survey’s embedded data (see Embedded Data)
- Comments
- Loop and merge information (see Loop & Merge)
- Counts of the survey’s responses (see Survey Response Counts)
To retrieve a survey, you need the following information:
- Your API token (needed for all API calls), item 1 in the sample below
- Your data center (needed for all API calls), item 2 in the sample below
- A Survey ID, item 3 in the sample below
To find these IDs, see Finding Qualtrics IDs.
The following Python 3 sample shows how to obtain a JSON object that represents a survey:
# Get Survey API
import os
import requests
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
surveyId = "YOUR SURVEY ID" # 3
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}".format(dataCenter, surveyId)
headers = {
"x-api-token": apiToken,
}
response = requests.get(baseUrl, headers=headers)
print(response.text)
Fill in the values for apiToken, surveyId, and dataCenter before running.
The results object in the returned JSON object has the following members:
| Member | Type | Description |
|---|---|---|
| blocks | Object | Contains information about the survey's blocks. See the Blocks table below for more information. |
| comments | Object | Discussion around questions. See the Comments table below for more information. |
| creationDate | String | The date and time the survey was created. See Dates and Times for more information on the date and time format. |
| embeddedData | Array of Objects | Each object in embeddedData contains two members, name and defaultValue |
| expiration | Object | Contains two members, endDate and startDate that express the date range during which the survey is valid. See Dates and Times for more information on the date and time format. |
| exportColumnMap | Object | Maps your questions to their internal question IDs. The members in this object are the names you've defined for your questions, such as Q1. The value for each member is a object that contains the member question and the value is a string representing the question ID, such as QID1. |
| flow | Array of Objects | The flow array represents the order of items that make up the survey. Each object in the flow array contains a type member that identifies the block. There are sometimes type members in the object that indicate the type of block in the flow. |
| id | String | The survey ID. The same value that was used to retrieve the survey. |
| isActive | Boolean | Indicates whether the survey is currently active. For more information on deactivating a survey, see Deactivating a Survey. |
| lastModifiedDate | String | The date and time (UTC time zone) the survey was last modified. See Dates and Times for more information on the date and time format. |
| loopAndMerge | Object | Each member in this object is a block ID whose value is a object with four members: columnNames, loopQuestionMeta, loopType, and randomizationMeta. See the Loop and Merge table below for more information. |
| name | String | The name of the survey. It is also the same as the project name. |
| organizationId | String | The organization's ID. The same as the dataCenter value in the above sample code. |
| ownerId | String | The user ID of the owner of the survey. |
| questions | Object | A object containing the entire set of questions from your survey. See the Questions table below for more information. |
| responseCounts | Object | Contains three members, auditable, deleted, and generated which contain counts of responses. |
Blocks
The blocks object's members are block IDs, such as "BL_1234567890" and inside each block is an object with these members:
| Member | Type | Description |
|---|---|---|
| description | String | The description given to the block (typically defined in the Survey UI). |
| elements | Array of Objects | Each object in the elements array contains two members, type and questionId. |
Comments
The comments object contains members for each question ID that has comments (or notes). Each question has a commentList array of one object per comment. For example:
"comments": {
"QID1": {
"commentList": [
{
"message": "Some note text for question Q1",
"timestamp": 1495745520,
"userId": "UR_1234567890"
}
]
}
}
The objects in the commentList array consist of the following:
| Member | Type | Description |
|---|---|---|
| message | String | The message attached to this question. |
| timestamp | Number | Unix epoch time (seconds since base time of January 1, 1970). |
| userId | String | The user who created this comment. |
If there are no comments, the comments object is empty.
Export Column Map
The exportColumnMap is useful for mapping the names you've given to your questions with the internal identifiers (question IDs) that Qualtrics uses to identify your questions. When tabulating responses to your survey, this information is particularly useful. For more information about survey responses, see Response Export Workflow.
The following table shows the export column map for the questions described in the Questions section below:
"Q1": {
"question": "QID1"
},
"Q2": {
"question": "QID2"
},
"Q3": {
"question": "QID3"
},
"Q4_1": {
"question": "QID4",
"subQuestion": "QID4.subQuestions.1"
},
"Q4_2": {
"question": "QID4",
"subQuestion": "QID4.subQuestions.2"
},
"Q4_3": {
"question": "QID4",
"subQuestion": "QID4.subQuestions.3"
},
"Q5": {
"question": "QID5"
},
"Q6_1": {
"choice": "QID6.choices.1",
"question": "QID6"
},
"Q6_2": {
"choice": "QID6.choices.2",
"question": "QID6"
},
"Q6_3": {
"choice": "QID6.choices.3",
"question": "QID6"
},
"Q7_1": {
"choice": "QID7.choices.1",
"question": "QID7"
},
"Q7_2": {
"choice": "QID7.choices.2",
"question": "QID7"
},
"Q7_3": {
"choice": "QID7.choices.3",
"question": "QID7"
},
"Q8#1_1": {
"column": "QID8.columns.1",
"question": "QID8",
"subQuestion": "QID8.subQuestions.1"
},
"Q8#1_2": {
"column": "QID8.columns.1",
"question": "QID8",
"subQuestion": "QID8.subQuestions.2"
},
"Q8#1_3": {
"column": "QID8.columns.1",
"question": "QID8",
"subQuestion": "QID8.subQuestions.3"
},
"Q8#2_1": {
"column": "QID8.columns.2",
"question": "QID8",
"subQuestion": "QID8.subQuestions.1"
},
"Q8#2_2": {
"column": "QID8.columns.2",
"question": "QID8",
"subQuestion": "QID8.subQuestions.2"
},
"Q8#2_3": {
"column": "QID8.columns.2",
"question": "QID8",
"subQuestion": "QID8.subQuestions.3"
},
"Q9_1": {
"choice": "QID9.choices.1",
"question": "QID9"
},
"Q9_2": {
"choice": "QID9.choices.2",
"question": "QID9"
},
"Q9_3": {
"choice": "QID9.choices.3",
"question": "QID9"
}
"Q10_1_Group": {
"item": "QID10.items.1",
"question": "QID10"
},
"Q10_1_Rank": {
"item": "QID10.items.1",
"question": "QID10"
},
"Q10_2_Group": {
"item": "QID10.items.2",
"question": "QID10"
},
"Q10_2_Rank": {
"item": "QID10.items.2",
"question": "QID10"
},
"Q10_3_Group": {
"item": "QID10.items.3",
"question": "QID10"
},
"Q10_3_Rank": {
"item": "QID10.items.3",
"question": "QID10"
},
# question type will not return json
"Q12_1_x": {
"question": "QID12"
},
"Q12_1_y": {
"question": "QID12"
},
"Q13_1": {
"question": "QID13",
"subQuestion": "QID13.subQuestions.1"
},
"Q13_2": {
"question": "QID13",
"subQuestion": "QID13.subQuestions.2"
},
"Q13_3": {
"question": "QID13",
"subQuestion": "QID13.subQuestions.3"
},
"Q14": {
"question": "QID14"
},
"Q15_10": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.10"
},
"Q15_11": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.11"
},
"Q15_12": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.12"
},
"Q15_13": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.13"
},
"Q15_14": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.14"
},
"Q15_15": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.15"
},
"Q15_16": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.16"
},
"Q15_17": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.17"
},
"Q15_18": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.18"
},
"Q15_19": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.19"
},
"Q15_20": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.20"
},
"Q15_21": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.21"
},
"Q15_22": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.22"
},
"Q15_23": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.23"
},
"Q15_24": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.24"
},
"Q15_25": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.25"
},
"Q15_26": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.26"
},
"Q15_27": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.27"
},
"Q15_28": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.28"
},
"Q15_29": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.29"
},
"Q15_30": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.30"
},
"Q15_31": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.31"
},
"Q15_32": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.32"
},
"Q15_33": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.33"
},
"Q15_34": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.34"
},
"Q15_35": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.35"
},
"Q15_36": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.36"
},
"Q15_37": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.37"
},
"Q15_38": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.38"
},
"Q15_39": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.39"
},
"Q15_4": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.4"
},
"Q15_40": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.40"
},
"Q15_41": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.41"
},
"Q15_42": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.42"
},
"Q15_43": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.43"
},
"Q15_44": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.44"
},
"Q15_45": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.45"
},
"Q15_5": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.5"
},
"Q15_6": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.6"
},
"Q15_7": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.7"
},
"Q15_8": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.8"
},
"Q15_9": {
"question": "QID15",
"subQuestion": "QID15.subQuestions.9"
},
"Q16_FILE_ID": {
"question": "QID16"
},
"Q16_FILE_NAME": {
"question": "QID16"
},
"Q16_FILE_SIZE": {
"question": "QID16"
},
"Q16_FILE_TYPE": {
"question": "QID16"
},
"Q17_1": {
"choice": "QID17.choices.1",
"question": "QID17"
},
"Q17_2": {
"choice": "QID17.choices.2",
"question": "QID17"
},
"Q17_3": {
"choice": "QID17.choices.3",
"question": "QID17"
},
"Q17_4": {
"choice": "QID17.choices.4",
"question": "QID17"
},
"Q18_1_TEXT": {
"choice": "QID18.choices.1",
"question": "QID18"
},
"Q18_2_TEXT": {
"choice": "QID18.choices.2",
"question": "QID18"
},
"Q18_3_TEXT": {
"choice": "QID18.choices.3",
"question": "QID18"
},
"Q18_4_TEXT": {
"choice": "QID18.choices.4",
"question": "QID18"
},
"Q18_5_TEXT": {
"choice": "QID18.choices.5",
"question": "QID18"
},
"Q18_6_TEXT": {
"choice": "QID18.choices.6",
"question": "QID18"
},
"Q18_7_TEXT": {
"choice": "QID18.choices.7",
"question": "QID18"
},
# question type will not return json
Loop and Merge
The loopAndMerge object contains block IDs as members and objects as values.
The possible loop types for loop and merge are static and question. If the loop is static it will always loop the same regardless of previous answers selected. If the loop type is question, then there will be a criterion in the loopOn array member which will say what you are looping on ("UnselectedChoices," "SelectedChoices," etc.). The loopQuestionMeta also provides the questionId and questionType of the question that is being used to loop on. If "Randomize loop order" is enabled the randomizationMeta will contain information about how many loops the question will go through.
The loopAndMerge object contains the following information:
| Member | Type | Description |
|---|---|---|
| columnNames | Object | Is an object with members such as field1, field2, etc. Each value associated with a field contains and array of the values that appear in that field. |
| loopQuestionMeta | Object | Contains an object that references the question defined by the loop. |
| loopType | String | Type of loop either "Question" or "Static." |
| randomizationMeta | Object | Indicates how the loop is randomized (if enabled in the survey design). |
Questions
The questions object contains information about the questions that make up your survey. Each member in the questions object is the question ID, and its value is an object that defines the question. For example, in the following Multiple Choice snippet, the question ID is QID1, which is a multiple-choice question. Each choice is a member (1, 2, and 3) that contains an object with members that describe that choice. Other question types have different objects that describe the question.
"QID1": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Choice 1",
"description": "Click to write Choice 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Click to write Choice 2",
"description": "Click to write Choice 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Click to write Choice 3",
"description": "Click to write Choice 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q1",
"questionText": "Multiple choice<div><br /></div>",
"questionType": {
"selector": "SAVR",
"subSelector": "TX",
"type": "MC"
},
"validation": {
"doesForceResponse": false
}
},
"QID2": {
"questionLabel": null,
"questionName": "Q2",
"questionText": "Descriptive Text<div><br /></div>",
"questionType": {
"selector": "TB",
"subSelector": null,
"type": "DB"
},
"validation": {
"doesForceResponse": false
}
},
"QID3": {
"questionLabel": null,
"questionName": "Q3",
"questionText": "Click to write the question text",
"questionType": {
"selector": "GRB",
"subSelector": "WOTXB",
"type": "DB"
},
"validation": {
"doesForceResponse": false
}
},
"QID4": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Scale point 1",
"description": "Click to write Scale point 1",
"imageDescription": null,
"recode": "1"
},
"2": {
"analyze": true,
"choiceText": "Click to write Scale point 2",
"description": "Click to write Scale point 2",
"imageDescription": null,
"recode": "2"
},
"3": {
"analyze": true,
"choiceText": "Click to write Scale point 3",
"description": "Click to write Scale point 3",
"imageDescription": null,
"recode": "3"
}
},
"questionLabel": null,
"questionName": "Q4",
"questionText": "Matrix table",
"questionType": {
"selector": "Likert",
"subSelector": "SingleAnswer",
"type": "Matrix"
},
"subQuestions": {
"1": {
"choiceText": "Click to write Statement 1",
"description": "Click to write Statement 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"choiceText": "Click to write Statement 2",
"description": "Click to write Statement 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"choiceText": "Click to write Statement 3",
"description": "Click to write Statement 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"validation": {
"doesForceResponse": false
}
},
"QID5": {
"questionLabel": null,
"questionName": "Q5",
"questionText": "Text entry",
"questionType": {
"selector": "SL",
"subSelector": null,
"type": "TE"
},
"validation": {
"doesForceResponse": false
}
},
"QID6": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Choice 1",
"description": "Click to write Choice 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Click to write Choice 2",
"description": "Click to write Choice 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Click to write Choice 3",
"description": "Click to write Choice 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q6",
"questionText": "Slider",
"questionType": {
"selector": "HSLIDER",
"subSelector": null,
"type": "Slider"
},
"validation": {
"doesForceResponse": false
}
},
"QID7": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Item 1",
"description": "Click to write Item 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Click to write Item 2",
"description": "Click to write Item 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Click to write Item 3",
"description": "Click to write Item 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q7",
"questionText": "Rank order",
"questionType": {
"selector": "DND",
"subSelector": "TX",
"type": "RO"
},
"validation": {
"doesForceResponse": false
}
},
"QID8": {
"columns": {
"1": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Answer 1",
"description": "Answer 1",
"imageDescription": null,
"recode": "1"
},
"2": {
"analyze": true,
"choiceText": "Answer 2",
"description": "Answer 2",
"imageDescription": null,
"recode": "2"
}
},
"questionLabel": null,
"questionText": "Click to write Column 1",
"questionType": {
"selector": "Likert",
"subSelector": "SingleAnswer",
"type": "Matrix"
},
"validation": {
"doesForceResponse": false
}
},
"2": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Answer 1",
"description": "Answer 1",
"imageDescription": null,
"recode": "1"
},
"2": {
"analyze": true,
"choiceText": "Answer 2",
"description": "Answer 2",
"imageDescription": null,
"recode": "2"
}
},
"questionLabel": null,
"questionText": "Click to write Column 2",
"questionType": {
"selector": "Likert",
"subSelector": "SingleAnswer",
"type": "Matrix"
},
"validation": {
"doesForceResponse": false
}
}
},
"questionLabel": null,
"questionName": "Q8",
"questionText": "Side by side",
"questionType": {
"selector": "SBSMatrix",
"subSelector": null,
"type": "SBS"
},
"subQuestions": {
"1": {
"choiceText": "Click to write Statement 1",
"description": "Click to write Statement 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"choiceText": "Click to write Statement 2",
"description": "Click to write Statement 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"choiceText": "Click to write Statement 3",
"description": "Click to write Statement 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"validation": {
"doesForceResponse": false
}
},
"QID9": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Choice 1",
"description": "Click to write Choice 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Click to write Choice 2",
"description": "Click to write Choice 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Click to write Choice 3",
"description": "Click to write Choice 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q9",
"questionText": "Constant sum",
"questionType": {
"selector": "VRTL",
"subSelector": "TX",
"type": "CS"
},
"validation": {
"doesForceResponse": false
}
}
"QID10": {
"groups": {
"0": {
"description": "Click to write Group 1",
"recode": "0"
},
"1": {
"description": "Click to write Group 2",
"recode": "1"
},
"2": {
"description": "Click to write Group 3",
"recode": "2"
}
},
"items": {
"1": {
"analyze": true,
"description": "Click to write Item 1",
"imageDescription": null
},
"2": {
"analyze": true,
"description": "Click to write Item 2",
"imageDescription": null
},
"3": {
"analyze": true,
"description": "Click to write Item 3",
"imageDescription": null
}
},
"questionLabel": null,
"questionName": "Q10",
"questionText": "Pick group and rank",
"questionType": {
"selector": "DragAndDrop",
"subSelector": "NoColumns",
"type": "PGR"
},
"validation": {
"doesForceResponse": false
}
},
"QID11": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Dislike",
"description": "Dislike",
"imageDescription": null,
"recode": "1"
},
"2": {
"analyze": true,
"choiceText": "Neutral",
"description": "Neutral",
"imageDescription": null,
"recode": "2"
},
"3": {
"analyze": true,
"choiceText": "Like",
"description": "Like",
"imageDescription": null,
"recode": "3"
}
},
"questionLabel": null,
"questionName": "Q11",
"questionText": "Hot spot",
"questionType": {
"selector": "LikeDislike",
"subSelector": null,
"type": "HotSpot"
},
"validation": {
"doesForceResponse": false
}
},
"QID12": {
"questionLabel": null,
"questionName": "Q12",
"questionText": "Heat map",
"questionType": {
"selector": "Image",
"subSelector": null,
"type": "HeatMap"
},
"regions": {},
"validation": {
"doesForceResponse": false
}
},
"QID13": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Click to write Choice 1",
"description": "Click to write Choice 1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Click to write Choice 2",
"description": "Click to write Choice 2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Click to write Choice 3",
"description": "Click to write Choice 3",
"imageDescription": null,
"recode": "3",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q13",
"questionText": "Drill down",
"questionType": {
"selector": "DL",
"subSelector": null,
"type": "DD"
},
"validation": {
"doesForceResponse": false
}
},
"QID14": {
"choices": {
"0": {
"analyze": true,
"choiceText": "0",
"description": "0",
"imageDescription": null,
"recode": "0",
"variableName": null
},
"1": {
"analyze": true,
"choiceText": "1",
"description": "1",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"10": {
"analyze": true,
"choiceText": "10",
"description": "10",
"imageDescription": null,
"recode": "10",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "2",
"description": "2",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "3",
"description": "3",
"imageDescription": null,
"recode": "3",
"variableName": null
},
"4": {
"analyze": true,
"choiceText": "4",
"description": "4",
"imageDescription": null,
"recode": "4",
"variableName": null
},
"5": {
"analyze": true,
"choiceText": "5",
"description": "5",
"imageDescription": null,
"recode": "5",
"variableName": null
},
"6": {
"analyze": true,
"choiceText": "6",
"description": "6",
"imageDescription": null,
"recode": "6",
"variableName": null
},
"7": {
"analyze": true,
"choiceText": "7",
"description": "7",
"imageDescription": null,
"recode": "7",
"variableName": null
},
"8": {
"analyze": true,
"choiceText": "8",
"description": "8",
"imageDescription": null,
"recode": "8",
"variableName": null
},
"9": {
"analyze": true,
"choiceText": "9",
"description": "9",
"imageDescription": null,
"recode": "9",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q14",
"questionText": "Net promoter score",
"questionType": {
"selector": "NPS",
"subSelector": null,
"type": "MC"
},
"validation": {
"doesForceResponse": false
}
},
"QID15": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Like",
"description": "Like",
"imageDescription": null,
"recode": "1"
},
"2": {
"analyze": true,
"choiceText": "Neither like nor dislike",
"description": "Neither like nor dislike",
"imageDescription": null,
"recode": "2"
},
"3": {
"analyze": true,
"choiceText": "Dislike",
"description": "Dislike",
"imageDescription": null,
"recode": "3"
}
},
"questionLabel": null,
"questionName": "Q15",
"questionText": "Highlight",
"questionType": {
"selector": "Text",
"subSelector": null,
"type": "HL"
},
"subQuestions": {
"10": {
"choiceText": "7: highlight",
"description": "7: highlight",
"imageDescription": null,
"recode": "10",
"variableName": null
},
"11": {
"choiceText": "8: with",
"description": "8: with",
"imageDescription": null,
"recode": "11",
"variableName": null
},
"12": {
"choiceText": "9: the",
"description": "9: the",
"imageDescription": null,
"recode": "12",
"variableName": null
},
"13": {
"choiceText": "10: above",
"description": "10: above",
"imageDescription": null,
"recode": "13",
"variableName": null
},
"14": {
"choiceText": "11: color",
"description": "11: color",
"imageDescription": null,
"recode": "14",
"variableName": null
},
"15": {
"choiceText": "12: categories.",
"description": "12: categories.",
"imageDescription": null,
"recode": "15",
"variableName": null
},
"16": {
"choiceText": "13: To",
"description": "13: To",
"imageDescription": null,
"recode": "16",
"variableName": null
},
"17": {
"choiceText": "14: edit",
"description": "14: edit",
"imageDescription": null,
"recode": "17",
"variableName": null
},
"18": {
"choiceText": "15: this",
"description": "15: this",
"imageDescription": null,
"recode": "18",
"variableName": null
},
"19": {
"choiceText": "16: text,",
"description": "16: text,",
"imageDescription": null,
"recode": "19",
"variableName": null
},
"20": {
"choiceText": "17: click",
"description": "17: click",
"imageDescription": null,
"recode": "20",
"variableName": null
},
"21": {
"choiceText": "18: on",
"description": "18: on",
"imageDescription": null,
"recode": "21",
"variableName": null
},
"22": {
"choiceText": "19: the",
"description": "19: the",
"imageDescription": null,
"recode": "22",
"variableName": null
},
"23": {
"choiceText": "20: link",
"description": "20: link",
"imageDescription": null,
"recode": "23",
"variableName": null
},
"24": {
"choiceText": "21: below.",
"description": "21: below.",
"imageDescription": null,
"recode": "24",
"variableName": null
},
"25": {
"choiceText": "22: Click",
"description": "22: Click",
"imageDescription": null,
"recode": "25",
"variableName": null
},
"26": {
"choiceText": "23: between",
"description": "23: between",
"imageDescription": null,
"recode": "26",
"variableName": null
},
"27": {
"choiceText": "24: the",
"description": "24: the",
"imageDescription": null,
"recode": "27",
"variableName": null
},
"28": {
"choiceText": "25: words",
"description": "25: words",
"imageDescription": null,
"recode": "28",
"variableName": null
},
"29": {
"choiceText": "26: to",
"description": "26: to",
"imageDescription": null,
"recode": "29",
"variableName": null
},
"30": {
"choiceText": "27: combine",
"description": "27: combine",
"imageDescription": null,
"recode": "30",
"variableName": null
},
"31": {
"choiceText": "28: or",
"description": "28: or",
"imageDescription": null,
"recode": "31",
"variableName": null
},
"32": {
"choiceText": "29: separate",
"description": "29: separate",
"imageDescription": null,
"recode": "32",
"variableName": null
},
"33": {
"choiceText": "30: them.",
"description": "30: them.",
"imageDescription": null,
"recode": "33",
"variableName": null
},
"34": {
"choiceText": "31: Clicking",
"description": "31: Clicking",
"imageDescription": null,
"recode": "34",
"variableName": null
},
"35": {
"choiceText": "32: directly",
"description": "32: directly",
"imageDescription": null,
"recode": "35",
"variableName": null
},
"36": {
"choiceText": "33: on",
"description": "33: on",
"imageDescription": null,
"recode": "36",
"variableName": null
},
"37": {
"choiceText": "34: words",
"description": "34: words",
"imageDescription": null,
"recode": "37",
"variableName": null
},
"38": {
"choiceText": "35: will",
"description": "35: will",
"imageDescription": null,
"recode": "38",
"variableName": null
},
"39": {
"choiceText": "36: allow",
"description": "36: allow",
"imageDescription": null,
"recode": "39",
"variableName": null
},
"4": {
"choiceText": "1: This",
"description": "1: This",
"imageDescription": null,
"recode": "4",
"variableName": null
},
"40": {
"choiceText": "37: or",
"description": "37: or",
"imageDescription": null,
"recode": "40",
"variableName": null
},
"41": {
"choiceText": "38: disallow",
"description": "38: disallow",
"imageDescription": null,
"recode": "41",
"variableName": null
},
"42": {
"choiceText": "39: respondents",
"description": "39: respondents",
"imageDescription": null,
"recode": "42",
"variableName": null
},
"43": {
"choiceText": "40: from",
"description": "40: from",
"imageDescription": null,
"recode": "43",
"variableName": null
},
"44": {
"choiceText": "41: highlighting",
"description": "41: highlighting",
"imageDescription": null,
"recode": "44",
"variableName": null
},
"45": {
"choiceText": "42: them.",
"description": "42: them.",
"imageDescription": null,
"recode": "45",
"variableName": null
},
"5": {
"choiceText": "2: is",
"description": "2: is",
"imageDescription": null,
"recode": "5",
"variableName": null
},
"6": {
"choiceText": "3: the",
"description": "3: the",
"imageDescription": null,
"recode": "6",
"variableName": null
},
"7": {
"choiceText": "4: text",
"description": "4: text",
"imageDescription": null,
"recode": "7",
"variableName": null
},
"8": {
"choiceText": "5: you",
"description": "5: you",
"imageDescription": null,
"recode": "8",
"variableName": null
},
"9": {
"choiceText": "6: can",
"description": "6: can",
"imageDescription": null,
"recode": "9",
"variableName": null
}
},
"validation": {
"doesForceResponse": false
}
},
"QID16": {
"questionLabel": null,
"questionName": "Q16",
"questionText": "Signature",
"questionType": {
"selector": "Signature",
"subSelector": null,
"type": "Draw"
},
"validation": {
"doesForceResponse": false
}
},
"QID17": {
"choices": {
"1": {
"analyze": true,
"choiceText": "First Click",
"description": "First Click",
"imageDescription": null,
"recode": "1",
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Last Click",
"description": "Last Click",
"imageDescription": null,
"recode": "2",
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Page Submit",
"description": "Page Submit",
"imageDescription": null,
"recode": "3",
"variableName": null
},
"4": {
"analyze": true,
"choiceText": "Click Count",
"description": "Click Count",
"imageDescription": null,
"recode": "4",
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q17",
"questionText": "Timing",
"questionType": {
"selector": "PageTimer",
"subSelector": null,
"type": "Timing"
},
"validation": {
"doesForceResponse": false
}
},
"QID18": {
"choices": {
"1": {
"analyze": true,
"choiceText": "Browser",
"description": "Browser",
"imageDescription": null,
"variableName": null
},
"2": {
"analyze": true,
"choiceText": "Version",
"description": "Version",
"imageDescription": null,
"variableName": null
},
"3": {
"analyze": true,
"choiceText": "Operating System",
"description": "Operating System",
"imageDescription": null,
"variableName": null
},
"4": {
"analyze": true,
"choiceText": "Screen Resolution",
"description": "Screen Resolution",
"imageDescription": null,
"variableName": null
},
"5": {
"analyze": true,
"choiceText": "Flash Version",
"description": "Flash Version",
"imageDescription": null,
"variableName": null
},
"6": {
"analyze": true,
"choiceText": "Java Support",
"description": "Java Support",
"imageDescription": null,
"variableName": null
},
"7": {
"analyze": true,
"choiceText": "User Agent",
"description": "User Agent",
"imageDescription": null,
"variableName": null
}
},
"questionLabel": null,
"questionName": "Q18",
"questionText": "Browser Meta Info",
"questionType": {
"selector": "Browser",
"subSelector": null,
"type": "Meta"
},
"validation": {
"doesForceResponse": false
}
},
"QID19": {
"questionLabel": null,
"questionName": "Q19",
"questionText": "Captcha",
"questionType": {
"selector": "V2",
"subSelector": null,
"type": "Captcha"
},
"validation": {
"doesForceResponse": false
}
},
For more information on these question types, see the following pages:
List Surveys
The List Surveys API returns a JSON object that describes all of the surveys that are owned by you and those that are collaborated on with you.
Survey Details Limited to Individual Collaborations
The List Surveys API details surveys you own and are working on with other individual users. It does not include information about surveys collaborated on with groups. This distinction ensures the API returns precise details about individual collaborations without statistical noise from group data.
The List Surveys API requires two pieces of information:
- Your API token (needed for all API calls), item 1 in the sample below
- Your data center ID (needed for all API calls), item 2 in the sample below
To find these IDs, see Finding Qualtrics IDs.
# List Surveys API
import os
import requests
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys".format(dataCenter)
headers = {
"x-api-token": apiToken,
}
response = requests.get(baseUrl, headers=headers)
print(response.text)
The JSON object returned contains a result member which contains an elements array containing objects describing your surveys. For example, the following sample shows the elements array of objects for a user who has two surveys.
"result": {
"elements": [
{
"id": "SV_1234567890",
"isActive": true,
"lastModified": "2017-05-23T15:01:02Z",
"name": "Spring Survey",
"ownerId": "UR_abcdefghij"
},
{
"id": "SV_2345678901",
"isActive": false,
"lastModified": "2017-05-18T19:49:31Z",
"name": "Summer Survey",
"ownerId": "UR_bcdefghijklmno"
}
],
"nextPage": null
}
The objects in the elements array have members that are described in the following table:
| Member | Type | Description |
|---|---|---|
| id | String | The survey ID of the survey. |
| isActive | Boolean | Whether the survey is currently active. Active surveys are surveys that haven't expired or aren't paused. Users can take active surveys. |
| lastModified | String | The data and time anyone made changes to the survey. See Dates and Times for more information on the date and time format. |
| name | String | The name of the survey. In the survey user interface it is also referred to as the project name. |
| ownerId | String | The ID of the survey's owner. |
The nextPage member contains the URL of the next page of survey results. For more information about pagination of results from the API, see "Pagination" in Quick Start.
Update Survey
The Update Survey API allows you to update the following information about a survey:
- The survey's name
- Whether the survey is active
- When the survey expires
To use this API, you need the following information:
- Your API token (needed for all API calls), item 1 in the sample below
- Your data center ID (needed for all API calls), item 2 in the sample below
- A Survey ID, item 3 in the sample below
To find these IDs, see Finding Qualtrics IDs.
# Update Survey
import os
import requests
import json
#Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
surveyId = "YOUR SURVEY ID" # 3
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}".format(dataCenter, surveyId)
headers = {
"content-type": "application/json",
"x-api-token": apiToken,
}
data = {
"name": "Newer Name",
"isActive": True,
"expiration": {
"startDate": "2017-05-22T00:00:00Z",
"endDate": "2017-05-24T00:00:00Z"
}
}
response = requests.put(baseUrl, json=data, headers=headers)
print(response.text)
This example changes the name of the survey to "Newer Name," sets it to active, and changes the survey's active date and time range from May 22, 2017 at 0:00 UTC to May 24, 2017 at 0:00 UTC.
Each item in data is optional. For instance, if you just want to change the name of the survey, you don't need to include isActive or expiration. The lastModified date and time of the survey is updated after using this API.
Import Survey
The Import Survey API allows you to import a survey's definition from a file. The possible file types include qsf ("Qualtrics Survey Format"), txt, and doc files.
For a discussion of these file types, see Import and Export Surveys.
For a detailed discussion of the Qualtrics .txt file format, see Preparing a Simple Format TXT File and Preparing an Advanced Format TXT File.
Get Survey Format
Note that the Import Survey API does not accept the same survey format that is returned by the Get Survey API.
The following example imports the survey "Simple.qsf" that was exported from the survey user interface (see Import and Export Surveys). The example imports a survey with a mime type of "application/vnd.qualtrics.survey.qsf". Available import formats are listed at Import Survey.
# Import Survey
import os
import requests
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys".format(dataCenter)
headers = {
"x-api-token": apiToken,
}
files = {
'file': ('Simple.qsf', open('Simple.qsf', 'rb'), 'application/vnd.qualtrics.survey.qsf')
}
data = { "name": "Test" }
response = requests.post(baseUrl, files=files, data=data, headers=headers)
print(response.text)
The API does not return the survey ID of the newly created survey. You'll need to call the List Surveys API or use the user interface to find it.
Delay
There is sometimes a delay before the newly created survey appears in the survey dashboard.
Import Survey from URL
You can import a survey that is located on a website. The file needs to be accessible to the Qualtrics servers, so it should be publicly accessible. Possible servers include Amazon's S3, Dropbox shared files, or public Google Drive files.
The example below shows how to import a .qsf file (with a mime type of "application/vnd.qualtrics.survey.qsf"). Available import formats are listed at Import Survey.
To import, you'll need
- Your API token (needed for all API calls), item 1 in the sample below
- Your data center ID (needed for all API calls), item 2 in the sample below
- A survey name, item 3 in the sample below
- The location of the import file (URL), item 4 in the sample below
To find these IDs, see Finding Qualtrics IDs.
Library Required
This first sample uses the requests_toolbelt library to create the multipart form data required by this API. Use pip to install it.
# Import Survey from URL
import os
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
surveyName = "NAME TO GIVE YOUR NEW SURVEY" # 3
fileUrl = "URL TO SURVEY" # 4
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys".format(dataCenter)
multipartData = MultipartEncoder(
fields = {
"name": surveyName,
"contentType": "application/vnd.qualtrics.survey.qsf",
"fileUrl": fileUrl
}
)
headers = {
"x-api-token": apiToken,
"Content-Type": multipartData.content_type
}
response = requests.post(baseUrl, data=multipartData, headers=headers)
print(response.text)
# Import Survey from URL
import os
import requests
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
surveyName = "Test Survey" # 3
fileUrl = "https://s3-us-west-2.amazonaws.com/S3bucketname/Test.qsf" # 4
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys".format(dataCenter)
files = {
"name": (None, surveyName),
"contentType": (None, "application/vnd.qualtrics.survey.qsf"),
"fileUrl": (None, fileUrl),
}
headers = {
"x-api-token": apiToken,
}
response = requests.post(baseUrl, files=files, headers=headers)
print(response.text)
Delay
There is sometimes a delay of several minutes before surveys imported with this API appear in the survey dashboard.
Delete Survey
The Delete Survey API deletes the survey that has the given survey ID.
The following example demonstrates how to delete a survey. You'll need the following information to delete a survey:
- Your API token (needed for all API calls), item 1 in the sample below
- Your data center ID (needed for all API calls), item 2 in the sample below
- A survey ID, item 3 in the sample below
To find these IDs, see Finding Qualtrics IDs.
Permissions required
- User needs to have
deleteSurveysprivilege
AND
- User is the survey owner OR
- User is Brand Admin and the survey is in this brand. OR
- User is Server Admin or MBA. OR
- User is the Division Admin and the survey is in this brand. OR
- User is the EX Admin, and the survey is an EX survey which is in this brand.
# Delete Survey
import os
import requests
# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"] # 1
dataCenter = os.environ["Q_DATA_CENTER"] # 2
surveyId = "YOUR Survey ID" # 3
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}".format(dataCenter, surveyId)
headers = {
"x-api-token": apiToken,
}
response = requests.delete(baseUrl, headers=headers)
print(response.text)
Upon successful deletion, the API returns a 200 response:
{
"meta": {
"httpStatus": "200 - OK",
"requestId": "bb120589-c361-4a3b-bf69-fa3aa46ca400"
}
}