qualtrics-ops

name	qualtrics-ops
description	Operate a live Qualtrics survey via the v3 APIs without breaking fielding. Publish gating, quotas, flow routing, embedded data, panel-vendor redirects, and read-back verification.
argument-hint	[describe the live survey and the change you need to make]

Qualtrics Live-Survey Operations

Instructions

1. When to use

This skill covers operating a survey already built and imported into Qualtrics — publishing, quotas, flow routing, live text patches, panel-vendor integration, security options — on an instrument that is or will be fielding real respondents. It is not survey design or QSF construction; assume the survey definition already exists and the question is how to change it without breaking what respondents currently see.

2. Non-negotiables

Backups first, always. Pull and save the survey definition (and flow and options as separate JSON) before any write. Qualtrics version restore exists but is coarse and carries data-risk caveats; your pre-change snapshot is the only precise recovery path, and the only one that covers objects (quota counters, options) outside version history.

Verify by read-back, never by absence of error. A 200 response proves the API accepted the request, not that respondents will see the result. After every write, GET the changed object back and confirm it matches intent.

The version list is the proof a change is live, not the publish-state flag. Question/block writes create no version-history entry, so publish-state can report "in sync" while the live version still lags behind your edit. The standard: your publish call created a NEW published version entry carrying your own description — and, because a description proves provenance rather than content, pair it with a read-back of the published content where the API exposes it.

One writer at a time. Confirm you are on the right survey, brand, and environment, that no one has the builder open concurrently, and that you know the rollback path before the first write. On an actively fielding instrument, prefer a change window; and remember the platform's own warning that deleting or restructuring questions and choices can invalidate already-collected data.

Assert everything untouched is unchanged, not just that your target changed — compare parsed structures, since the server may normalize ordering and defaults. Several of the traps below are full-replace endpoints that silently wipe sibling data; catching that requires diffing the whole object against the pre-change backup, not just checking the field you meant to edit.

3. Publish gating — two distinct failure modes

Most flow and options edits to an active survey are staged, not live, until an explicit version publish — respondents keep getting the old version while the API happily reads back your new one. (A few option keys apply immediately, availability among them; treat "staged until published" as the safe default assumption and verify per key.) Question/block writes are worse: they create no list_versions entry at all, so publish-state can say "in sync" immediately after a write that hasn't actually gone anywhere near respondents. Stage all related writes for a change as one batch, verify the batch by read-back, then publish ONCE, deliberately (forcing the publish if your client supports it) — publishing after every individual write can expose respondents to internally inconsistent intermediate versions. Reload the builder UI before trusting its Draft/Published badge — it lags the API.

Publishing an inactive survey activates it. Treat activation as a separate, deliberate decision from publishing a change — have your API client require an explicit activation flag so a routine content publish can never launch fielding as a side effect.

4. Quota API

• START HERE IF A QUOTA COUNTS BUT NEVER BLOCKS: check ActionInfo. QuotaAction: "EndCurrentSurvey" only NAMES the action. The nested ActionInfo object is what actually FIRES it. A quota written with an empty stub —

  "ActionInfo": {"Type": "BooleanExpression"}
  

  — counts every matching respondent flawlessly, forever, and acts on none of them: no termination, no screen-out, no error at write time, at publish time, or at runtime, and the builder UI renders the quota as normal. The platform's own serialization is:

  "ActionInfo": {"0": {"0": {"ActionType": "EndCurrentSurvey",
                              "Type": "Expression",
                              "LogicType": "QuotaAction"},
                        "Type": "If"},
                  "Type": "BooleanExpression"}
  

  ActionType must repeat the QuotaAction value. This was shipped as an empty stub in a homegrown API client and made every quota it ever created inert across multiple live fielding surveys — the true reason quotas "didn't work", after days of chasing logic-dialect theories that were all downstream of it. If a quota's count is incrementing, its matching logic is already correct and the problem is not the logic; go straight to ActionInfo.

