Skip to main content

Qualtrics’ API Evolution Philosophy

Overview​

Over time, Qualtrics® product functionality changes to incorporate new scenarios, evolve scenarios, and occasionally remove product capabilities to make way for improved functionality. The Qualtrics API will undergo a similar lifecycle. This guide will help clarify Qualtrics’ process for making API changes, clarify expectations for what changes you may need to make as a result of any API change, and the notification process for changes that are considered Breaking (as defined below).

Please review this guide carefully to understand what changes are considered Breaking and Non-Breaking (as defined below), and how to ensure that your application can adapt automatically to Non-Breaking changes.

Important​

Qualtrics reserves the right to, and may, make changes without prior notice if the change is considered Non-Breaking or if it is a Breaking Change being made to address critical product issues or legal, security, or privacy concerns.

Definitions​

Breaking changes​

A “Breaking Change” is a change that may require you to make changes to your application in order to avoid disruption to your integration. For Breaking Changes, an email communication (see Communication section) is sent to impacted organizations.

The following are a few examples of changes we consider Breaking:

  • Restricting permissions required for calling the API
  • Removal of an allowed query parameter, body parameter, headers, request field or response field
  • Addition of a required parameter or request field without default values
  • Changes to the intended functionality of an endpoint. For example, if a DELETE request previously used to archive the resource but now hard deletes the resource.
  • Removal of a field returned in the response
  • Changes to the response field’s name
  • Removal and changes to an existing authentication method (OAuth 2.0 or X-API-TOKEN)
  • Removing Endpoints from an OAuth 2.0 scope, removing an OAuth 2.0 scope
  • Introduction of a new request validation (such as parameter validation)
  • Decreases to rate limit
  • Removal of an API endpoint
  • Changes to a file returned or ingested:
    • Changes in filename format
    • Changes in file location
    • Changes in encoding (ASCII, UTF-8, UTF-16)
    • Changes in file extension (csv, tsv, json, .zip, etc)
    • Decreases in file size limit
    • (case-by-case) Changes in file contents / structure

Non-Breaking changes​

A Non-Breaking change is a change that you can adapt to at your own discretion and pace without disruption.

We highly recommend making sure that your application is designed to be able to handle the following types of Non-Breaking changes without prior notice from Qualtrics:

  • Relaxing permissions required for calling the API
  • Addition of new endpoints
  • Addition of new methods to existing endpoints
  • Addition of new fields in the following scenarios:
    • New fields in responses
    • New optional request fields or parameters
    • New required request fields that have default values
  • Addition of a new value returned for an existing text field
  • Changes to the order of fields returned within a response
  • Addition of an optional request header
  • Removal of redundant request header
  • Changes to the length of data returned within a field
  • Changes to the overall response size
  • Response latency increases
  • Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.
  • Fixes to HTTP response codes and error codes from incorrect code to correct code.
  • Increases to rate limits
  • Addition of new authentication means
  • Adding a new OAuth 2.0 scope, or adding endpoints to an existing OAuth 2.0 scope

Communication​

For any changes classified as Breaking, Qualtrics will send an email communication to the most active Brand Admins (as determined by recent sign in history) for your organization. We will also post the change to our List of Breaking API Changes.

Breaking Change emails will include:

  1. A description of the change.
  2. The required action you must take.
  3. The date at which the change will take place.

Qualtrics endeavors to send email notifications about 180 days prior to the change. This may vary from time to time. Emails are sent about 365 days prior if an API is being turned off.

To avoid disruption to your users, make sure that you perform the recommended actions before the release date of the Breaking Change. If you believe an uncommunicated Breaking Change has occurred in the Qualtrics API, please contact Qualtrics Support to report the issue.

Disclaimer: Qualtrics may, in its sole discretion and without liability, change the timing of any product feature rollout, change the functionality for any in preview, in development, or released product feature, or choose not to release a product feature or functionality for any reason or for no reason.

Disclaimer​

Qualtrics may, in its sole discretion and without liability, change the timing of any product feature rollout, change the functionality for any in preview, in development, or released product feature, or choose not to release a product feature or functionality for any reason or for no reason.