---
name: sales-listenlabs
description: "Listen Labs (listenlabs.ai) platform help — AI-moderated qualitative research that interviews REAL people (voice/video/audio/text) at scale, with a full public REST API v2 (create study, launch, self-recruit link, pull responses/transcripts), an official OAuth MCP server for Claude/Cursor/ChatGPT, Emotional Intelligence (Ekman) analysis, Quality Guard fraud detection, and a 30M+ panel or bring-your-own participants. Use when setting up a Listen Labs study or discussion guide, launching a study from code, pulling interview responses into a CRM or warehouse (poll updatedSince — no webhooks), wiring the MCP server into Claude Code, choosing panel vs self-recruit participants, authenticating the API (x-api-key), reading its enterprise/demo-first pricing, or migrating off the deprecated unversioned response endpoints. Do NOT use for comparing AI-interview/research tools 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 Listen Labs]"
license: MIT
version: 1.0.0
tags: [sales, pre-launch, platform]
github: "https://github.com/listenlabs"
---

# Listen Labs Platform Help

Listen Labs (listenlabs.ai) runs **AI-moderated qualitative research on REAL people** — a voice, video,
audio, or text interviewer that asks personalized, adaptive follow-ups and runs stimulus/concept tests at
scale, synthesizing themes, personas, Emotional Intelligence, and executive reports. Recruit from a **30M+
global panel** or **bring your own participants** via a **self-recruit link**.

Its edge in the real-human AI-moderated-interview cluster (User Intuition, Strella, Voicepanel, Outset,
Conveo) is twofold: (1) it interviews **real people, not synthetic personas**; and (2) it ships **both a
full public REST API v2** (create study → launch → self-recruit link → pull responses/transcripts) **and an
official OAuth MCP server** — the most complete API+MCP surface after User Intuition. The catch: it's sold
**demo-first / annual contract** (enterprise-priced), and there are **NO webhooks** — data-out is poll-only.

**The one caveat to say every time:** a real interview is far stronger than a synthetic "yes", but a stated
"I'd pay for this" is **still not a purchase** — keep the *why* (objections, language, reasoning) and take
the willingness-to-pay go/no-go from a **real behavior test** (pre-sale, smoke test).

## 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 Listen Labs?**
   - A) **Set up a study** — write the study guide (screener + interview + concept blocks), pick
     voice/video/audio/text mode
   - B) **Recruit** — the 30M+ panel (wallet-billed) vs a **self-recruit link** for your own participants (BYOP)
   - C) **Automate** — drive it from the **MCP server** (Claude/Cursor/ChatGPT) or the **REST API v2**
   - D) **Wire up data** — pull responses/transcripts into a CRM / warehouse / Slack (**poll `updatedSince`**)
   - E) **Interpret** a report / Emotional Intelligence / personas, or decide **whether to trust it** for a decision
2. **Panel or your own participants, and what's the research question?** A sharp `studyGoal` + the right
   audience yields depth; a vague one yields shallow filler.

Skip-ahead: if the user wants to **compare** AI-interview/research 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 AI-interview/research/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 peer that needs **HMAC webhooks / self-serve REST pipeline** | `/sales-userintuition {question}` |

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

Otherwise, answer Listen-Labs-specific questions using Step 3.

## Step 3 — Listen Labs platform reference

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

For raw endpoints, auth, the study-guide OpenAPI schema, the response/transcript shapes, the MCP setup, and
an end-to-end poll script, read `references/listenlabs-api-reference.md`.

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

## Step 4 — Actionable guidance