• Proven by controlled before/after, and this is the method to reuse. Do NOT try to diagnose quota enforcement on a clone of the real instrument — geo gates, duplicate-device gates, anti-automation paradata and session-resume cookies will each eject or short-circuit the walk, and stripping them piecemeal corrupts the flow (all of this was tried, and burned hours). Instead build a minimal disposable survey from scratch: three quota-bearing questions on page 1, one marker question on page 2 (reaching page 2 is the "not blocked" signal — a single-page survey cannot demonstrate blocking at all, because the respondent has already answered everything by the time the quota evaluates), plus TWO quotas: one the walk matches and one differing in a single condition as a negative control. Walk it once to fill the match quota, then walk again and observe. The control must stay at 0 — that is what proves the multi-condition AND is sound rather than collapsing. Change ONE variable per walk. In the reference case the immediately-preceding walk already had the group's Selected flag, canonical dialect and EndSurveyOptions all in place and still reached page 2; populating ActionInfo alone flipped the identical walk to terminating at page 1.

• Ruled out along the way — do not re-chase these (each was a plausible theory that cost real time): the quota group's flag (setting it to match a working reference changed nothing on its own); the presence or absence of (worth having for the flag, but not what makes a quota fire); and as a way to express "already full" — that IS wrong and no platform-authored quota uses it (minimum observed across 49 reference quotas was 16), but with a broken no limit value of any kind would have blocked anyone. Use when a cell is already over target and you want it shut: the first matching respondent tips it to full and every subsequent one is blocked.

5. Flow mutation and routing placement

• Anchor routing gates on block descriptions, not on a data-capture node. A capture node's position can vary across instruments (some run it pre-consent, some post-), so a gate anchored to "wherever that node sits" can end up before consent on some builds — ethics-relevant if the gate is a termination. Anchor each gate type to a stable semantic point instead: consent-dependent gates immediately after the consent block; paradata-based gates after the point where every field they read is guaranteed to exist; questionnaire-anchored checks right after their own block, never held to end-of-survey (a late termination costs the respondent the whole length of interview for nothing).
• Know which multilingual architecture you have. Qualtrics' native translation layer keeps ONE block structure with per-language text; a branch-per-language build duplicates every block per arm. On the latter, duplicate each gate into every arm with a fresh flow-element ID — one gate does not cover all arms.
• Capture-before-gate order is load-bearing. The node that writes a field must precede every gate that reads it. Get the order wrong and the gate fails safe — no error, no fire, just silently dead — which is far more dangerous than a routing bug that throws.
• When the exit URL is carried in an embedded-data field consumed by the end-of-survey redirect, the node that SETS the field must precede the terminating element inside the gate — the termination ends flow evaluation, so anything ordered after it never executes.
• On paired-language (twin) instruments, never express a failure condition as "the correct option was not selected" — an unanswered field in the respondent's other language arm also satisfies "not selected" and routes out the wrong arm entirely. Express failure as positive selection of a wrong option instead.
• Guard any geolocation-based termination with an explicit "value present and not equal to the excluded value," not just "not equal to." An unresolved lookup (proxy, privacy relay, corporate VPN) must not silently satisfy a bare not-equal check and terminate a legitimate respondent.
• Reserve live termination for signals that cannot belong to a real, eligible respondent: ineligibility, duplicate device/session, a hard machine signature. Anything that is scored or graded on a continuum — a bot-risk score, a fraud score, an attention-check failure, response-speed outliers — belongs in analysis-side exclusion criteria, not a live termination branch, because a live gate can't be revisited once it has turned away a respondent.

6. Live text edits vs. source specs

When a survey is built from versioned source specs (YAML, a survey-builder config, etc.), a live typo or wording fix still often needs to go directly against the live question via a targeted patch — matching exact surrounding text and replacing only the intended span — rather than a full spec rebuild and repush, because a rebuild will clobber any manual formatting or ordering that was applied directly in the live tool since the last build. When syncing the fix back into the source spec afterward, match whitespace-insensitively: prose in structured source formats commonly soft-wraps, so a byte-for-byte diff against live text produces false mismatches.

Keep an explicit list of anything the build pipeline does not emit (e.g. quality-routing branches, vendor-specific disclosures added live) — a rebuild silently drops these, so they must be reapplied by hand after every rebuild and repush.

