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.

In this guide

Set up the integration
Use Qualtrics in a metric
Troubleshooting

Set up the integration

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)

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.

Tip: Use a dedicated connector account

Create a separate Qualtrics user (for example, [email protected]) 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Still not working? Contact support at [email protected]

Last updated 20 days ago