Qualtrics

Migration Guide V2 to V3

Overview

V2 APIs turned off has been moved back from Nov 15th, 2019, to March 31st, 2020. After March 31st, V2 API calls will no longer exist and calls to them will fail with HTTP 404 response code.

Here we explain for Qualtrics V2 API programmers some of the items and considerations they need to migrate to V3. We also provide some code examples.

Improvements for the programmer

item
description

No More PHP

V3 uses industry started REST, so you post to REST endpoints. There is no more posting to the php URL: https:\survey.qualtrics.com/WRAPI/ControlPanel/api.php with commands passed and parameters in the URI.

oAuth support

This is how Facebook and Google login works along with some of your corporate apps. It is an industry standard. In terms of a browser, this means you can login one time for different web sites across and outside of your organization.

Read about Qualtrics support for OAuth here.

Adopts industry standard JSON format

JSON is returned as a JSON array instead of one large JSON string. So, in terms of JavaScript, you do not have to use Object.entries or Object.keys to get individual records. The V2 design is not really correct and requires extra code to work with that. So V3 corrects that.

There are some new concepts:

Glossary

item
description

panel

A collection of contacts.

XM Directory

Is an upgraded version of the contact management/distribution platform. It is now called XM Directory.

data center

This is the data center assigned to your account and where you should send REST requests. Login to qualtrics.com and read it from the URL, i.e., https://**(brand)**.**(data center**).qualtrics.com/. The idea is to reduce latency by sending requests to the data center closest to you.

pool ID

Think of this as the directory assigned to your brand.

See the graphic below.

API key

aka Token. Qualtrics supports API Key and Oauth authentication. In V3, the API Key replaces the combination of API Key and Qualtrics userid (i.e. the ID you use to login to qualtrics.com).

See the graphic below.

organization iD

This is also know as brand.

See the graphic below.

user ID

Note that in V2 the user ID is the ID you use to login to qualtrics.com. In V3 it is just a code. You generally do not need that unless you want to look up information about a particular user.

To find the organization id (brand), pool ID, and token (API Key), look under Account Setting>Qualtrics IDs

Then read the values from here:

Qualtrics IDs

V2 to V3 API Map

There is an equivalent V3 API for each V2, with some exceptions. For example, below we list those that have been obsoleted. The main reason for this is users were not using them. And now some single APIs do the work or several API calls, such as retrieving survey results.

A list of which V3 API corresponds to which V2 API is listed here.

Note that support for JSONP is dropped as well.

Obsoleted V2 APIS

activateBrand
deactivateBrand
getResponseCountsBySurveyOwner
getQualtricsIdsForLibrary
getPanelMemberCount
updatePredefinedDataSource
getIncentiveRecipients
userPermissionType

Further Info

See V2 to V3 migration guide below as well.

V3 Samples

Here we explain some of the V3 APIs and how to use those in place of the V2 ones. We give Node.js, JavaScript, and curl examples.

V2 API
V3 API

getPasswordExpirationDates

You do this in two steps: list users and get user.

First, here is how this is done in V2:

curl 'https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?Request=getPasswordExpirationDates&User=(Qualrics User ID)&(Token=XXXXXX)&Format=JSON&Version=2.5&Organization=(brand)'

Or using JavaScript, as shown below.


const request = require('request-promise')

var user = encodeURI('(qualtrics User ID)');

const options = {
  method: 'GET',
  uri: 'https://survey.qualtrics.com/WRAPI/ControlPanel/api.php',
  qs: {
    Request: 'getPasswordExpirationDates',
    User: user,    
    Token: '(API token),
    Format: 'JSON', 
    Version: '2.5',
    Organization: '(brand)'
  }
}

request(options)
  .then(function (response) {
    users = Object.entries(JSON.parse(response))
    users.forEach(function(user) {
      e = Object.entries(user)
      e.forEach(function(ef) {
       for (i in ef) {
       var users = ef[i].UserData
       if (users !== undefined) {
             keys = Object.keys(users) 
             keys.forEach(function(user) {
               var u = users[user]
                console.log("UserID=", u.UserID, " PasswordExpirationDate=", u.PasswordExpirationDate)
                })
             }
          }
       })
       })
    })
  .catch(function (err) {
    console.log (err) 
  })

As you can see above, the V2 JSON format is difficult to work with as the response is not a an array. Instead they are all in one big JSON object. That's not proper JSON design. It has been corrected in V3.

The code above results in:

UserID= UR_6VWbL6blrg56JQ9  PasswordExpirationDate= 2018-08-13 10:40:15
UserID= UR_cM8EBX1iFVG9gB7  PasswordExpirationDate= 2018-06-26 13:41:57
UserID= UR_8cckjr0DrgLJOSh  PasswordExpirationDate= Never
UserID= UR_dnzekZ5RS3JzFe5  PasswordExpirationDate= Never
UserID= UR_5cDOLfs9wUvghtH  PasswordExpirationDate= 2015-12-04 18:22:18
UserID= UR_3OxyToZvPYvfPdX  PasswordExpirationDate= 2015-12-04 18:23:09

Here is the V3 approach:


curl -i -H 'X-API-TOKEN:(API Key)' -H 'Content-Type: application/json' https://co1.qualtrics.com/API/v3/users

Results in:

{
	"id": "**UR_cNE7W3FX4TPThGJ**",
	"divisionId": null,
	"username": "xxx@xxx.com",
	"firstName": "Sam",
	"lastName": "Jones",
	"userType": "UT_PARTICIPANT",
	"email": "xxx@xxx.com",
	"accountStatus": "active"
}

Then take that user ID UR_cNE7W3FX4TPThGJ and pass it to the next curl:


