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).
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:
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
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, pollGET /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-SHA256X-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.
