How to Integrate Lovable with Qualtrics

Qualtrics requires a datacenter-specific API URL for every request — this is the single most important configuration step and the most common source of integration failures. Log in to your Qualtrics account at yourdomain.qualtrics.com. Click your user icon in the top-right corner and select Account Settings. In the Account Settings page, click on the 'Account section' header to expand the account information, then find 'Qualtrics IDs' in the left sidebar and click it. On the Qualtrics IDs page, you will see several important identifiers. The Datacenter ID is labeled clearly — it is a short string like 'ca1' (Canada), 'fra1' (Frankfurt), 'iad1' (US East), 'sjc1' (US West), or 'syd1' (Sydney). This determines the base URL for all API calls: https://[datacenter-id].qualtrics.com/API/v3. Copy this datacenter ID carefully — a typo here means all API calls will fail with authentication errors. On the same page, find the API section and click 'Generate Token' to create your API token. If you already have a token, it will be shown here (partially obscured for security). Copy the full token value. Note that Qualtrics API tokens have full access to all resources in your organization's Qualtrics account — they are not scoped to specific surveys. Treat this token with the same security as a database root password. Also copy your Organization ID from this page — formatted as a string like 'yourcompany' — and the Survey IDs for the surveys you want to integrate (each Survey ID starts with 'SV_'). Now go to your Lovable project, open the Cloud tab, and add these secrets: QUALTRICS_API_TOKEN (your token), QUALTRICS_BASE_URL (formatted as https://[datacenter-id].qualtrics.com/API/v3), and QUALTRICS_ORG_ID (your organization ID). Add VITE_QUALTRICS_SURVEY_URL as the public survey URL for iframe embedding.

Create a Supabase Edge Function that proxies requests from your Lovable frontend to the Qualtrics API, handling authentication and the datacenter-specific URL abstraction. The function reads QUALTRICS_API_TOKEN and QUALTRICS_BASE_URL from Deno.env.get() to construct authenticated requests. Qualtrics API v3 uses the X-API-TOKEN header for authentication — unlike Bearer token approaches used by many other APIs, Qualtrics requires this specific header name. Every request must include 'X-API-TOKEN: [your-token]' in the headers. Forgetting this header or using 'Authorization: Bearer' instead results in a 401 response. The most useful Qualtrics API endpoints for a Lovable integration are: GET /surveys (list all surveys in the organization), GET /surveys/{surveyId} (get survey metadata including questions and structure), POST /surveys/{surveyId}/export-responses (initiate a response export), GET /surveys/{surveyId}/export-responses/{exportProgressId} (check export progress), and GET /surveys/{surveyId}/export-responses/{exportProgressId}/file (download the exported response file as a ZIP containing JSON or CSV). Qualtrics uses a multi-step export process for responses (not a single GET call). First, POST to initiate the export and receive a progress ID. Then poll the progress endpoint until the export status is 'complete'. Finally, download the ZIP file from the file endpoint. This asynchronous pattern is necessary for large response datasets but adds complexity for real-time dashboard use — for dashboards, use the webhook approach to store responses incrementally rather than bulk exporting on every page load. For the proxy function, support two modes: a 'surveys' mode that lists surveys (fast, single API call) and a 'responses' mode that uses the async export pattern for full response data (slower, multi-step). Cache exported responses in Supabase to avoid repeated exports.

