Working with Survey Sessions

This example reads a survey's structure. Then it walks the user through each question, calling updateSession after each question. After the last question the survey is marked as complete.

So this illustrates how you might use the Qualtrics APIs in your own application. This code sample is designed to work specifically for a simple set of multiple choice questions. You would need to extend this code to make it work with certain complex survey question types, like Matrix Tables. This code would still work but the user would not be able to see the complete text of the questions.

Use Survey API to Understand Survey Structure

The best way to define a survey is via your brand administration page. From a defined survey, you can explore the question structure by querying the Survey API. This will help you see how to use more complex questions in your application

To run the below code you need to set APIKEY and DATACENTER in your environment. Then pass the surveyID to the Python program below on the command line, e.g., python updateSurveySession.py SV_9soLp9xtDjAKP53

When the user runs the code it prompts the user as shown below (The Python code is shown below that). After the last question the user is thanked for their answers and the survey is marked done. The screen echos the JSON sent to Qualtrics as it updates each question.

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.

python updateSurveySession.py SV_9soLp9xtDjAKP53
QID1
Would you recommend our product to your friends or family?
Maybe
2
Definitely not
1
Definitely would
3
enter your answer=3
update response= {
  "result": {
    "sessionId": "FS_3CtjKCy3C1DInW9",
    "questions": [
      {
        "questionId": "QID2",
        "type": "mc",
        "display": "What is your favorite color?",
        "options": {
          "multiSelect": false
        },
        "choices": [
          {
            "choiceId": "1",
            "display": "Blue",
            "textual": false
          },
          {
            "choiceId": "2",
            "display": "Red",
            "textual": false
          },
          {
            "choiceId": "3",
            "display": "Green",
            "textual": false
          }
        ]
      }
    ],
    "embeddedData": {},
    "responses": {},
    "done": false
  },
  "meta": {
    "requestId": "389c06cf-cc9e-4823-906e-47bd117b5662",
    "httpStatus": "200 - OK"
  }
}
QID2
What is your favorite color?
Red
2
Blue
1
Green
3
enter your answer=1
update response= {
  "result": {
    "sessionId": "FS_3CtjKCy3C1DInW9",
    "questions": [],
    "embeddedData": {},
    "responses": {},
    "done": "We thank you for your time spent taking this survey. <br /> Your response has been recorded."
  },
  "meta": {
    "requestId": "b127fe1f-01a5-47e5-8bec-3b250482c46f",
    "httpStatus": "200 - OK"
  }
}

import requests
import json
import os
import sys

def updateSession(sessionId, surveyId, payload, apiToken, dataCenter):
    url = "https://" + dataCenter + ".qualtrics.com/API/v3/surveys/" + surveyId + '/sessions/' + sessionId

    headers = {'X-API-TOKEN': apiToken,
          'content-type': 'application/json',
          'Accept': 'text/plain'}


    response = requests.post(url, headers=headers, data=payload)
    print ("update response=", response.text)

def getSession(surveyId, apiToken, dataCenter):

    headers = {'X-API-TOKEN': apiToken}

    url = "https://" + dataCenter + ".qualtrics.com/API/v3/surveys/" + surveyId + '/sessions'

    payload = {'language': 'EN'}

    response = requests.post(url, headers=headers, params=payload)

    d = json.JSONDecoder()
    res = d.decode(response.text)
    sessionId = res['result']['sessionId']
    return sessionId

def main():
    try:
        surveyId = sys.argv[1]
    except IndexError:
        print ("usage: %s -i <surveyID> %s", sys.argv[0])
        sys.exit(2) 

    try:
        apiToken = os.environ['APIKEY']
        dataCenter = os.environ['DATACENTER']
    except KeyError:
        print("set environment variables APIKEY and DATACENTER")
        sys.exit(2) 
    
    sessionId = getSession(surveyId, apiToken, dataCenter)

    headers = {'X-API-TOKEN': apiToken}

    url = "https://" + dataCenter + ".qualtrics.com/API/v3/surveys/" + surveyId

    response = requests.get(url, headers=headers)

    d = json.JSONDecoder()
    res = d.decode(response.text)

    r = res['result']

    questions = r['questions']

    for k, v in questions.items():
        print (k)
        print (v['questionText'])
        c = v['choices']
        for x, y in c.items():
            print (y['choiceText'])
            print (x)
        answer = input("enter your answer=")  
        payload = '{ 
        "advance": true 
        } 
        "responses": { 
        "%s": { 
            "%s": { 
                "selected": true 
                } 
            } 
        }' % (k, answer) 
        updateSession(sessionId, surveyId, payload, apiToken, dataCenter) 

if __name__ == "__main__":
    main()