Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Version License Python


Unofficial python API for Qualtrics.

This library is intended to simplify integration of Qualtrics system with your python application, while preserving semantics of API when possible. You can automate survey or panel creation, automatically load survey responses to your system, use this library in your scripts and so on.

My ultimate goal is cover all API calls. Some of them (subscribe, createUser etc) require admin access, and I don't have it currently, so adding support for them may take a while. I do welcome pull requests if you'd like to contribute.

System requirements

Python 2.7 or Python 3.5

Requires setuptools. It might be already installed on your system, but if not you can use script to install setuptools.


Install the latest release using pip:

pip install pyqualtrics

Development version can installed using pip install git+

Alternatively, you can download or clone this repo and run pip install -e ..


This library requires account with Qualtrics API enabled. Check with your Qualtrics representative to see if API Access is available for your account.

Please refer to for information on how to get your API Token and other Qualtrics IDs (in your Account Settings, click "Qualtrics Ids").

Usage example

This is how you can get list of all responses to a survey (using API v2).

from pyqualtrics import Qualtrics

QUALTRICS_TOKEN = "lskdjfla93402930sldfkajlk32l4w3fsddsf"
QUALTRICS_SURVEY_ID = "SV_8pqqcl4sy2316ZF"

responses = qualtrics.getLegacyResponseData(SurveyID=QUALTRICS_SURVEY_ID)
for response_id, response in responses.items():
    print response_id + " : " + response["Finished"]

getLegacyResponseData function returns an OrderedDict of all survey responses.

Bugs and requests

Qualtrics support is awesome, but this is not official Qualtrics SDK and they DO NOT support this piece of software. If you have found a bug or if you have a request for additional functionality, please use the issue tracker on GitHub.

Error handling

If API call was not successful (return None or False), additional information about problem can be found in the following attributes of the Qualtrics object

qualtrics.last_error_message : Human-readable error message (set to None is no error occurs)

qualtrics.response : server response as a text string. Can be useful for debugging if server did not return JSON response for some reason

qualtrics.r : server response as a requests.Response object.

qualtrics.json_response : python dictionary, JSON response returned by the server. Can be None (if response is not a JSON document)

qualtrics.last_url : URL constructed by the library (for both v3 and v2 API calls)

qualtrics.last_data : Body or last POST request (v3 calls only)

from pyqualtrics import Qualtrics

qualtrics = Qualtrics(user="user", token="token")
xml = qualtrics.getSurvey(SurveyID="SV_8pqqcl4sy2316ZF")
if not xml:
   print "Error getting survey: %s" % qualtrics.last_error_message


You can use this under Apache 2.0. See LICENSE.txt file for details. I appreciate if you drop me a line if you find this library useful!


Alex Vyushkov, pyqualtrics[at]

Developer's notes

API Documentation

The Qualtrics REST API allows you to query our system using a simple URL syntax. All requests are simple GET or POST requests that return XML or JSON. Official API documenation is available on

This library uses API v2.5

How to run tests

Tests suite requires access to Qualtrics API. It uses following environment variables

QUALTRICS_USER - Qualtrics User ID

QUALTRICS_TOKEN - Token to access Qualtrics API


Please refer to for additional information on how to get your API Token. Library ID can be found in the 'Qualtrics IDs' section. If one of these variables is not defined, tests won't start at all.

If you want to run full test suite, you may want to create a survey, a message and one response in your Qualtrics account. QUALTRICS_SURVEY_ID, QUALTRICS_RESPONSE_ID and QUALTRICS_MESSAGE_ID variable should be set to activate those tests

You can re-created Qualtrics survey used for testing using files in qualtrics_files_for_tests directory

Notes for test_get_legacy_response_data test

This test requires a partially completed response in "getLegacyData test" survey (SV_8pqqcl4sy2316ZL), and it will closed after 6 month (max timeout allowed by Qualtrics). Thus every 6 month new partially completed response should be created.

Use link and answer "Male". Don't answer the second question