curl -H 'X-API-TOKEN: (API token)' 'https://co1.qualtrics.com/API/v3/users/UR_cNE7W3FX4TPThGJ'

Results in a properly constructed JSON array:

[
  {
UR_cNE7W3FX4TPThGJ ' {
	"result": {
		"id": "UR_cNE7W3FX4TPThGJ",
		"username": "xxxxx@xxx.co",
		"email": "xxx@xxx.co",
		"firstName": "xxx",
		"lastName": "xxx",
		"userType": "UT_PARTICIPANT",
		"organizationId": "xxx",
		"divisionId": null,
		"language": "en",
		"accountStatus": "active",
		"unsubscribed": false,
		"accountCreationDate": "2018-06-27T01:41:57Z",
		"accountExpirationDate": null,
		"passwordLastChangedDate": null,
		"passwordExpirationDate": null,
		"lastLoginDate": null,
		"responseCounts": {
			"auditable": 0,
			"generated": 0,
			"deleted": 0
		},
		"permissions": {
			"siteIntercept": {
				"accountPermissions": {
					"administerSiteIntercept": {
						"calculatedState": "off",
						"state": "userType"
					},
...
					
}
]

getLegacyResponseData

The V3 API creates a .zip file of responses in csv, csv2013, xml, json, or spss formats. It is a batch process, so you call the program in three steps, in the order shown below. You have to waiting for step 2 to complete before moving to step 3.

Create Response Export
GetResponseExportProgress
GetResponseExportFile

A complete example is here.

You need to know the surveyID. You can either use curl to obtain a list or look it up in qualtrics.com: account settings>Qualtrics IDs.

getResponseCountsBySurvey

Use Get Survey. This returns the survey structure, which can be quite lengthy. But at the bottom it gives the counts:

"responseCounts": {
      "auditable": 0,
      "generated": 0,
      "deleted": 0
    }

Table of Equivalent V2 to V3 APIs

To help make the process of upgrading from version 2.x easier, here is a table to help you find the equivalent call.

Category
V2 API Call
V3 API Call

Contacts

checkImportContactsStatus

Transaction Contacts Import Status

Use Import Contacts into Mailing List with Transactions but leave off transactions if you only want to important contacts.

Contacts

createContact

Contacts

deleteContact

Contacts

getContact

Contacts

importContacts

You can create a contact in a directory one at a time. But you can only import a batch of them into a mailing list. Use Import Contacts into Mailing List with Transactions. If you only want contacts and transactions then leave off any transactions.

Contacts

updateContact

organizations

getOrgActivity

organizations

getResponseCountsByOrganization

organizations

getPasswordExpirationDates

users

deleteUser

users

getUserIds

users

getResponseCountsBySurveyOwner

users

getUserInfo

users

createUser

users

changeUserName

users

updateUser

divisions

getResponseCountsByDivision

divisions

createDivision

groups

deleteGroup

groups

removeUserFromGroup

groups

getGroupIds

groups

addGroup

groups

addUserToGroup

surveys

deleteSurvey

surveys

getSurveys

surveys

getResponseCountsBySurvey

surveys

getSurvey

surveys

getSurveyName

surveys

getQuotasForSurvey

surveys

importSurvey

surveys

activateSurvey

surveys

deactivateSurvey

surveys

setSurveyOptions

surveys

setSurveyOwner

responses

updateResponseEmbeddedData

responses

getLegacyResponseData

Use all of:

responses

importResponses

responses

deleteResponse

distributions

getDistributions

distributions

createDistribution

distributions

sendEmailToPanel

distributions

sendReminder

distributions

sendSurveyToIndividual

distributions

sendSurveyToPanel

distributions

sendThankYou

mailinglists

deletePanel

mailinglists

removeRecipient

mailinglists

getPanels

mailinglists

getPanel

mailinglists

getRecipient

mailinglists

getSamples

mailinglists

getSample

mailinglists

createPanel

mailinglists

importPanel

mailinglists

addRecipient

mailinglists

updateRecipient

mailinglists

getListContacts

messages

deleteLibraryMessage

messages

getLibraryMessages

messages

getLibraryMessage

messages

createLibraryMessage

messages

setLibraryMessage

graphics

uploadGraphic

graphics

deleteGraphic

eventsubscriptions

unsubscribeFromAll

DELETE /v3/eventsubscriptions

eventsubscriptions

unsubscribe

DELETE /v3/eventsubscriptions/:eventSubscriptionId

eventsubscriptions

getAllSubscriptions

eventsubscriptions

getSubscriptionStatus

eventsubscriptions

subscribe

POST /v3/eventsubscriptions

getPanelMemberCount

(Not Implemented)

getQualtricsIdsForLibrary

(Not Implemented)

surveys

importSurveyTranslations

updatePredefinedDataSource

(Not Implemented)

mailinglists

getPanelOptouts

GET v3/directories/:directoryId/mailinglists/:mailingListId/optedOutContacts

mailinglists

getBouncedContacts

GET v3/directories/:directoryId/mailinglists/:mailingListId/bouncedContacts

directories

getContactByInfoFields

POST v3/directories/:directoryId/contacts/search

directories

getDirectoryContacts

responses

getSingleResponseHTML

GET API/v3/surveys/:surveyId/responses/:responseId

graphics

deleteGraphic

DELETE /v3/graphics/:graphicId

incentive

getIncentiveRecipients

(Not Implemented)

lists

createList

lists

getList

lists

getListContact

lists

getListContactCount

lists

getListContacts

lists

getListOptouts

List Contacts In Mailing Listand query field unsubscribed

lists

getLists

lists

getSampleContacts

lists

getSamples

lists

removeContact

lists

userPermissionType

Migration Guide V2 to V3


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.