7. Panel-vendor integration basics

Redirect logic for panel-vendor traffic follows a stable pattern regardless of vendor: a pre-consent screen-out value, a terminal complete value, and an end-of-survey redirect to whichever URL parameter carries the vendor's completion redirect — typically piped from an embedded-data field the vendor's entry link populated. Bracket any quota-bearing block with a quota-full redirect variant so respondents who close out a quota mid-survey get routed to the vendor's quota-full endpoint rather than falling through to a generic completion or termination redirect.

URL query parameters resolve into piped references at session start regardless of where (or whether) the embedded-data declaration sits in the flow — live-verified against redirect pipes. Declare the field anyway: declaration is what makes the value reliably typed, saved, and exported, and downstream logic easier to read.

(Panel vendors vary — a generic panel-vendor redirect endpoint is the concept that matters here, not any particular vendor's API shape.)

Before enabling ANY quota's hard-terminate action (EndCurrentSurvey) on a survey running through a panel vendor, check prior vendor correspondence for an explicit statement of which real-time termination paths are in use. Vendors are sometimes told directly — in an email, not just implied by default config — that a given exit status (a quota-full redirect code, say) is deliberately not used, with real-time termination limited to a named, narrower set of conditions (duplicate device, geo-ineligibility, automation detection). Flipping a quota to hard-terminate is, from inside Qualtrics, a purely internal config change with a green checkmark and no warning — but it silently starts exercising a redirect path the vendor's system was told to expect never to see. This is a compliance question, not a technical one, and the fix isn't a Qualtrics setting: read the actual correspondence (search for the vendor's redirect status codes by name, not just "quota") before assuming a hard quota is safe to activate on a live vendor-sourced field.

8. Security options

Treat the survey's security/options block as read-modify-write: fetch the full current object, change only the target keys, and write the whole object back — then assert every key you did not intend to touch is byte-identical to the pre-change value. Options endpoints are as prone to full-replace semantics as the quota-group endpoint above, and a security setting silently reset to a default (e.g. a fraud-detection threshold, a ballot-box-stuffing prevention flag) is the kind of regression that goes unnoticed until an incident, not at write time.

After any live toggling of quota actions or repeated publishes on a fielding survey, verify no real respondent was actually affected — don't just reason about it. Pull the response export, filter to sessions with StartDate inside the affected window, and check Progress/Finished across all of them. A clean 100/Finished=True for every session is checkable proof nobody was cut off mid-survey by a config change in flight; don't rely on "the targets never should have hit zero" reasoning alone when the actual data is one export call away.

Quality Checks

• Pre-change backup saved (survey definition + flow + options as separate JSON) before any write
• Publish issued after every quota/question/flow write, with activation (allow_activation/equivalent) triggered only at deliberate launch, never as a side effect
• Change verified live via list_versions showing a version with your own description — not via publish-state or the builder UI badge alone
• Full object read back post-write; every untouched key confirmed byte-identical to the backup
• Quota-group and options writes sent as complete objects (full membership / full key set), never partial
• Any quota with more than one condition is diffed byte-for-byte against a real, platform-exported QSF's quota Logic shape (Conjuction spelling, ChoiceTextEntryValue locator) before being trusted — never hand-authored from the "obviously correct" spelling
• Any LogicType: "EmbeddedField" quota condition uses the BARE field name as LeftOperand ("gc"), never the e://Field/ piped form that is correct everywhere else in Qualtrics
• Quota type identified before reading or writing Logic: Simple = one cell, dict-shaped logic, absolute Occurrences; Cross = a grid, array-of-logic-sets, Occurrences is the total and Conjuction holds a percentage share, not And/Or
• Fill verified against a real response export, never against count alone, on any survey that was already fielding before the quota was created or fixed
• Every hard quota's ActionInfo is POPULATED with the nested {"0":{"0":{"ActionType":<same as QuotaAction>,"Type":"Expression", "LogicType":"QuotaAction"},"Type":"If"},"Type":"BooleanExpression"} shape -- an empty {"Type":"BooleanExpression"} stub yields a quota that counts every match and blocks nobody, silently