---
name: sales-syntheticusers
description: "Synthetic Users (syntheticusers.com) platform help — run AI-moderated research studies (problem-exploration and concept-testing interviews) against synthetic participants instead of recruiting real people, grounded in your own data via RAG, with insights reports, saturation scoring, and a full REST API (Bearer auth, Python + TypeScript SDKs, SSE streaming, PDF export). Use when setting up a Synthetic Users study or audience, interpreting a synthetic interview report, grounding participants in your own customer data, pulling study transcripts or summaries via the API, wiring the create-study to interview to summary flow into a pipeline, or judging whether a synthetic 'yes' is real demand. Do NOT use for comparing idea-validation or persona tools across the market (use /sales-idea-validation) or analyzing real-customer NPS/VoC feedback (use /sales-customer-feedback)."
argument-hint: "[describe what you need help with in Synthetic Users]"
license: MIT
version: 1.0.0
tags: [sales, pre-launch, platform]
github: "https://github.com/SyntheticUsers"
---

# Synthetic Users Platform Help

Synthetic Users (syntheticusers.com) is an **AI synthetic user-research platform**: you define an
**audience**, write a topic guide, and run **interviews** against AI **synthetic participants** —
multi-agent personas with stable OCEAN personality profiles — instead of recruiting real respondents.
Three interview types: **problem exploration**, **concept testing**, and **custom script**. You can
**ground studies in your own data via RAG** (customer interviews, support tickets, segment
definitions), and it returns an **insights report** (themes, executive summary, verbatim quotes) with
**saturation scoring** to tell you when you've heard enough. Unusually for this cluster it ships a
**full REST API** (Bearer auth, Python + TypeScript SDKs, SSE streaming, PDF export).

Its signal is **directional, not demand**: synthetic participants model existing/public/training data,
so they skew **agreeable, generic, and Western-biased** and cannot surface a genuinely *new* unmet
need. Treat any synthetic result as a **hypothesis to disconfirm with real behavior**, not a green
light.

## 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 Synthetic Users?**
   - A) Set up a **study** — pick an interview type (problem exploration / concept testing / custom script)
   - B) Define or generate an **audience** of synthetic participants
   - C) **Ground** a study in your own data (RAG upload) for more specific answers
   - D) **Interpret** an insights report / transcripts / saturation score you already ran
   - E) **Automate** it — pull studies/summaries/transcripts via the API, or wire the flow into a pipeline
   - F) Decide **whether to trust it** — is this a valid stand-in for real research?
2. **What's the research question and who's the audience?** A sharp audience + topic guide yields a
   usable result; a vague one yields generic filler.

Skip-ahead: if the user wants to **compare** synthetic-research/persona/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 synthetic-research/persona/idea tools, or the validate-before-building **method** | `/sales-idea-validation {question}` |
| Running a **real** demand test (smoke-test page, waitlist, pre-sale) after synthetic signal | `/sales-idea-validation` or `/sales-funnel` `{question}` |
| Analyzing **real-customer** NPS/CSAT/VoC feedback (post-launch) | `/sales-customer-feedback {question}` |
| A **data-grounded persona you chat with** (from your CRM/GA4), not a full study | `/sales-delve` or `/sales-marketing-mary` `{question}` |

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

Otherwise, answer Synthetic Users-specific questions using Step 3.

## Step 3 — Synthetic Users platform reference

**Read `references/platform-guide.md`** for the full reference — the three interview types, audience &
RAG grounding, the study → interview → summary → knowledge-graph → PDF workflow, the API/webhook/UI-only
tag on each module, best-effort usage-based pricing and trial, the integration/automation surface, the
data model (Study/Audience/SyntheticUser/Conversation JSON shapes), and quick-start recipes.

For raw endpoints, auth, and JSON schemas, read `references/syntheticusers-api-reference.md`.

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

## Step 4 — Actionable guidance

- **A synthetic "yes" is not demand — say so every time.** Whatever the user asks, make explicit that
  synthetic participants model existing/public/training data, so they run **agreeable, generic, and
  Western-biased** and can be **confidently wrong**. Frame every result as a **hypothesis to disconfirm
  with a real behavior test** (smoke-test click, reply, pre-sale) — keep the *objections, angles, and
  language* it surfaces (its real value), take the go/no-go from real strangers, and route the real test
  to `/sales-idea-validation`.