1// supabase/functions/qualtrics-proxy/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
3
4const corsHeaders = {
5  'Access-Control-Allow-Origin': '*',
6  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
7};
8
9serve(async (req) => {
10  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
11
12  try {
13    const apiToken = Deno.env.get('QUALTRICS_API_TOKEN');
14    const baseUrl = Deno.env.get('QUALTRICS_BASE_URL');
15
16    if (!apiToken || !baseUrl) {
17      return new Response(
18        JSON.stringify({ error: 'QUALTRICS_API_TOKEN or QUALTRICS_BASE_URL not configured' }),
19        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
20      );
21    }
22
23    const url = new URL(req.url);
24    const resource = url.searchParams.get('resource') ?? 'surveys';
25    const surveyId = url.searchParams.get('survey_id');
26
27    const qualtricsHeaders = {
28      'X-API-TOKEN': apiToken,
29      'Content-Type': 'application/json',
30    };
31
32    let apiUrl = '';
33    if (resource === 'surveys') {
34      apiUrl = `${baseUrl}/surveys`;
35    } else if (resource === 'survey-detail' && surveyId) {
36      apiUrl = `${baseUrl}/surveys/${surveyId}`;
37    } else {
38      return new Response(JSON.stringify({ error: 'Invalid resource or missing survey_id' }), {
39        status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
40      });
41    }
42
43    const qResponse = await fetch(apiUrl, { headers: qualtricsHeaders });
44
45    if (qResponse.status === 401) {
46      return new Response(JSON.stringify({ error: 'Invalid Qualtrics API token' }), {
47        status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
48      });
49    }
50    if (qResponse.status === 403) {
51      return new Response(JSON.stringify({ error: 'Qualtrics plan does not support this API endpoint' }), {
52        status: 403, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
53      });
54    }
55
56    const data = await qResponse.json();
57    return new Response(JSON.stringify(data), {
58      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
59    });
60  } catch (error) {
61    return new Response(JSON.stringify({ error: String(error) }), {
62      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
63    });
64  }
65});

Qualtrics surveys can be embedded in web applications using two methods: iframe embedding with the survey's published URL, and the Qualtrics Web SDK for more integrated embedding with custom styling and event handling. For most Lovable app integrations, iframe embedding is simpler and more reliable. To get the survey's iframe URL, log in to Qualtrics, open your survey, click 'Distributions', then 'Anonymous Link'. The Anonymous Link URL is the public survey URL suitable for iframe embedding — it looks like https://[org].qualtrics.com/jfe/form/SV_xxxxxxxxx. Store this URL as VITE_QUALTRICS_SURVEY_URL in Lovable's environment configuration. For personalized data capture, pass user context through embedded data URL parameters. Append query parameters to the survey URL to pre-populate embedded data fields in Qualtrics: ?Q_EmbeddedData=userId~[user_id]|userPlan~[plan]. The respondent will not see these values, but they are stored with each response, enabling you to match survey responses back to Supabase user records. Qualtrics surveys fire a window.postMessage event when the survey is completed — the message data includes a 'QualtricsEmbeddedFeedback' type with the survey ID. Listen for this event in your Lovable React component to detect completion and close the modal or trigger post-survey actions. Note that the exact postMessage format varies slightly between Qualtrics versions — test with your specific survey to confirm the message format. For a better embedded experience, append &Q_SkinType=button to the survey URL on some Qualtrics configurations to hide the Qualtrics branding. Your Qualtrics license terms govern whether removing the branding is permitted.

1// src/components/QualtricsModal.tsx
2import { useEffect, useCallback } from 'react';
3import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
4import { supabase } from '@/integrations/supabase/client';
5
6interface QualtricsModalProps {
7  open: boolean;
8  onClose: () => void;
9  userId: string;
10  userPlan?: string;
11}
12
13const SURVEY_URL = import.meta.env.VITE_QUALTRICS_SURVEY_URL;
14
15export function QualtricsModal({ open, onClose, userId, userPlan = 'free' }: QualtricsModalProps) {
16  const handleClose = useCallback(async () => {
17    await supabase
18      .from('profiles')
19      .update({ qualtrics_survey_completed: true })
20      .eq('id', userId);
21    onClose();
22  }, [userId, onClose]);
23
24  useEffect(() => {
25    function handleMessage(event: MessageEvent) {
26      // Handle Qualtrics completion postMessage
27      if (
28        event.data === 'QSIFinished' ||
29        (typeof event.data === 'object' && event.data?.type === 'QualtricsEmbeddedFeedback')
30      ) {
31        handleClose();
32      }
33    }
34    if (open) window.addEventListener('message', handleMessage);
35    return () => window.removeEventListener('message', handleMessage);
36  }, [open, handleClose]);
37
38  if (!SURVEY_URL) return null;
39
40  const embeddedParams = `userId~${encodeURIComponent(userId)}|userPlan~${encodeURIComponent(userPlan)}`;
41  const iframeUrl = `${SURVEY_URL}?Q_EmbeddedData=${embeddedParams}`;
42
43  return (
44    <Dialog open={open} onOpenChange={(isOpen) => !isOpen && handleClose()}>
45      <DialogContent className="max-w-3xl h-[85vh] p-0 overflow-hidden">
46        <DialogHeader className="px-6 pt-4 pb-2">
47          <DialogTitle>Share Your Feedback</DialogTitle>
48        </DialogHeader>
49        <iframe
50          src={iframeUrl}
51          className="w-full flex-1 border-none"
52          style={{ height: 'calc(100% - 60px)' }}
53          title="Qualtrics Survey"
54          allow="camera; microphone"
55        />
56      </DialogContent>
57    </Dialog>
58  );
59}