- **Say the caveat: a real interview ≠ a purchase.** Whatever the user asks, make explicit that Listen Labs
  interviews **real humans** (a 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* — **mine the transcripts
  for objections, hesitation, and pricing language** — and take the go/no-go from a **real behavior test**
  (pre-sale, smoke-test click) — route that to `/sales-idea-validation`.
- **There are NO webhooks — design data-out as a poll.** To pipe completed interviews into a CRM/warehouse,
  poll `GET /api/public/v1/responses/{linkId}` with **`updatedSince` (ISO 8601)** and keep an `updatedAt`
  cursor; set `includeInProgress=false` for completed-only; drill into a transcript with
  `GET /responses/{linkId}/{responseId}`. Never tell the user to "register a webhook" — Listen Labs doesn't
  have them (unlike User Intuition / Great Question).
- **The create → launch flow is three requests.** `POST /api/public/v1/studies/create` (validates the guide,
  returns a draft `id` + `linkId`) → `GET /api/public/v1/wallets` (pick one; omit `walletId` only if the org
  has exactly one) → `POST /api/public/v1/studies/{studyId}/launch` (returns `selfRecruitLink`). Auth is the
  **`x-api-key`** header, org-scoped, created from the account **Developer** section.
- **Branch on `code`, not `error`.** Validation failures return a stable `code` (`invalid_request_body` with
  an `issues[]` array, or `invalid_study_guide` for a cross-field rule); the human-readable `error` text may
  change. Retry `409 concurrent_modification` / `409 study_busy` after a short delay.
- **For agent automation, use the MCP server.** `https://listenlabs.ai/mcp` (OAuth on first use; access
  token ~1h auto-refreshed, refresh ~30d; role-scoped, "acts as you"). It creates/edits/launches studies,
  searches studies/themes, and fetches AI analysis reports as markdown — but you still need an active org.
- **Present pricing as best-effort and enterprise/demo-first.** Listen Labs **doesn't publish pricing**;
  buying is a **sales conversation** (scoping, screener review, procurement — ~2–4 weeks), best-effort
  ~$20K annual base + $300–400/session. State figures as best-effort and point to a Listen Labs demo — it
  is **not** a self-serve solopreneur tool. Prefer a **self-recruit link with your own participants** to
  avoid panel per-session cost.
- **Migrate off deprecated endpoints.** The unversioned `/api/public/responses/...` paths are **removed
  2026-08-01** — always use `/api/public/v1/responses/...`.

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 native integrations
move; verify at listenlabs.ai and docs.listenlabs.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).
- **No webhooks — poll `updatedSince`.** Unlike User Intuition/Great Question, Listen Labs has no push
  channel; reconcile new/updated interviews by polling `GET /responses/{linkId}?updatedSince=<ISO8601>`.
- **Unversioned response endpoints die 2026-08-01.** Build on `/api/public/v1/responses/...`, not the old
  `/api/public/responses/...` paths.
- **Enterprise/demo-first — no self-serve.** No published pricing, no public free trial; onboarding is a
  sales/scoping process (~2–4 weeks). API keys require an active org (Developer section, Admin/Supervisor).
- **Study-guide validation is server-side and cross-field.** The screening block must be **first** and hold
  only `multiple_choice` items with a `status` on every option; `externalId`s must be unique; conditionals
  must reference an **earlier** item's `externalId`. A broken rule → `400 invalid_study_guide`.
- **Wallet required with multiple wallets.** Omit `walletId` at launch only when the org has exactly one;
  otherwise `400 wallet_required`. `400 insufficient_credits` = the wallet can't fund the launch.
- **Emotional Intelligence / Quality Guard are report/fielding-layer, UI-first.** The API exposes a
  `qualityScore` per response, but the Ekman emotion analysis and fraud-prevention tuning live in the UI.

## Related skills

