Using Qualtrics API Documentation

About API Documentation

Our Qualtrics API Documentation page details all of our currently available documentation.

This page walks you through how to navigate our documentation, outlining what each section discusses and what’s available.

OVERVIEW

In the API Overview, you can see information about the Qualtrics API in general, as well as information about Pagination (i.e., if you run a List Contacts request and you have more than 100 contacts, the result will be paginated and a nextPage URL will be provided to get the next 100 – this applies to all collection requests).

BASE URL AND DATACENTER IDS

This sub-section shows you how to find the datacenter ID that you will need to include in the base URL for your API requests.

FINDING YOUR QUALTRICS IDS

This sub-section shows you where you can find the various IDs that you will need when running API requests. For IDs that are not available in this section, please see Locating Qualtrics IDs by Inspecting the Element.

AUTHENTICATION

The Authentication sub-section outlines what information is needed to authenticate your requests, as well as suggestions for protecting your API token. For more information on the authentication process, view Generating an API Token.

PARAMETERS

The Parameters sub-section covers the different methods for passing parameters depending on the HTTP method being used (GET, POST, PUT, or DELETE).

RESPONSES

The Responses sub-section contains examples of the different HTTP response codes that can be returned when you run a request, as well as the possible reasons for each response code. Our API always returns responses in JSON, except in the case of the response export request where the file can be returned in any of our available formats.

USING THE QUALTRICS APIS

This section of the documentation has code snippets in Python and Java to help you in developing workflows for managing surveys and users and for getting survey results.

REFERENCE

The Reference section contains important information on acceptable date and time formats, language codes, requests limits, and details on event subscriptions. Event subscriptions allow you to send notifications to a publication URL once an event occurs (e.g., a response being recorded).

REQUESTS

To help organize the documentation and help users find the API requests they’re looking for, the requests are categorized as follows:

• Organizations
• Divisions
• Groups
• Users
• Surveys
• Exporting Survey Responses
• Responses
• Response Imports
• Message Library
• Graphic Library
• Distributions
• Insights Platform Contacts
• Event Subscriptions
• XM Directory (Target Audience)

Request Parameters and Options

Each API request has a name, a brief description, a table that lists possible parameters, the response, an example request in cURL, and the “Try It Out” wizard. Understanding how to use this information can help streamline your work.

NAME AND DESCRIPTION

The first three things that are listed for any API request is the HTTP verb, the name of the API request, and a brief description of the request.

LIST OF PARAMETERS

For each API request, you’ll see a table listing all possible parameters that can be used (some will be optional, some will be required). This table has the following information:

• Each parameter’s name
• The accepted formats for each parameter
• Whether the parameter is required
• A brief description of the parameter

DEFINITION

The definition refers to the URL used in the request.

Notice the drill-down structure used in the URLs. For example:

• The List Mailing Lists request uses the following URL: https://yourdatacenterid.qualtrics.com/API/v3/mailinglists
• You can then use an ID returned with that request to get a specific mailing list by appending the ID to the end of the URL: https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/:mailingListId
• To list the contacts within that mailing list, add contacts to the end: https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/:mailingListId/contacts
• To get a specific contact, you can then use a contactId returned in the previous request: https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/:mailingListId/contacts/:contactId

EXAMPLES

The examples given on the documentation show you how to format the request in cURL. These requests include the root URL and all required parameters from the parameters table.

RESULT FORMAT

This section gives an example of what you can expect to receive once your API request is successful. For example, if you’re using the API request Create User, your response will be the user ID of the newly created user.

TRY IT

The API Reference page contains a “Try It” function that allows you to quickly and easily test an API request (note that most API requests require Qualtrics IDs). Let’s demonstrate the wizard by using our example API request List Surveys. Below is how you’ll test your API call:

1. Click the person icon to bring up the API Token field.
   
2. Enter your account’s API token.
3. Enter any additional parameters.
4. Press Try It to test the API call.

Once you’ve entered the necessary values for your request, you’ll see the call’s output.

In addition to returning the response to the API request, the wizard will display the following information about the request in the Metadata tab:

• Method: GET, POST, PUT, or DELETE
• URL: The URL of the request.
• Request Headers: This includes the Token and may include Content-Type and any other information passed through the headers of the request.
• Request Data: This will contain the JSON used in the body of the request. When no request data is present, such as in the case of GET requests, it will be empty.
• Status: The HTTP response code. See the API Responses documentation for information regarding various response codes and their significance.
• Response Headers: The headers of the response returned from Qualtrics.