> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration.md).

# How to set up the Qualtrics integration

An Admin connects Qualtrics once at the account level. After that, anyone in the workspace can build metrics from your surveys.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Qualtrics integration](#set-up-the-qualtrics-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Qualtrics in a metric](#use-qualtrics-in-a-metric)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Qualtrics integration

{% hint style="info" icon="tag" %}

#### Plan availability

The Qualtrics integration is available on the **Governance** plan.
{% endhint %}

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the Smaply account level
* A Qualtrics account with API access
* A Qualtrics API token
* Your Qualtrics base URL (the datacenter host only, for example `iad1.qualtrics.com`)
  {% endhint %}

{% hint style="success" icon="lightbulb" %}

#### **Tip: Use a dedicated connector account**

Create a separate Qualtrics user (for example, `smaply-qualtrics@yourcompany.com`) and give it access only to the surveys you want to surface in Smaply. Generating the API token from this account keeps the connection scoped to a known set of surveys and avoids tying it to an individual employee's login.
{% endhint %}

{% stepper %}
{% step %}
**Open the Qualtrics integration in Smaply**

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Qualtrics**.

<figure><img src="/files/41AOLLxk95TgSiwBMZVp" alt="Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right."><figcaption><p>Account settings > Integrations</p></figcaption></figure>

The **Configure Qualtrics** page opens with empty fields for your API token and base URL, plus an inline help block.
{% endstep %}

{% step %}
**Get your Qualtrics credentials**

You need two values from Qualtrics: an API token and your datacenter base URL.

<figure><img src="/files/lf7mqiK8HJLPoKXrx8s9" alt="Configure Qualtrics page in Smaply with empty Qualtrics API token and Qualtrics base URL fields, plus a how-to setup info block above the form."><figcaption><p>Configure Qualtrics, empty form</p></figcaption></figure>

In Qualtrics:

* Log in and navigate to **Account Settings > Qualtrics IDs**. Under **API**, click **Generate Token** and copy the token immediately.
* Take your datacenter base URL from the host part of your Qualtrics web address, for example `iad1.qualtrics.com`, `fra1.qualtrics.com`, or `syd1.qualtrics.com`. Enter the host only, with no `https://` and no path after it.

{% hint style="warning" %}

#### **Important: Save the token before leaving the page**

Qualtrics shows the API token only once. If you navigate away without copying it, you will need to generate a new one.
{% endhint %}
{% endstep %}

{% step %}
**Enter your credentials and save**

Back in Smaply, paste the API token into the **Qualtrics API token** field and the datacenter URL into the **Qualtrics base URL** field, then click **Save Configuration**. Smaply validates the credentials against Qualtrics before storing them.

The token is encrypted at rest and masked in the UI after save. You can edit or delete the configuration later from the same page.
{% endstep %}

{% step %}
**Verify the connection**

A green **Connection established** banner confirms Smaply can reach Qualtrics. The page now shows a **Qualtrics integration details** card with the masked token and base URL, plus **Edit Configuration** and **Delete Configuration** buttons.

<figure><img src="/files/B5TF9gCdRsVf4EEiKLFi" alt="Configure Qualtrics page after a successful connection, showing a green Connection established banner above a Qualtrics integration details card with the base URL and a masked API token, Edit Configuration and Delete Configuration buttons, and a Debug Configuration section below."><figcaption><p>Connection established</p></figcaption></figure>
{% endstep %}
{% endstepper %}

***

#### Verify the setup

To confirm the connection before anyone builds a metric on it, reopen **Account Settings > Integrations** and click **Edit** next to **Qualtrics**. On the **Configure Qualtrics** page, a green **Connection established** banner ("Successfully connected to Qualtrics") means Smaply can reach Qualtrics with the stored credentials.

If you see a red **Connection Failed** or **Connection Error** banner instead, see [Troubleshooting](#troubleshooting) below.

***

#### Use Qualtrics in a metric

Once the integration is connected, Editors create Qualtrics metrics like any other Smaply metric. The metric configuration modal exposes the Qualtrics-specific fields below the standard **Name**, **Source**, and **Type** fields:

* **Survey**: which Qualtrics survey to pull responses from
* **Question**: the survey question whose responses drive the metric
* **Group by**: an option to break the metric down (for example, by response category)
* **Calculation**: how individual responses are aggregated into the displayed value

For the full metric flow, including Number, Series, and Comparison types, chart options, and how the card behaves on a journey map, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the survey question to the journey moment**

Pick the question that maps to the stage you want the metric to sit on. A post-purchase NPS question reads differently on the "Onboarding" stage than on the "Renewal" stage, even when the underlying numbers are the same.
{% endhint %}

Qualtrics metrics refresh on load when the previous update attempt is older than one hour. There is no continuous or streaming pull.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Qualtrics** page means Smaply cannot reach Qualtrics with the stored credentials.

* Confirm the **Qualtrics base URL** is the datacenter host only, with no `https://` and no path (for example `iad1.qualtrics.com`). Pasting the full browser address is the most common cause.
* Re-check the **Qualtrics API token**. Leading or trailing whitespace pasted from a clipboard is a common cause.
* If the Qualtrics user that generated the token has been deactivated, the token stops working. Generate a new token from an active account.

</details>

<details>

<summary><strong>Token rejected during Save</strong> - Authentication issue</summary>

The credentials fail validation when you click **Save Configuration**.

* The token may have been revoked in Qualtrics. Open Qualtrics, generate a new token under **Account Settings > Qualtrics IDs**, and paste the new value into Smaply.
* The Qualtrics account that generated the token may not have **API access** enabled. A Qualtrics Brand Administrator can confirm and enable it.

</details>

<details>

<summary><strong>No surveys appear when configuring a metric</strong> - Surveys issue</summary>

The connection succeeds but the **Survey** dropdown in the metric configuration is empty.

* The Qualtrics user behind the token does not have access to any surveys. Share the surveys with that user in Qualtrics, or generate the token from a user that already has access.
* If you are using a dedicated connector account, confirm that the surveys you expect have been explicitly shared with that account in Qualtrics.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

The metric loads but the values look wrong, empty, or stale.

* Open the metric and check the **Survey**, **Question**, and **Calculation** are still pointing at the right Qualtrics objects. Question IDs change if a question is deleted and re-added in Qualtrics.
* Confirm the survey actually has new responses since the last refresh. Metrics refresh on load when the previous update is older than one hour, so freshly-added responses can take up to an hour to appear.
* If the values are still unexpected, use **Debug Configuration** on the **Configure Qualtrics** page. Pick the affected survey, click **Download survey data**, and send the file to <code class="expression">space.vars.supportEmail</code> for diagnosis.

{% hint style="warning" %}

#### **Important: The debug download contains sensitive data**

The Debug Configuration export includes the raw survey list, survey details, and response JSON for the selected survey. Treat the file as sensitive, share it only with Smaply support, and only download it when support has asked for it.
{% endhint %}

</details>

<details>

<summary><strong>Metrics that worked previously have stopped pulling</strong> - Token revoked</summary>

A previously working integration shows an error and metrics stop updating.

* The most common cause is a revoked or rotated API token in Qualtrics. Generate a new token, open the **Configure Qualtrics** page in Smaply, click **Edit Configuration**, paste in the new token, and save.
* If the Qualtrics account itself has been deactivated, generate the token from a different active account (a dedicated connector account is the most resilient option).

</details>

For wider questions about how integrations behave across tools (refresh frequency, plan availability, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Manage integrations</strong></td><td>Disconnect, edit credentials, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Use Qualtrics in a metric</strong></td><td>Build a metric card from a survey question once the integration is connected.</td><td><a href="/pages/YlBBu3nrg4BHYJ9YcmGk">/pages/YlBBu3nrg4BHYJ9YcmGk</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/metrics-tools/qualtrics/how-to-set-up-the-qualtrics-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.