sales-skills/sales-userintuition

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.