Insight Platform - API Common Uses | Qualtrics

Common API Use Cases

Introduction

This support page highlights the ways other Qualtrics clients are leveraging the Qualtrics API. Below you’ll find a list of common API requests that our clients are using and the use cases associated with each request.

Attention: API integrations may require programming knowledge to implement. Our support team does not offer assistance or consultation on custom coding. If you’d like to know more about our custom coding services, please contact your Qualtrics Account Executive.

Common Methods

Query String

You can pass your API request parameters through standard query string syntax. You start with the root URL and append each of your required parameters to the end.

Root URL:

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php

For the first parameter that is added to the root URL, include a “?” followed by the name of the parameter, an equal sign, and the parameter’s value (e.g., ?Version=2.4). Add all subsequent parameters with a leading ampersand “&” (e.g., &Request=importPanel).

Root URL + Required Parameters:

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?Version=2.4&Request=importPanel&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML

Continue adding or appending any other additional parameters to your URL by following the same process described above. Once you’ve include all your desired parameters, you’ll have a completed request.

Root URL + Required Parameters + Additional Parameters:

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?Version=2.4&Request=importPanel&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML&LibraryID=UR_6FmmzmE470uARsV&ColumnHeaders=1&Email=3&URL=https%3A%2F%2Fco1.qualtrics.com%2FWRQualtricsControlPanel%2FFile.php%3FF%3DF_3IeSPPh9HjXwaj3%26download%3D1&Name=Test&FirstName=1&LastName=2&AllED=1

Web Service

Automating API request construction is commonly done by an IT specialist at your organization, as this process requires the implementation of custom code. However, an organization may not always have the resources to allocate to this automation process. In some cases though, you can use a Qualtrics survey to automate instead of custom code. The steps below demonstrate how to accomplish this process.

Qtip: To automate API request construction from within Qualtrics, you’ll need to be familiar with constructing an API request and with Web Services. In addition, you’ll need to include a survey question that collects a participant’s necessary personal information (e.g., Text Entry – Form question).

Once your survey has been constructed,

  1. Navigate to the Survey module and open your Survey Flow.
    image02
  2. Beneath your block of questions, select Add Below.
    image03
  3. Select the element Web Service.
    image06
  4. Inset the root URL into the URL box:
    https://survey.qualtrics.com/WRAPI/ControlPanel/api.php

    image02

    Qtip: You can also leave off the “api.php” and include that piece as the URL parameter, as seen in steps 6–7.
  5. Click Add a parameter to send to web service.
    image09
  6. Add all required parameters for your API request by clicking the plus sign.
    image01
  7. Set the value for each parameter to the right.
    image07
  8. Add all additional parameters for your API request by clicking the plus sign.
    image00
  9. Set the value for each parameter to the right (you’ll want to use Piped Text for values with dynamic data, like FirstName, LastName, and Email).
    image08

JSON

You can pass your parameters as JSON through the body of the request. Note that when using this method, you must specify a Content-Type (i.e., application/json or text/json). This method is commonly done by an IT specialist at your organization, as this process requires the implementation of custom code.

Survey Platform

Automating importing a contact list

You can use the importPanel request to import batches of contacts into your Qualtrics account. Through this request, you can import CSV lists of individuals from your CRM into Qualtrics. There are two main parameters of interest for this request:

  • URL: If present, the Qualtrics API will attempt to load the CSV file from the URL specified; otherwise, it simply looks at the POST for the data.
  • AllED: When enabled (done by setting the value to 1), any columns unaccounted for in your file will be saved as Embedded Data fields. Your file must include column headers for this parameter to function.

Example: In the following URL, the importPanel request parameters are being passed through a query string.

https://survey.qualtrics.com//WRAPI/ControlPanel/api.php?API_SELECT=ControlPanel&Version=2.5&Request=importPanel&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML&LibraryID=UR_6FmmzmE470uARsV&ColumnHeaders=1&Email=3&URL=https%3A%2F%2Fco1.qualtrics.com%2FWRQualtricsControlPanel%2FFile.php%3FF%3DF_3IeSPPh9HjXwaj3%26download%3D1&Name=TEST_API_PAGES2&FirstName=1&LastName=2&AllED=1

