---
name: sales-userintuition
description: "User Intuition (userintuition.ai) platform help — AI-moderated customer research that interviews REAL humans (voice, video, or chat, laddering 5–7 levels deep) from a 4M+ vetted global panel or your own customers, driven by a REST API, HMAC-signed completed-interview webhooks, a CLI, and an MCP server (ask_humans, get_results) for Claude Code, Cursor, and ChatGPT. Use when setting up a study or panel, running a preference/claim/message test from an AI agent, connecting the MCP server or wiring completed-interview webhooks into a CRM or warehouse, choosing panel recruiting vs bring-your-own-participants, picking voice vs chat vs video, authenticating the API (ui_sk_ keys, 429 rate limits), or deciding whether it beats synthetic-persona tools for real customer signal. Do NOT use for comparing research tools across the market or the validate-before-building method (use /sales-idea-validation), or analyzing existing NPS/CSAT/VoC feedback (use /sales-customer-feedback)."
argument-hint: "[describe what you need help with in User Intuition]"
license: MIT
version: 1.0.0
tags: [sales, pre-launch, platform]
---

# User Intuition Platform Help

User Intuition (userintuition.ai) runs **AI-moderated customer research on REAL humans** — a voice,
video, or chat interviewer that adapts and probes 5–7 levels deep (like a senior researcher), run in
parallel across dozens of participants and returned in hours. Recruit from a **4M+ vetted global
panel** or **bring your own customers** (BYOP). Every interview is auto-scored (Length/Depth/Coverage)
and **misses aren't charged**; findings compound in a searchable **Customer Intelligence Hub**.

Its edge in the idea-validation/customer-research cluster is twofold: (1) it interviews **real people,
not synthetic personas** — so it surfaces genuine reasoning, objections, and language, not an LLM's
guess; and (2) it has the **strongest agent-native surface** here — a real REST API, HMAC-signed
webhooks, a CLI, **and** an MCP server (`ask_humans`, `get_results`) so an agent can launch studies and
read results without leaving Claude Code/Cursor/ChatGPT.

**The one caveat to say every time:** an interview is far stronger than synthetic signal, but a stated
"I'd pay for this" is **still not a purchase** — real qualitative depth (the *why*) is not the same as
observed willingness-to-pay. Pair a study with a real behavior test before a go/no-go.

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

Ask only what you can't infer:

1. **What do you want from User Intuition?**
   - A) **Set up a study** — write the objective/conversation-flow/screener, pick voice vs chat vs video
   - B) **Recruit** — from the panel (with demographic targeting) vs bring-your-own-participants (BYOP)
   - C) **Automate** — drive it from the MCP server (Claude Code/Cursor/ChatGPT) or the REST API/CLI
   - D) **Wire up data** — completed-interview webhooks or polling into a CRM / data warehouse / Slack
   - E) **Interpret** a report/Intelligence Hub result, or decide **whether to trust it** for a decision
2. **What's the research question, and panel or your own customers?** A sharp objective + the right
   audience yields depth; a vague one yields shallow filler.

Skip-ahead: if the user wants to **compare** research/idea tools across the market, or the
validate-before-building *method*, that's a `/sales-idea-validation` question — route in Step 2.

## Step 2 — Route or answer directly

| If the user's question is about… | Route to |
|---|---|
| Comparing research/idea/synthetic tools, or the validate-before-building **method** | `/sales-idea-validation {question}` |
| Running a **real behavior** demand test (smoke-test page, waitlist, pre-sale) after interviews | `/sales-idea-validation` or `/sales-funnel` `{question}` |
| Analyzing **existing** NPS/CSAT/VoC/review feedback (post-launch, not new interviews) | `/sales-customer-feedback {question}` |
| A **synthetic-persona** peer (AI personas instead of real people) | `/sales-syntheticusers` or `/sales-ditto` `{question}` |

When routing, give the exact command: "This is a {domain} question — run: `/sales-idea-validation {original question}`"

Otherwise, answer User-Intuition-specific questions using Step 3.

## Step 3 — User Intuition platform reference