- `/sales-idea-validation` — The tool-agnostic validate-before-building method + the full research/persona/interview tool landscape (use this to actually decide build-or-not; an interview "yes" is not demand)
- `/sales-userintuition` — User Intuition platform help (the peer with the **deepest developer surface** — a self-serve REST API, **HMAC-signed completed-interview webhooks**, a CLI, and an MCP server; recommend it over Listen Labs when you need a **webhook-native pipeline** or self-serve access without an enterprise contract)
- `/sales-strella` — Strella platform help (the **deterministic-scripted-flow** real-human peer — **UI-only, no API/webhooks/MCP**; pick it when scripted repeatability matters more than a programmatic pipeline)
- `/sales-voicepanel` — Voicepanel platform help (the **broadest-format, MCP-first** real-human peer — voice/video/chat/phone + screen-share usability tasks; an MCP server but **no REST API or webhooks**, access onboarded in waves)
- `/sales-great-question` — Great Question platform help (the **all-in-one research-ops suite** — recruit + run any method + repository, with a REST API + HMAC webhooks + MCP all at once)
- `/sales-customer-feedback` — Analyze existing NPS/CSAT/VoC/review feedback post-launch (vs Listen Labs, which *runs new interviews* with real people)
- `/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 30 Listen Labs interviews and most said they'd use and pay for it. Green light?"
**Skill does**: Credits the signal as **real** (actual humans, genuine reasoning — 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 to read the
Emotional Intelligence signal for where enthusiasm was hollow) 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: Pipe completed interviews into HubSpot (developer/automation)
**User says**: "When an interview finishes, I want the transcript and summary in HubSpot. How do I set up the webhook?"
**Skill does**: Corrects the premise — **Listen Labs has no webhooks** — and gives the poll pattern instead:
poll `GET /api/public/v1/responses/{linkId}` with **`updatedSince`** (ISO 8601) and `includeInProgress=false`,
keep an `updatedAt` cursor, and for each `progress: "complete"` row fetch
`GET /responses/{linkId}/{responseId}` for the full `transcript`, mapping `bulletSummary`/`tags`/`qualityScore`
onto the contact. Auth is the `x-api-key` header. Points to `references/listenlabs-api-reference.md` for the
Python poll loop.
**Result**: Completed transcripts land on the HubSpot contact via a resilient poll, not a webhook that doesn't exist.

### Example 3: Create and launch a study from code
**User says**: "How do I create and launch a study from the API and get a link to send my own users?"
**Skill does**: Describes the three requests — `POST /api/public/v1/studies/create` with a study guide
(screener block first, interview block; validated up front → draft `id` + `linkId`), `GET /wallets` to pick
one (omit `walletId` only if the org has exactly one), then `POST /studies/{studyId}/launch` → `selfRecruitLink`.
Notes **branch on `code` not `error`** for validation failures, and that a **self-recruit link with your own
users avoids panel per-session cost**. Points to the OpenAPI study-guide schema in the API reference.
**Result**: The user fields a study programmatically and distributes the self-recruit link to their own audience.

## Troubleshooting

### "My webhook endpoint never receives completed interviews"
**Symptom**: You set up a listener expecting Listen Labs to POST completed interviews, and nothing arrives.
**Cause**: **Listen Labs has no webhooks.** There is no push channel at all (this differs from User
Intuition and Great Question, which do sign completed-interview webhooks).
**Solution**: Poll `GET /api/public/v1/responses/{linkId}` with **`updatedSince`** (ISO 8601) on an interval
matched to fielding speed (interviews trickle in over hours), keep an `updatedAt` cursor, set
`includeInProgress=false` for completed-only, and drill into `GET /responses/{linkId}/{responseId}` for the
transcript. See the Python loop in `references/listenlabs-api-reference.md`. If you need a webhook-native
pipeline, route to `/sales-userintuition`.

### "My study create call returns a 400"
**Symptom**: `POST /api/public/v1/studies/create` fails with a `400`.
**Cause**: Either the body failed schema validation (`code: invalid_request_body`, with an `issues[]` array
naming the field), or the study guide broke a cross-field rule (`code: invalid_study_guide`) — most often the
screening block isn't first / has a non-`multiple_choice` item / an option is missing `status`, a duplicate
`externalId`, or a conditional referencing an item that isn't earlier.
**Solution**: **Branch on `code`, not the `error` text.** Read `issues[].path` for field errors; for
`invalid_study_guide`, put the screening block first with only `multiple_choice` items (every option carries
`approve`/`reject`/`neutral`), make `externalId`s unique, and ensure conditionals reference an earlier item.

### "Launch fails asking for a wallet, or says insufficient credits"
**Symptom**: `POST /studies/{studyId}/launch` returns `400 wallet_required` or `400 insufficient_credits`.
**Cause**: Your org has **multiple wallets** and you omitted `walletId` (it auto-selects only when there's
exactly one), or the chosen wallet's `projectCreditBalance`/`recruitmentCreditBalance` can't fund the launch.
**Solution**: Call `GET /api/public/v1/wallets`, pick a `walletId` with enough balance (remember `usage`
includes active holds), and pass it in the launch body. Top up recruitment/project credits before launching a
panel study; a **self-recruit link with your own participants** avoids panel recruitment cost.