Automating creating a contact

Rather than individually update contact lists with new contact members, you can automate the process by using the addRecipient request. This request adds a new contact to an existing contact list. There are two main parameters of interest for this request:

  • LibraryID: The library in your Qualtrics accounts that contains your desired contact list.
  • PanelID: The ID of the contact list you want to add your contact to (because the contact needs to be added an existing contact list).

Example: In the following URL, the addRecipient request parameters are being passed through a query string.

https://survey.qualtrics.com/WRAPI/ControlPanel/api.php?API_SELECT=ControlPanel&Version=2.5&Request=addRecipient&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML&LibraryID=UR_6FmmzmE470uARsV&PanelID=ML_3UbcI5y0zea4oa9&FirstName=Demo&LastName=User&Email=demou%40qualtrics.com

Generating your own Individual Links (createDistribution and getPanel)

You might need to distribute your survey through an internal mailer rather than the Qualtrics mailer. With the Qualtrics API, you can construct Individual Links that track a respondent’s personal information without having to use the Qualtrics mailer.

To accomplish this task, you’ll need to use two API requests: createDistribution and getPanel. These API requests will return the Distribution ID and the Recipient ID, which you will use to construct the Individual Links. Before you begin, you’ll need to import a contact list to Qualtrics either manually or by using the API request importPanel.

There are two main parameters of interest for the createDistribution request:

  • LibraryID: The library in your Qualtrics accounts that contains your desired contact list.
  • PanelID: The contact list that will be used to create your new distribution (all distributions are associated with a contact list).

Example: In the following URL, the createDistribution request parameters are being passed through a query string.

https://survey.qualtrics.com//WRAPI/ControlPanel/api.php?API_SELECT=ControlPanel&Version=2.5&Request=createDistribution&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML&SurveyID=SV_bHDRTwFIL4pFpGZ&PanelID=ML_3UbcI5y0zea4oa9&Description=API_SUPPORT_DIST&PanelLibraryID=UR_6FmmzmE470uARsV

Once successfully constructed, the createDistribution API request will return the Distribution ID (e.g., EMD_6ik2HNNuT3qorI1).

There are two main parameters of interest for the getPanel request:

  • LibraryID: The library in your Qualtrics account that contains your desired contact list.
  • PanelID: The same Panel ID that was used in the createDistribution request.

Example: In the following URL, the getPanel request parameters are being passed through a query string.

https://survey.qualtrics.com//WRAPI/ControlPanel/api.php?API_SELECT=ControlPanel&Version=2.5&Request=getPanel&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=CSV&LibraryID=UR_6FmmzmE470uARsV&PanelID=ML_3UbcI5y0zea4oa9

Once successfully constructed, the getPanel API request will return all contacts in your contact list and their Recipient IDs (e.g., MLRP_0v7VXagWC5aiF37).

Once you have these IDs, you’ll need your organization’s branded URL, your survey’s base link, and your survey’s ID. To locate this information, navigate to your My Projects page. Select your survey and navigate to your Distributions module. Select the distribution method Anonymous Link.

image05

Copy the beginning of the Anonymous Link up until the question mark.

  • Anonymous Link: https://qunigenesis.qualtrics.com/SE/?SID=SV_bHDRTwFIL4pFpGZ
  • Base Link: https://qunigenesis.qualtrics.com/SE/?

From the Anonymous Link, you’ll also find the Survey ID (e.g., SV_bHDRTwFIL4pFpGZ). Now you’ll have the following:

  • Distribution ID: EMD_6ik2HNNuT3qorI1
  • Recipient ID: MLRP_0v7VXagWC5aiF37
  • Survey ID: SV_bHDRTwFIL4pFpGZ
  • Base Link: https://qunigenesis.qualtrics.com/SE/?

Now we can construct the Individual Links. Append Q_DL= to the end of your base  link and then add the Distribution, Survey, and Recipient IDs, all separated by underscores. Note that for the Distribution and Survey IDs, you remove the EMD_ and SV_.

Individual Link:

https://qunigenesis.qualtrics.com/SE/?Q_DL=6ik2HNNuT3qorI1_bHDRTwFIL4pFpGZ_MLRP_0v7VXagWC5aiF37