- **Use it for what it's genuinely good at.** Fast, cheap **pre-testing** of messaging/concepts/objections
  and **directional** pre-launch signal, filling a persona hypothesis, or coverage when a real panel is
  slow — **not** discovering a *new* unmet need and **not** a standalone validity verdict (surveys of
  researchers put standalone trust in the low single digits).
- **Ground it in your own data (RAG) and sharpen the audience — output tracks input.** A vague audience or
  topic guide yields generic filler ("garbage in, garbage out"). Tell the user to **upload real data**
  (interviews, tickets, segment defs) and write a **specific audience + topic guide**; note grounding is a
  paid/RAG add-on to the interview cost.
- **Read saturation, don't chase volume.** ~10–12 participants typically reach **saturation** (no new
  themes); more interviews mostly repeat. Point to the **saturation score**, not raw interview count, and
  treat the **verbatim quotes** as leads to test, not facts.
- **Present pricing as best-effort and point to the live page.** It's **usage-based** (~$2–60 per
  interview, +RAG), with a 7-day trial and API/deeper integration on higher tiers — say figures are
  best-effort and confirm at syntheticusers.com/pricing before relying on them.
- **For automation, use the real API.** Auth is **`Authorization: Bearer <API_KEY>`**, base URL
  **`https://api.syntheticusers.com/api/v1`**; pagination is **`page` + `size`** (size max 100). The core
  flow is `POST /studies` → `POST /studies/{id}/interview` → `POST /studies/{id}/summary` →
  `GET /studies/{id}/pdf`; there are **no webhooks** — poll study `status` or subscribe to
  `GET /projects/{id}/stream` (SSE). Give a concrete cURL/Python snippet from
  `references/platform-guide.md`.

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) — usage-based pricing, trial terms, RAG costs, and API surface move;
verify at syntheticusers.com and docs.syntheticusers.com.*

- **Sycophancy / agreeableness bias.** Synthetic participants tend to *please* — they give shallow,
  overly favorable feedback and can approve a concept real users would reject. Never read a positive
  synthetic reaction as validation.
- **It can't surface a NEW unmet need.** It models existing/public data, so it's strongest at
  *pre-testing a hypothesis you already have* and weakest at discovery. Don't use it to "find the problem."
- **Western/geographic and identity bias.** Outputs skew toward Western, majority perspectives and can
  flatten identity groups — be cautious generalizing across markets/segments.
- **Garbage in, garbage out.** A thin audience definition or no RAG data yields generic filler. Ground
  the study and write a specific topic guide before trusting any theme.
- **No webhooks.** The API has **no webhook callbacks** — long-running studies are tracked by **polling
  `status`** or the **SSE `/projects/{id}/stream`** endpoint, not push notifications.
- **PDF/report is a heavy endpoint.** `GET /studies/{id}/pdf` generates on demand (can 500 on error) and
  returns binary — handle non-200s and stream to file.

## Related skills

