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).

Allowlist Qualtrics servers

See Allowlist Qualtrics Servers.

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, description, and URL

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

The URL used in the request (or “definition”) will be listed next to the HTTP verb.

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

List of body parameters

For each API request, you’ll see a table listing all possible body 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

Request sample

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

Response example

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.

Completing API requests on the API Site

Our API Documentation allows you to quickly and easily execute an API request. (Note that most API requests require Qualtrics IDs.)

1. Select between API Key and OAuth 2.0.
   
2. Enter your account’s API token in the API Token field. (Or the corresponding OAuth 2.0 information, if you chose OAuth 2.0.)
3. Enter any additional parameters.
4. Click Users to choose a server to test on. For the most accurate test, you want this to match the data center of your account.
5. Press Send API Request to test the API call.

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