Integrating Web Service Data Into Qualtrics Survey Loop and Merge

Qualtrics survey designers can use REST data service endpoints to populate data for use in survey questions. 

Before You Start 

You will need the following before you can complete this task: 

  1. Qualtrics account
  2. Target data service URL endpoint (ex. https://mydataservice.com/userinfo)
  3. Working knowledge of Qualtrics basics
  4. *API key where applicable*

Setting up the Survey

We will use a new survey and an example service endpoint:

  1. Create a blank survey.

    Qualtrics survey create project element with Project Name text area. Content is

  2. Create three blocks:
    1. Consent block with a descriptive text question
    2. LM Block with a descriptive text question and a matrix table question
    3. Closing block with a descriptive text question

      Qualtrics Survey editor showing 3 blocks named Consent, LM Block, and Close.
  3. Open the survey flow editor.

    Qualtrics survey editor 'Survey Flow' nav bar item highlighted.

 Web Request Data

  1. In the survey flow editor click Add Below on the first block element.

    Qualtrics Block element 'Add Below' link highlighted.

  2. Select Web Service.

    Qualtrics Add Element form with 'Web Service' button focused.

  3. Enter the service URL in the URL field. Here we are using: https://jsonplaceholder.typicode.com/posts.

    Qualtrics Web Service element form with URL text area highlighted. Content is https://jsonplaceholder.typicode.com/posts
  4. Click Test to send a request to the URL, and receive data back.
    • If you receive an error, you may view the unformatted response by clicking View Raw Data. This may help you determine the problem.

      'Select fields to include as embedded data' window with 'View Raw Data' button highlighted.
  5. Select the fields you want to reference from embedded fields later. Here we click All.

    'Select fields to include as embedded data' window with results displayed, and checkboxes for each data piece.
  6. Click Add Embedded Data.

    'Add Embedded Data' button highlighted.
  7. You will see a large array of data fields have been populated from the web request.
  8. We will not be doing this in the example, but the left hand side is the resulting embedded variable. You may change them by clicking on the name. Example: LetterText becomes ${e://Field/LetterText}.

    Set embedded data area of result with Left Hand Side variable focused and renamed LetterText.

Create a Loop and Merge Data Field Sheet

This step is only needed if you intend to use Loop and Merge to reference the data. We will create it in this example, and you will see it used in the next section. Download the example file here to follow along, or to use as a basis for your custom file: loop_and_merge_starter_fields.xlsx.

  1. Open Excel or LibreOffice and create a new worksheet.
  2. In the first column enter the function `=ROW()-1`.
  3. In the second column enter the function `=CONCATENATE("${e://Field/",A1,".userId}")`.
  4. Add any additional columns for fields you may need.

    Shows excel spreadsheet with four columns B-E created with the formula. userId, id, title, and body.

  5. Copy the first row and paste through the number you need. Row 100 for this example.

    Highlighted excel columns B1 through E100.

  6. Feel free to download the example file and modify to your needs.

Enable Loop and Merge

We are going to turn on the Loop and Merge feature for our question block and then use the data to display text to participants.

  1. Please go back to the Qualtrics survey.
  2. In our LM Block under Block Options select Loop & Merge.

    Expanded block options with Loop and Merge option focused.
  3. Click Turn on Loop & Merge.

    Loop and Merge window showing 'Turn on Loop & Merge' button.
  4. Paste the fields from B1:E100 into Loop & Merge.

    Loop and Merge window with fields from excel pasted in.
  5. Click Save.
  6. Click into the LM Block first question text.

    Left: Qualtrics question text. Right: Focused converts to edit mode.
  7. Click HTML View.
  8. Enter the following HTML segment.
  9. <h3>Title: ${lm://Field/3}</h3>
    <h5>User: ${lm://Field/1}</h5>
    <h5>Post Id: ${lm://Field/2}</h5>
    <p>Body: ${lm://Field/4}</p>

  10. Click out of the editor and Preview the survey. Don't preview just the block. After the consent page you should see something like this.

    Qualtrics survey question with User = 1, Post Id = 1, Title and Body filled Lorem Ipsum example text.
  11. Success!

Adding API Key

If the web service you are utilizing requires an API key to access it, you can add this in the survey flow.

  1. In Survey Flow go to the Web Service item.
  2. Click Add a custom header to send to web service...
  3. Enter "x-api-key" and click Set a Value Now.
    • Check with the API provider for details
  4. Enter the API key.
  5. Click Test to verify.

Questions?

Email: research-programming@wharton.upenn.edu