Integrating Verisoul with Qualtrics Surveys

Last updated: October 27, 2025

Guide Type: Implementation / Developer Integration
Goal: Collect a Verisoul session_id in Qualtrics, send it to your backend, call Verisoul’s Authenticate Session API, and use the returned decision (e.g., Real) inside Qualtrics for branching and reporting.
Last updated: Oct 27, 2025

Estimated Time: 60-120 minutes

What you’ll build

Load the Verisoul Browser SDK in a Qualtrics question.
Call window.Verisoul.session() to get a session_id in the browser. docs.verisoul.ai
POST that session_id (and account info) to your backend.
Your backend calls POST /session/authenticate with x-api-key and returns the full JSON (including decision) to the browser. docs.verisoul.ai
Store decision (and/or raw payload) as Embedded Data in Qualtrics for logic and analytics. Qualtrics supports per-question JavaScript via Add JavaScript.

Prerequisites

Verisoul Project ID and API key
Backend HTTPS endpoint you control
Qualtrics survey with permission to add question-level JavaScript

Step 1: Backend endpoint (Node.js/Express)

This endpoint accepts a session_id and your app’s account object (at minimum an id), then calls Verisoul’s Authenticate Session API using x-api-key. The API returns a JSON payload that includes the top-level decision field (e.g., Real). docs.verisoul.ai

// backend/verisoulVerify.js
import express from "express";
import fetch from "node-fetch";

const app = express();
app.use(express.json());

app.post("/api/verify", async (req, res) => {
  const { session_id, account } = req.body;

  if (!session_id) {
    return res.status(400).json({ error: "Missing session_id" });
  }
  if (!account || !account.id) {
    return res.status(400).json({ error: "Missing account.id" });
  }

  try {
    // Choose sandbox or prod depending on your environment
    const VERISOUL_BASE = process.env.VERISOUL_ENV === "prod"
      ? "https://api.verisoul.ai"
      : "https://api.sandbox.verisoul.ai";

    const resp = await fetch(`${VERISOUL_BASE}/session/authenticate`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        // Verisoul uses x-api-key header
        "x-api-key": process.env.VERISOUL_API_KEY,
      },
      body: JSON.stringify({
        session_id,
        account, // e.g., { id, email, metadata, group, lists }
      }),
    });

    const verisoul = await resp.json();

    if (!resp.ok) {
      console.error("Verisoul API error:", verisoul);
      return res.status(resp.status).json({
        error: "Verisoul API returned an error",
        details: verisoul,
      });
    }

    // Return the full payload and surface decision prominently
    return res.status(200).json({
      decision: verisoul.decision, // e.g., "Real"
      verisoul,                    // full payload for debugging/analytics
    });
  } catch (err) {
    console.error("Verisoul verify error:", err);
    return res.status(500).json({
      error: "Server error during Verisoul verification",
      details: err.message,
    });
  }
});

app.listen(3000, () => console.log("Backend listening on 3000"));

Why this format?

Verisoul’s API requires x-api-key, a session_id, and an account object in the body. The response includes a top-level decision string and rich session/account details. docs.verisoul.ai

Step 2: Add Verisoul to a Qualtrics question

In the Qualtrics Survey Editor, open the question where you want to run verification (often the first question/block).
Click Question Options → Add JavaScript, then paste the snippet below. Qualtrics runs this code when the question loads. Qualtrics

Verisoul recommends the async script tag with a verisoul-project-id attribute. Replace {env} with sandbox or prod, and {project_id} with your project ID. Then call window.Verisoul.session() to get a session_id.

Qualtrics.SurveyEngine.addOnload(function () {
  // 1) Load Verisoul Browser SDK (async helper version)
  const s = document.createElement("script");
  s.async = true;
  s.src = "https://js.verisoul.ai/sandbox/bundle.js"; // or prod
  s.setAttribute("verisoul-project-id", "YOUR_PROJECT_ID");
  document.head.appendChild(s);

  // 2) When SDK is ready, request a session_id and send to backend
  // The async installation provides a proxy so you can call Verisoul.session()
  // without manually awaiting the script onload. :contentReference[oaicite:7]{index=7}
  (async () => {
    try {
      // Get a session_id (do this right before you need to call the backend)
      const { session_id } = await window.Verisoul.session(); // returns { session_id } :contentReference[oaicite:8]{index=8}

      // TODO: Build your account object. At minimum, include an id.
      // You may pass email, lists, metadata, etc., if you have them.
      const account = {
        id: "${e://Field/QualtricsUserId}" || "anonymous", // example; replace with your identifier
        // email: "...",
        // lists: ["us_users"],
        // metadata: { survey_id: "${e://Field/ResponseID}" }
      };

      const resp = await fetch("https://YOUR_BACKEND_DOMAIN/api/verify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ session_id, account }),
      });
      const data = await resp.json();

      // 3) Store the top-level decision and the full payload (optional) as Embedded Data
      Qualtrics.SurveyEngine.setEmbeddedData("VerisoulDecision", data.decision || "unknown");
      Qualtrics.SurveyEngine.setEmbeddedData("VerisoulPayload", JSON.stringify(data.verisoul || {}));
    } catch (e) {
      console.error("Verisoul integration error:", e);
      Qualtrics.SurveyEngine.setEmbeddedData("VerisoulDecision", "error");
    }
  })();
});

Step 3: Branch on the decision field

When your backend calls Verisoul’s Authenticate Session, the response contains a top-level decision string (e.g., Real) and detailed session/account info. Use decision as the primary gate in Qualtrics logic. docs.verisoul.ai

Example branching (Survey Flow):

If data.decision equals Real → continue survey
Else → show a “verification failed” message or end the survey

You can also log VerisoulPayload for analysis (contains account_score, risk_signals, session.network, session.device, etc.). docs.verisoul.ai

Security & reliability checklist

Never put the API key in Qualtrics JS; send session_id to your backend and call Verisoul with x-api-key there. docs.verisoul.ai
Use the SDK’s async script tag with verisoul-project-id, and call Verisoul.session() only when needed; session_ids expire after 24 hours. docs.verisoul.ai
Consider initializing the script as early as possible to maximize signal quality. docs.verisoul.ai
If window.Verisoul or session() fails (e.g., blocked script or sanctioned region), follow the troubleshooting guidance and gracefully prevent progression. docs.verisoul.ai

Optional: Qualtrics Actions “Web Service Task”

If you prefer to post the backend result after response completion, you can use Actions → Web Service Task. It can call external services with headers/body you define (e.g., post VerisoulDecision), typically on survey completion. Qualtrics

End-to-end flow (concise)

Qualtrics question loads → Verisoul SDK script tag (async). docs.verisoul.ai
JS calls window.Verisoul.session() → obtains session_id. docs.verisoul.ai
Frontend posts { session_id, account } to your backend.
Backend calls POST {env}/session/authenticate with x-api-key → receives payload containing decision and rich details. docs.verisoul.ai
Backend returns { decision, verisoul } to the browser.
Qualtrics stores VerisoulDecision (and optionally VerisoulPayload) as Embedded Data and branches accordingly. Qualtrics

References

Verisoul Browser SDK (script tag, session(), env/project params): docs.verisoul.ai
Verisoul Authenticate Session (endpoint, x-api-key, response fields incl. decision): docs.verisoul.ai
Qualtrics Add JavaScript to a Question (where the code goes): Qualtrics
Optional: Qualtrics Web Service Task (call external services on completion): Qualtrics