# Qualtrics
## How to set up the Qualtrics integration
To use Qualtrics data in Smaply metrics, an Admin connects Qualtrics once at the account level using a Qualtrics API token and base URL. After that, anyone in your workspaces can pull survey response counts, averages, and breakdowns into metric cards on a journey map.
{% hint style="info" icon="clipboard-list" %}
**In this guide**
1. Set up the integration
2. Use Qualtrics in a metric
3. Troubleshooting
{% endhint %}
**Set up the integration**
{% hint style="warning" icon="list-check" %}
**Prerequisites**
* Admin role at the Smaply account level
* A Qualtrics account with API access
* Your Qualtrics API token and base URL (for example, `iad1.qualtrics.com`)
{% endhint %}
Qualtrics uses a single authentication method: an API token paired with the base URL of your Qualtrics datacenter. The token inherits the permissions of the Qualtrics user that generated it, so it can read every survey that user can read.
{% 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 %}
**Generate a Qualtrics API token**
In Qualtrics, open your account menu and go to **Account Settings > Qualtrics IDs**. Under **API**, click **Generate Token**. Copy the token immediately.
{% 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 %}
**Find your Qualtrics base URL**
The base URL is the datacenter portion of your Qualtrics URL. When you are signed in to Qualtrics, look at the address bar — the host before `/Q/...` is your base URL (for example, `iad1.qualtrics.com`, `fra1.qualtrics.com`, or `syd1.qualtrics.com`). You will paste this into Smaply in the next step.
{% endstep %}
{% step %}
**Open the Qualtrics integration in Smaply**
In Smaply, open **Account Settings > Integrations**, find **Qualtrics** in the metrics list, and click **Set up**. The **Configure Qualtrics** page opens with empty **API token** and **Base URL** fields.
{% endstep %}
{% step %}
**Enter your credentials and save**
Paste the API token into the **API token** field and the datacenter host into the **Base URL** field, then click **Save**. 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.
{% endstep %}
{% endstepper %}
***
**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.
{% 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.
Connection issue - Connection Failed or Connection Error banner
A red banner on the **Configure Qualtrics** page means Smaply cannot reach Qualtrics with the stored credentials.
* Confirm the **Base URL** matches your Qualtrics datacenter exactly (for example, `iad1.qualtrics.com`, not `https://iad1.qualtrics.com/`). Smaply expects the host only.
* Re-check the **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.
Authentication issue - Token rejected during Save
The credentials fail validation when you click **Save**.
* The token may have been revoked in Qualtrics. Open Qualtrics, generate a new token under **Account Settings > Qualtrics IDs > API**, 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.
Surveys issue - No surveys appear when configuring a metric
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.
Data issue - A metric returns no data or unexpected values
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 space.vars.supportEmail for diagnosis.
Token revoked - Metrics that worked previously have stopped pulling
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).
{% hint style="info" icon="headset" %}
**Still not working?** Contact support at
{% endhint %}
***
**Related topics**
---
# Agent Instructions: 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:
```
GET https://helpdesk.smaply.app/integrations/metrics-tools/qualtrics.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.