Qualtrics Integration

Qualtrics is the survey engine at the heart of the TABS research project. It hosts the survey instrument, manages branching logic, captures respondent data, and handles the post-survey redirect flow. We interact with Qualtrics programmatically via its REST API v3, which enables us to copy surveys, inspect definitions, apply configuration changes, and export data — all from GitHub Actions.

Why Qualtrics

We chose Qualtrics for several reasons critical to a long-term academic survey:

• Sophisticated logic capabilities — Complex question branching adapts to the respondent's role and industry, ensuring participants see only the questions relevant to them.
• Enterprise-grade security — SOC 2 Type II compliance, data encryption at rest and in transit, and fine-grained access controls.
• API-first platform — Every aspect of survey management (creation, configuration, export) is accessible via REST endpoints, enabling full automation.
• Embedded Data & Survey Flow — The Survey Flow engine allows us to capture URL parameters, set variables, branch conditionally, and control the respondent experience without custom code.

API Integration Pattern

Every Qualtrics API call is authenticated with an X-API-TOKEN header. The token is stored as a GitHub Actions secret in the qualtrics-prod environment and is never committed to the repository.

Automated Workflows

Seven GitHub Actions workflows automate different aspects of Qualtrics management:

Survey Flow Architecture

The most critical piece of the Qualtrics configuration is the Survey Flow — the sequence of logic steps executed for each respondent. The TABS survey uses a "redirect lockdown" pattern with two conditional branches that ensure every respondent ends up at the correct destination.

The redirect lockdown prevents open-redirect vulnerabilities by hard-coding COMPLETE_URL in the Survey Flow rather than accepting it as a URL parameter. See the Technical Integrations overview for the full visual flow diagram.

Annual Survey Rollover

TABS runs a 10-year data collection effort. Each year, a new copy of the survey is created to keep yearly data cleanly separated. The recommended rollover sequence:

1. Test connectivity — Run the smoke test workflow to verify API credentials are valid.
2. Copy the survey — Use the copy workflow to clone the current year's survey.
3. Update environment variable — Point QUALTRICS_SURVEY_ID at the new survey ID in GitHub environment variables.
4. Verify configuration — Run the verification workflow against the new survey.
5. Apply Prolific integration — If the copy didn't preserve Survey Flow branches, re-apply them using the apply workflow.
6. Update Prolific study — Point the Prolific study's external URL at the new Qualtrics survey link.

This entire process can be completed in under 30 minutes using the automated workflows. All steps are documented in PROLIFIC_INTEGRATION.md.

Data-Driven Site Metrics

The Qualtrics integration feeds live data to the website. The daily metrics workflow queries the Qualtrics API for response counts and question metadata, then writes the results to src/data/qualtrics-metrics.json. The homepage and media page import this file to display:

• Surveys Completed — Total response count across all distribution channels
• Survey Questions — Actual question count fetched from the survey definition API (replacing a previously hardcoded "100+")

This ensures the numbers displayed on the site always reflect the current state of the survey without manual updates.

Related

• Technical Integrations overview
• Prolific Integration — participant recruitment and the Qualtrics–Prolific bridge
• Google Analytics Integration — impact measurement and verified visitors