**Read `references/platform-guide.md`** for the full reference — the module/automation-surface table
(what's API-accessible, webhook-accessible, or UI-only), best-effort pricing and plan gates, the
Study → Interview → Participant → Report data model (JSON shapes), integrations, and quick-start recipes.

For raw endpoints, auth, JSON schemas, webhook verification, the MCP tools, and an end-to-end script,
read `references/userintuition-api-reference.md`.

Answer using only the relevant section — don't dump the full reference.

## Step 4 — Actionable guidance

- **Say the caveat: real interview ≠ a purchase.** Whatever the user asks, make explicit that User
  Intuition interviews **real humans** (a big step up from synthetic personas — genuine reasoning,
  objections, language), but a stated "I'd pay" in an interview is **not observed demand**. Keep the
  *why/objections/language* (its real value) and take the go/no-go from a **real behavior test**
  (smoke-test click, pre-sale) — route that to `/sales-idea-validation`.
- **Estimate cost with a dry run before spending.** Tell the user to always dry-run first: via the MCP
  `ask_humans` tool set `dry_run: true`, or via REST `POST /api/public/v1/studies/create-and-launch-panel`
  set `panel.dry_run: true` — it returns `estimated_total_cost_usd` and `estimated_timeline_hours` with
  **no credits spent**. Note **quality-only billing**: interviews that fail the auto-score aren't charged.
- **For agent automation, prefer the MCP server; for pipelines, the REST API.** MCP: server
  `https://mcp.userintuition.ai/mcp` (Streamable HTTP, OAuth on first use), tools `ask_humans`
  (modes `preference_check` / `claim_reaction` / `message_test`, params `stimuli`, `audience`,
  `sample_size` [default 25], `dry_run`), `get_results`, `list_studies`, `edit_study`, `cancel_study`.
  REST: base `https://api.userintuition.ai`, `Authorization: Bearer ui_sk_...` (org-scoped keys, shown
  **once**); core flow is create-and-launch-panel → poll List Interviews / `get_study` → generate/get report.
  **Results aren't instant** — an agent launches with `ask_humans`, then retrieves later with `get_results`
  by `study_id` (~2–3h typical turnaround), not in the same call.
- **Wire completed interviews via webhooks — but design for no retries.** The webhook fires **once per
  interview** (including **Stripe-triggered churn/cancellation interviews**) with an
  `interview.completed`-style payload (transcript `messages`, quality, recordings).
  Verify the **HMAC-SHA256** signature (`X-UI-Signature` over `"<timestamp>.<body>"` with the `whsec_`
  secret; reject timestamps outside 5 min). There are **NO automatic retries** and a **30s timeout** —
  return `2xx` fast and defer heavy work to a background job. If you can't hold a public endpoint, **poll**
  `GET /api/public/v1/interviews` instead. Registration is **account-wide** (covers all studies).
- **Panel vs BYOP: match to the question.** Panel recruiting (demographic targeting via
  `targeting_attributes`, ~$30 flat panel incentive/participant) reaches strangers for discovery/concept
  tests; **BYOP** (share link / embed widget / Stripe-triggered) interviews *your own* customers for
  churn/win-loss and is the honest audience for product feedback — but you handle incentives.
- **Present all pricing as best-effort.** Tiers and per-interview rates change — state figures are
  best-effort and point the user to **userintuition.ai/pricing** and **docs.userintuition.ai** to confirm.

If you discover a gotcha or tip not in `references/learnings.md`, append it there with today's date.

## Gotchas

*Best-effort from research (2026-07) — pricing, panel size, the API/MCP surface, and integration status
(HubSpot/Shopify were "coming soon") move; verify at userintuition.ai and docs.userintuition.ai.*

- **Real ≠ demand.** Interviews reveal the *why* better than any synthetic tool, but a stated intent to
  pay is not a purchase — the go/no-go still belongs to a real behavior test (pre-sale, smoke test).
- **Webhooks have no retries and a 30s timeout.** A non-2xx or slow endpoint just gets logged, not
  redelivered — respond 2xx immediately, process async, and reconcile by polling List Interviews.
- **API key is shown once.** The `ui_sk_` key (and the `whsec_` webhook secret) display a single time —
  store them immediately; there's no re-reveal.
- **Quality-only billing cuts both ways.** You only pay for interviews clearing the Length/Depth/Coverage
  bar (failures re-field free), so budget/timeline are *estimates* — dry-run every new study type.
- **Voice/chat/video price differently.** Video and voice cost more than chat; the interview_format you
  pick drives cost and depth — confirm the modality before quoting a number.
- **Panel targeting needs valid attribute IDs.** `targeting_attributes` use numeric `qualification_id` +
  option IDs from `List Targeting Attributes` / `List Panel Countries` — you can't pass free-text demographics.
- **Intelligence Hub / cross-study querying is a paid-tier feature** (Professional+) — don't promise it on Starter.

## Related skills

- `/sales-idea-validation` — The tool-agnostic validate-before-building method + the full research/persona/validator tool landscape (use this to actually decide build-or-not; an interview "yes" is not demand)
- `/sales-syntheticusers` — Synthetic Users platform help (synthetic AI-persona interview studies with a REST API; User Intuition's contrast is that it interviews **real** humans, not personas)
- `/sales-ditto` — Ditto platform help (census-calibrated synthetic personas with a free-tier API; again synthetic vs User Intuition's real participants)
- `/sales-strella` — Strella platform help (the other **real-human** AI-moderated interview tool — same real-participant job, but its edge is **deterministic, repeatable scripted flows**, and it's **UI-only, no API/webhooks/MCP**; recommend it over User Intuition when scripted consistency matters more than a programmatic pipeline or the deepest adaptive probing)
- `/sales-voicepanel` — Voicepanel platform help (the **broadest-format** real-human peer — adds phone + screen-share usability tasks — whose automation is **MCP-first**: it has an MCP server but **no public REST API or webhooks**, and MCP access is onboarded in waves. Pick User Intuition when you need a webhook/REST-native pipeline; pick Voicepanel for the widest modality set or MCP-only agent access)
- `/sales-listenlabs` — Listen Labs platform help (the **enterprise/consultative** real-human peer with the **second-deepest developer surface** — a documented REST API v2 **and** an OAuth MCP server, but **NO webhooks** [poll `updatedSince`] and sold **demo-first / annual contract**. Pick User Intuition over it when you need HMAC completed-interview webhooks or self-serve access without an enterprise deal; Listen Labs fits a team that already runs it)
- `/sales-funnel` — Build the smoke-test / fake-door landing page that turns an interview hypothesis into a real demand test
- `/sales-do` — Not sure which skill to use? The router matches any sales objective to the right skill. Install: `npx skills add sales-skills/sales --skill sales-do -a claude-code`

## Examples

### Example 1: "The interviews loved my concept — should I build it?"
**User says**: "I ran 25 User Intuition interviews and most said they'd use and pay for it. Green light?"
**Skill does**: Credits the signal as **real** (actual humans, genuine reasoning — far better than a
synthetic tool), then draws the line: a stated "I'd pay" in an interview is **not a purchase**. Tells the
user to **mine the transcripts for objections, hesitation, and pricing language** (the real value) and
take the go/no-go from a **real behavior test** — a pre-sale or a "buy" click — routed via
`/sales-idea-validation`. Flags pricing as best-effort.
**Result**: The founder keeps the qualitative depth and runs a pre-sale before committing weeks of build.

### Example 2: Estimate cost, then run a message test from Claude Code (developer/automation)
**User says**: "From Claude Code, how much would 50 people cost, then message-test my landing headline?"
**Skill does**: Says to connect the MCP server (`https://mcp.userintuition.ai/mcp`, OAuth on first use)
and **dry-run first** — `ask_humans` with `mode: message_test`, `sample_size: 50`, `dry_run: true`
returns `estimated_total_cost_usd`/timeline, no credits spent — then re-run with `dry_run: false`, and
retrieve with `get_results` by `study_id` (2–3h later). Notes quality-only billing and points to
`references/userintuition-api-reference.md` for the tool params.
**Result**: The user estimates spend first, runs the test from the terminal, and reads results in place.

### Example 3: Pipe completed churn interviews into the CRM
**User says**: "When a customer cancels, I want the cancellation interview transcript in HubSpot."
**Skill does**: Describes the flow — the **Stripe integration** triggers a BYOP churn interview on
cancellation; register an **account-wide webhook** (`POST /api/public/v1/webhooks`), verify the
**HMAC-SHA256** `X-UI-Signature` with the `whsec_` secret, and on the completed-interview payload map
`messages`/`quality`/`audio_recording_url` onto the contact. Stresses **no retries + 30s timeout**
(return 2xx fast, process async) and polling `GET /interviews` to reconcile misses.
**Result**: Cancellation transcripts land on the HubSpot contact, resilient to the no-retry webhook design.

## Troubleshooting

### "My webhook endpoint isn't getting completed interviews"
**Symptom**: Studies finish but the CRM/warehouse never receives the payload.
**Cause**: The endpoint returned non-2xx or timed out (**30s limit**), and User Intuition does **no
automatic retries** — the delivery is only logged. Or the signature check is rejecting valid calls.
**Solution**: Return `2xx` immediately and defer processing to a background job. Verify HMAC-SHA256 over
`"<X-UI-Timestamp>.<raw body>"` with the `whsec_` secret (constant-time compare, 5-min window). Backfill
missed interviews by polling `GET /api/public/v1/interviews`. See `references/userintuition-api-reference.md`.

### "My panel study cost/timeline came back different than expected"
**Symptom**: The estimate and the final charge don't match, or fewer interviews than requested.
**Cause**: **Quality-only billing** — interviews failing the Length/Depth/Coverage auto-score aren't
charged and get **re-fielded free**, so totals are estimates; and voice/video cost more than chat.
**Solution**: Always **dry-run** a new study type (`panel.dry_run: true` or `ask_humans dry_run: true`) to
read `estimated_total_cost_usd`/`estimated_timeline_hours`, confirm the `interview_format`, and treat the
number as a ceiling that quality-billing can lower.

### "The results feel generic / didn't go deep"
**Symptom**: Transcripts are shallow or off-topic despite real participants.
**Cause**: A vague `study_plan.objectives`/`conversation_flow`, a weak screener, or the wrong audience —
the AI moderator probes around *your* brief, so a thin brief caps the depth.
**Solution**: Write a sharp objective + conversation flow + disqualifying screener questions, target the
right panel (`targeting_attributes`) or use BYOP for your real customers, and interpret via the Intelligence
Hub. Then take the go/no-go to a real behavior test via `/sales-idea-validation`.