- `/sales-idea-validation` — The tool-agnostic validate-before-building method + the full synthetic-research/persona/validator tool landscape (use this to actually decide build-or-not; a synthetic "yes" is not demand)
- `/sales-imario` — iMario platform help (the closest peer — a synthetic-research **canvas** whose unit is a **reusable Synthetic Individual** with cross-session memory, run across six jobs [research, concept validation, sales rehearsal, content testing, journey design, AI-agent personality]; trades Synthetic Users' documented public REST API for reusable-persona breadth — its API is Pro-gated and undocumented)
- `/sales-ditto` — Ditto platform help (the other synthetic-research tool with a real public REST API — recruits **census-calibrated demographic panels** [country/state/age] and ships a **free-tier key** + official Claude Code skills; Synthetic Users' edge is documented Python/TS SDKs + SSE streaming + RAG grounding, Ditto's is demographic calibration + a free API on-ramp)
- `/sales-delve` — Delve AI platform help (data-grounded personas + Digital Twins + Synthetic Research built from your real GA4/CRM/social data — the persona-you-chat-with counterpart; has a paid, gated API)
- `/sales-marketing-mary` — Marketing Mary platform help (interactive buyer personas you converse with, grounded in real CRM/GA4 data; UI-only, no public API)
- `/sales-customer-feedback` — Real-customer NPS/CSAT/VoC strategy across tools (use once you have live customers; synthetic research is pre-launch only)
- `/sales-funnel` — Build the smoke-test / fake-door landing page that turns a synthetic 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 synthetic interviews loved my idea — should I build it?"
**User says**: "I ran a concept test on Synthetic Users and 9 of 10 synthetic participants said they'd use it. Green light?"
**Skill does**: Explains synthetic participants **model existing/training data and skew agreeable**, so a
near-unanimous "yes" is a **directional signal, not demand** — it can approve a concept real strangers
ignore. Tells the user to **mine the transcripts for objections and language** (the real value) and take
the go/no-go from a **real behavior test** — a smoke-test click or pre-sale — routed via
`/sales-idea-validation`. Notes ~10 participants likely hit **saturation**, so more interviews won't add
signal.
**Result**: The founder keeps the angles, runs a real fake-door test before writing code.

### Example 2: Grounding a study in real data for a specific audience (references/platform-guide.md)
**User says**: "How do I make Synthetic Users give answers specific to *my* B2B ops buyers, not generic fluff?"
**Skill does**: Says output **tracks input** — define a **sharp audience** (role, context, psychographics)
and **upload real data via RAG** (past interviews, support tickets, segment defs) so participants are
grounded, noting RAG is a **paid add-on** on top of the per-interview cost. Explains the **problem
-exploration vs concept-testing vs custom-script** choice and to write a focused topic guide. Frames each
theme as a hypothesis to confirm with real users.
**Result**: A grounded study with specific, testable themes instead of generic filler.

### Example 3: Pulling study summaries into a data pipeline via the API (developer/automation)
**User says**: "I want to run a study and push the summary + transcripts into our warehouse automatically. What's the API?"
**Skill does**: Gives the flow — auth `Authorization: Bearer <API_KEY>`, base
`https://api.syntheticusers.com/api/v1`; `POST /studies` → `POST /studies/{id}/interview` →
`POST /studies/{id}/summary` → `GET /studies/{id}` (read `status`/transcripts) → `GET /studies/{id}/pdf`.
Notes **no webhooks** — poll `status` or subscribe to `GET /projects/{id}/stream` (SSE) — and pagination
is `page` + `size` (max 100). Points to the **Python/TypeScript SDKs** and a cURL/Python snippet in
`references/platform-guide.md`.
**Result**: The user wires the create → interview → summarize → export flow with polling, no webhook dependency.

## Troubleshooting

### "The synthetic participants agreed with everything — is that real?"
**Symptom**: Interviews return uniformly positive, agreeable feedback that feels too good.
**Cause**: LLM-based participants exhibit **sycophancy** — they model plausible agreement and skew favorable.
**Solution**: Discard the "verdict," keep the **objections and language** surfaced, and validate the
concept with **real behavior** (smoke test, pre-sale). Ground the study in real data and sharpen the
audience to reduce generic agreement. Cross-check via `/sales-idea-validation`.

### Results feel generic / could describe anyone
**Symptom**: Themes are vague and not specific to your product or buyer.
**Cause**: Thin audience definition and **no RAG grounding** — "garbage in, garbage out."
**Solution**: Write a **specific audience + topic guide** and **upload your own data** (interviews,
tickets, segment defs) via RAG so participants are grounded; note RAG adds cost. Re-run with a focused
concept.

### "My long study never 'finishes' — how do I know when it's done via the API?"
**Symptom**: After `POST /studies/{id}/interview`, the study stays processing and there's no callback.
**Cause**: The API has **no webhooks**; long-running studies complete asynchronously.
**Solution**: **Poll** `GET /studies/{id}` and read `status`, or subscribe to the SSE stream at
`GET /projects/{id}/stream` for model events. Use `page`/`size` pagination on list endpoints. See
`references/syntheticusers-api-reference.md`.