Automating your data download in preparation to import into your CRM

If you find yourself needing data from many surveys on a daily basis, you can use the getLegacyResponseData API request. This request downloads your raw data, making it easier for you to obtain your data and then import those responses to your CRM, data warehouse, etc. There are two main parameters of interest for this request:

  • LastResponseID: Download any new responses collected after the specified Response ID (e.g., after each download, you could have your system save the last Response ID and use it in the next getLegacyResponseData request).
  • ResponseID: Downloaded only one individual’s response from the raw data.

Example: In the following URL, the getLegacyResponseData request parameters are being passed through a query string.

https://survey.qualtrics.com//WRAPI/ControlPanel/api.php?API_SELECT=ControlPanel&Version=2.5&Request=getLegacyResponseData&User=kathleenb_gen&Token=11lyq2mnuBbpKD5gfxTbqF2Sm2BTHplJreCvCuzQ&Format=XML&SurveyID=SV_1O1Gm3Ggunb0Hqd&LastResponseID=R_3sBthYFmgKGzMu3

Target Audience

Removing bounced emails from your directory

From the time to time, it’s helpful to update and tidy your directory by making sure that your contacts have correct email addresses. When looking at the Mailing History for a specific distribution, you can see if any emails bounced for that specific distribution. With the getBouncedContacts API request, you can get a list of every contact in your directory that has ever had an email bounce in any distribution. You can then either update these contacts or remove them from your directory.

There are three main parameters of interest for this request:

  • Days: The number of days to scan for, from today backward. If left empty, searches all time.
  • ListId: The list to get bounced contacts from. If left blank, searches entire directory.
  • LibraryID: The library ID (usually user ID) that the list is in (only required if passing in List Id).

Example: In the following URL, the getBouncedContacts request parameters are being passed through a query string.

https://survey.qualtrics.com/WRAPI/Contacts/api.php?Request=getBouncedContacts&User=api_user&Token=S0plqwI1MYxilMkEofkl7J1pyK61HFB86aKX3aAF&Format=XML&Version=2.3&Days=100&LibraryID=UR_6X2HgGh8rfLNtHf&ListId=CG_8vS9A0clZqlhjjn

Once the API request has been successfully constructed, you will receive a list of all your contacts who have had an email bounce that meet the criteria you specified in the optional parameters of the request.

Updating a contact (updateContact and getContactByInfoFields)

Sometimes you may want to update a contact through the API. In order to do so, you’ll need the contact’s Contact ID. Oftentimes you will have a name or email address for a contact readily available, but you won’t know their Contact ID. The getContactByInfoFields API request allows you to look up a contact’s Contact ID which you can then use for later API requests. We’ll first explain the API request getContactByInfoFields and then updateContact.

There are two main parameters of interest for the getContactByInfoFields request:

  • Email: The email of the contact who is to be retrieved.
  • ExternalDataRef: The external data reference of the contact who is to be retrieved.

Depending on how you are deduplicating your contacts, either the email or the external data reference will be a unique identifier. Use whichever one best fits your deduplication model.

Example: In the following URL, the getContactByInfoFields request parameters are being passed through a query string.

https://survey.qualtrics.com/WRAPI/Contacts/api.php?Request=getContactByInfoFields&User=api_user&Token=S0plqwI1MYxilMkEofkl7J1pyK61HFB86aKX3aAF&Format=XML&Version=2.3&Email=support@qualtrics.com

The result for the getContactByInfoFields request will be to receive the contact’s Contact ID, so you can now use it for requests like updateContact.

There is one main parameter of interest for the updateContact request: ContactID. The parameter is the ID of the contact who is retrieved in the getContactByInfoFields request.

Example: In the following URL, the updateContact request parameters are being passed through a query string.

https://survey.qualtrics.com/WRAPI/Contacts/api.php?Request=updateContact&User=api_user&Token=S0plqwI1MYxilMkEofkl7J1pyK61HFB86aKX3aAF&Format=XML&Version=2.3&ContactID=CID_1SQ74MTVlT3PDlj&FirstName=Qualtrics&LastName=Support

As a result of the updateContact request, the specified contact will be updated with whatever information you’ve changed based on the parameters of your request.