Qualtrics's workflow triggers (formerly called event subscriptions) deliver response data to an external URL when survey responses are submitted. This real-time delivery is far more efficient than polling the API and enables immediate follow-up actions. Setting up webhook delivery requires configuring a workflow trigger in your Qualtrics survey. In your Qualtrics account, open the survey, click 'Workflows' in the top navigation. Click 'Create a workflow' and select 'Survey response' as the event trigger — this fires for every completed response. In the workflow's action step, select 'Web Service' as the action type. Set the method to POST and enter your Edge Function URL (https://[project-ref].supabase.co/functions/v1/qualtrics-webhook). In the request body, set the format to JSON and include the following fields mapped from Qualtrics embedded data and response values: ResponseId (from Response), status (from Response), values (from Response - Full Response), and any specific question values you need. The webhook payload structure in Qualtrics is customizable — you define exactly what fields are included in the JSON body through the workflow's 'Add field' interface. This is more flexible than SurveyMonkey but requires more configuration. At minimum, include the ResponseId so your Edge Function can fetch the full response via the API, or include all the relevant question values directly in the webhook body to avoid the additional API call. In the Edge Function, parse the incoming JSON body, extract the response data, and store it in your Supabase database. For NPS programs, also trigger the appropriate follow-up logic: create a support ticket for detractors, add promoters to a referral campaign audience, or send a summary email to the customer success team. For complex XM workflows or implementing Qualtrics's advanced features like panels or directory management, RapidDev's team can help design the integration architecture.

1// supabase/functions/qualtrics-webhook/index.ts
2import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
3import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';
4
5const corsHeaders = {
6  'Access-Control-Allow-Origin': '*',
7  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
8};
9
10serve(async (req) => {
11  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
12  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
13
14  try {
15    const supabase = createClient(
16      Deno.env.get('SUPABASE_URL') ?? '',
17      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
18    );
19
20    const body = await req.json();
21    const responseId = body.ResponseId ?? body.response_id;
22    const surveyId = body.SurveyID ?? body.survey_id;
23    const npsScore = body.nps_score !== undefined ? Number(body.nps_score) : null;
24    const respondentEmail = body.respondent_email ?? null;
25    const verbatimFeedback = body.verbatim_feedback ?? null;
26
27    if (!responseId) {
28      return new Response(JSON.stringify({ error: 'ResponseId missing from payload' }), {
29        status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
30      });
31    }
32
33    // Store response
34    const { error: insertError } = await supabase.from('xm_responses').upsert({
35      response_id: responseId,
36      survey_id: surveyId,
37      nps_score: npsScore,
38      respondent_email: respondentEmail,
39      verbatim_feedback: verbatimFeedback,
40      raw_payload: body,
41    }, { onConflict: 'response_id' });
42
43    if (insertError) console.error('DB insert error:', insertError);
44
45    // Queue detractor follow-up
46    if (npsScore !== null && npsScore < 7) {
47      await supabase.from('follow_up_tasks').insert({
48        type: 'detractor_followup',
49        response_id: responseId,
50        respondent_email: respondentEmail,
51        nps_score: npsScore,
52        status: 'pending',
53      });
54    }
55
56    return new Response(JSON.stringify({ success: true }), {
57      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
58    });
59  } catch (error) {
60    console.error('Qualtrics webhook error:', error);
61    return new Response(JSON.stringify({ error: String(error) }), {
62      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
63    });
64  }
65});