| name | ditto-voc-programme |
| description | Build and run an always-on Voice of Customer programme using Ditto's synthetic persona platform (300K+ AI personas, 92% overlap with real focus groups). Covers monthly pulse checks, quarterly deep dives, ad-hoc probes, and longitudinal trend tracking. Produces 6 VoC deliverables: customer journey map, pain priority matrix, language library, unmet needs report, decision criteria hierarchy, and product feedback synthesis. Designed for CS managers, VoC programme managers, CX/UX researchers, and product managers running continuous feedback loops. Use when the user mentions voice of customer, VoC, customer feedback programme, pulse check, customer journey map, NPS deep dive, churn analysis, or continuous customer research.
|
| allowed-tools | Bash(curl *), Bash(python3 *), Read, Grep, WebFetch |
| argument-hint | [product, problem space, or pulse check brief] |
Ditto for Voice of Customer Programmes
Build a continuous VoC research programme — monthly pulse checks, quarterly
deep dives, longitudinal trend tracking — using Ditto's 300,000+ synthetic
personas. Directly from the terminal.
Full documentation: https://askditto.io/claude-code-guide
What Ditto Does
Ditto maintains 300,000+ AI-powered synthetic personas calibrated to census
data across USA, UK, Germany, and Canada. You ask them open-ended questions
and get qualitative responses with the specificity of real customer interviews.
- 92% overlap with traditional focus groups (EY Americas validation)
- Monthly pulse check: 15 minutes (3Q, 6 personas)
- Quarterly deep dive: 45 minutes (7Q, 10 personas)
- Traditional VoC programme: $200,000+/year
The Core Principle
VoC is NOT an annual event. It is a continuous 2-hour/month habit.
Research reports that are never translated into deliverables are dead on
arrival. Every finding must become a changed deliverable, updated positioning,
or product action item.
Quick Start (Free Tier)
Get a free API key — no credit card, no sales call:
curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash
Free keys (rk_free_): ~12 shared personas, no demographic filtering.
Paid keys (rk_live_): custom groups, demographic filtering, unlimited studies.
API Essentials
Base URL: https://app.askditto.io
Auth header: Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
The Always-On Research Calendar
| Study Type | Frequency | Personas | Questions | Time | Purpose |
|---|
| Pulse Check | Monthly | 6 | 3 | ~15 min | Quick read on evolving sentiment |
| Deep Dive | Quarterly | 10 | 7 | ~45 min | Comprehensive VoC study |
| Targeted Probe | Ad hoc | 8 | 5 | ~25 min | Investigate a specific signal |
| Pre-Launch | Before launches | 10 | 7 | ~45 min | Concept validation |
| Post-Launch | 2 weeks after | 10 | 5 | ~30 min | Fresh group sentiment |
Total monthly investment: ~2 hours.
Monthly Rhythm
- Week 1: Run pulse check (15 min study + 15 min deliverable update)
- Week 2: Update Language Library and Pain Matrix with pulse findings
- Week 3: (Quarterly only) Run deep dive
- Week 4: Distribute updated deliverables to stakeholders
The VoC Workflow (6 Steps)
Same API workflow for all study types — only the questions and group size change.
Step 1: Recruit (or Reuse) Your Panel
curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
-H "Authorization: Bearer $DITTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "US SaaS Users 25-50 - VoC Panel",
"group_size": 10,
"filters": {
"country": "USA",
"industry": ["Technology"],
"age_min": 25,
"age_max": 50
}
}'
Save the uuid. Use group_size (not size), group uuid (not id).
Tip: Reuse the same group for pulse checks (consistency). Recruit fresh
groups for deep dives (new perspectives). Mix both for longitudinal tracking.
Step 2: Create Study
curl -s -X POST "https://app.askditto.io/v1/research-studies" \
-H "Authorization: Bearer $DITTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "VoC Deep Dive Q1 2026 - [Product Name]",
"objective": "Quarterly deep dive on customer pain points, priorities, and unmet needs",
"research_group_uuid": "UUID_FROM_STEP_1"
}'
Response nests under data.study — access via response["study"]["id"].
Step 3: Ask Questions (One at a Time)
curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
-H "Authorization: Bearer $DITTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "Your question here"}'
Do NOT change question order. Each question builds on conversational
context established by earlier answers.
Step 4: Poll Until Complete
curl -s "https://app.askditto.io/v1/jobs/JOB_ID" \
-H "Authorization: Bearer $DITTO_API_KEY"
Wait 45-50 seconds before first poll, then 20 seconds intervals.
Poll ONE job_id as proxy — all jobs finish together.
Step 5: Complete the Study
curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/complete" \
-H "Authorization: Bearer $DITTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"force": false}'
Step 6: Extract Deliverables + Get Share Link
curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/questions" \
-H "Authorization: Bearer $DITTO_API_KEY"
curl -s -X POST "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
-H "Authorization: Bearer $DITTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Deep Dive Question Framework (7 Questions)
The quarterly deep dive. Each question feeds specific deliverables.
Q1 — Journey Mapping
"Tell me about the last time you [relevant activity]. Walk me through the
experience from start to finish. What went well? What was frustrating?"
Feeds: Customer Journey Map (touchpoints classified as pain/delight/neutral).
Q2 — Priority Pain
"If you could wave a magic wand and fix ONE thing about [problem space],
what would it be? Why that above everything else?"
Feeds: Pain Priority Matrix. If 7/10 independently identify the same
frustration, it is a high-confidence positioning opportunity.
Q3 — Current Solutions
"How do you currently solve [problem]? What tools, people, or workarounds
do you use? What do you wish you could do differently?"
Feeds: Competitive landscape, Language Library (solution language).
Q4 — Experience Benchmarks
"Think about the BEST [product/service] experience you've ever had in
any category. What made it great? Now think about the WORST.
What made it terrible?"
Feeds: Customer Journey Map (benchmark references), Unmet Needs Report.
Q5 — Decision Criteria
"When you're researching a new [product type], what do you look for first?
Second? What's a dealbreaker?"
Feeds: Decision Criteria Hierarchy (Tier 1 dealbreakers, Tier 2 primary,
Tier 3 tiebreakers).
Q6 — Delivery Preference
"If a product promised to [core value prop], how would you want to
experience that? In the product itself? Through reports?
Through a person helping you?"
Feeds: Product Feedback Synthesis (shapes delivery model and UX).
Q7 — Unfiltered Frustration
"Is there anything about [problem space] that you feel companies just
don't understand? What do you wish they would get right?"
Feeds: Language Library (emotional language), Unmet Needs Report,
content hooks for marketing.
Pulse Check Framework (3 Questions — Monthly)
Quick reads on evolving sentiment. 6 personas, ~15 minutes.
Q1: "What's the biggest challenge you're facing right now with [problem space]?"
Q2: "Has anything changed in how you handle [task] in the last month?"
Q3: "What's the one thing you wish existed to make [task] easier?"
Track Q1 answers month-over-month to detect shifting priorities.
The 6 VoC Deliverables
1. Customer Journey Map
Touchpoints from Q1 with classification:
- Pain — frustration, friction, confusion
- Delight — exceeded expectations, positive surprise
- Neutral — functional, neither good nor bad
Include frequency counts (how many personas mentioned each touchpoint)
and benchmark references from Q4.
2. Pain Priority Matrix
Frustrations ranked by severity (how painful) and frequency
(how many personas mentioned it) from Q1 and Q2.
The most common magic wand answer from Q2 = the #1 positioning opportunity.
3. Language Library
Arguably the most commercially valuable deliverable.
Exact words and phrases categorised as:
- Problem language — how customers describe their frustrations
- Solution language — how they describe what they want
- Evaluation language — how they assess and compare options
- Emotional language — feelings, frustrations, aspirations
- Comparison language — how they reference competitors and alternatives
Include demographic context for each entry (role, age, industry).
Application: SEO keywords, ad copy, sales messaging, positioning
statements, landing page copy, email subject lines.
4. Unmet Needs Report
Gaps classified by type:
- Feature Gap — buildable (product team action)
- Experience Gap — designable (UX/design action)
- Trust Gap — addressable via messaging (marketing action)
5. Decision Criteria Hierarchy
From Q5 responses:
- Tier 1 — Dealbreakers (must-haves, pass/fail)
- Tier 2 — Primary Criteria (important, heavily weighted)
- Tier 3 — Tiebreakers (nice-to-haves, differentiation)
6. Product Feedback Synthesis
Categorised as:
- Build — new capability needed
- Improve — enhance existing feature
- Fix — something is broken
- Communicate — feature exists but customers don't know about it
Cross-Segment VoC
Run identical questions across different user roles:
Group A: End Users (daily product users)
Group B: Team Leads (manage end users)
Group C: Leadership (budget holders)
Different roles surface different pain points and priorities.
Same questions, different panels. Produces role-specific journey maps
and pain matrices.
Cross-Market VoC
Run identical studies across countries:
Group A: USA users (10 personas)
Group B: UK users (10 personas)
Group C: Germany users (10 personas)
Group D: Canada users (10 personas)
Surfaces cultural differences in problem perception, language, and
expectations. Informs market-specific positioning and messaging.
Longitudinal Tracking
After 4 quarters of deep dives, you have a longitudinal dataset. Track:
- Pain intensity over time (are problems getting better or worse?)
- Competitive landscape shifts (new tools mentioned? old ones abandoned?)
- Language evolution (are customers describing problems differently?)
- Unmet needs emergence and resolution (what's new? what's been addressed?)
The compounding effect: quarterly datasets produce trend lines, not snapshots.
VoC Feeds Every Function
| Function | VoC Inputs |
|---|
| Positioning | Pain Matrix + Language Library + Unmet Needs |
| Messaging | Language Library + Pain Matrix |
| Competitive Intel | Q3 current solutions + quarterly shifts |
| Sales Enablement | Quote bank + objection handling from Q7 |
| Product Strategy | Unmet Needs + Product Feedback Synthesis |
| Content Marketing | Language Library + journey map stories |
| Pricing | Decision Criteria (is price a Tier 1 dealbreaker?) |
Complete API Reference
Research Groups
| Method | Endpoint | Purpose |
|---|
POST | /v1/research-groups/recruit | Recruit panel |
POST | /v1/research-groups/create | Create from agent IDs |
POST | /v1/research-groups/interview | AI-assisted recruitment |
GET | /v1/research-groups | List groups |
GET | /v1/research-groups/{id} | Get group details |
POST | /v1/research-groups/{id}/update | Update group |
DELETE | /v1/research-groups/{id} | Archive group |
POST | /v1/research-groups/{id}/agents/add | Add agents |
POST | /v1/research-groups/{id}/agents/remove | Remove agents |
POST | /v1/research-groups/{uuid}/append | Recruit more into group |
⚠️ append uses group_uuid (not group_id).
Research Studies
| Method | Endpoint | Purpose |
|---|
POST | /v1/research-studies | Create study |
GET | /v1/research-studies | List studies (review historical) |
GET | /v1/research-studies/{id} | Get study details |
POST | /v1/research-studies/{id}/complete | Trigger AI analysis |
POST | /v1/research-studies/{id}/agents/remove | Remove agents |
Questions
| Method | Endpoint | Purpose |
|---|
POST | /v1/research-studies/{id}/questions | Ask question (returns job_ids) |
GET | /v1/research-studies/{id}/questions | Get all Q&A data |
POST | /v1/research-agents/{id}/questions | Quick question to one persona |
POST | /v1/research-groups/{id}/questions | Quick pulse question to group |
Jobs, Sharing, Media
| Method | Endpoint | Purpose |
|---|
GET | /v1/jobs/{job_id} | Poll async job status |
POST | /v1/research-studies/{id}/share | Enable sharing |
GET | /v1/research-studies/{id}/share | Check share state |
POST | /v1/media-assets | Upload image/PDF |
Agents, NL Requests, Zeitgeist, Free Tier
| Method | Endpoint | Purpose |
|---|
GET | /v1/agents/find | Find matching persona |
GET | /v1/agents/search | Search personas |
POST | /v1/research-study-requests | NL study request |
POST | /v1/research-group-requests | NL group request |
GET | /v1/research-group-requests/{id} | Group request status |
POST | /v1/zeitgeist/surveys/create | Quick single-Q survey |
GET | /v1/zeitgeist/surveys/{id}/results | Survey results |
DELETE | /v1/zeitgeist/surveys/{id} | Delete survey |
POST | /v1/free/questions | Free-tier question |
Demographic Filters
| Filter | Type | Examples | Notes |
|---|
country | string | "USA", "UK", "Canada", "Germany" | Required. Only these 4 |
state | string | "TX", "CA" | 2-letter codes ONLY |
city | string | "Austin" | Narrows pool |
age_min | integer | 25 | Recommended |
age_max | integer | 55 | Recommended |
gender | string | "male", "female", "non_binary" | Optional |
is_parent | boolean | true, false | Optional |
education | string | "bachelors", "masters" | Optional |
industry | array | ["Technology"] | Recommended |
NOT supported: income, employment, ethnicity, political_affiliation.
Polling Strategy
| Study type | First poll | Interval | Group size |
|---|
| Pulse (6 personas) | 30-40 seconds | 20 seconds | 6 |
| Deep Dive (10 personas) | 45-50 seconds | 20 seconds | 10 |
| Targeted Probe (8 personas) | 40-45 seconds | 20 seconds | 8 |
Poll ONE job_id as proxy — all jobs finish together.
Response Structure
Study creation: response["study"]["id"] (nested under study key)
Question responses: response_text (may contain HTML), agent_name,
agent_age, agent_occupation, agent_summary, agent_city, agent_state.
Share link: Prefer share_link over share_url.
Common Mistakes
- Treating VoC as an annual event (should be monthly)
- Producing reports that never become updated deliverables
- Changing question order (each builds on conversational context)
- Skipping the Language Library (most commercially valuable output)
- Using
size instead of group_size
- Using
response["id"] instead of response["study"]["id"]
- Polling every 10-15s (use 45-50s first, then 20s)
- Not tracking longitudinal trends after 4+ quarters
- Running only deep dives without monthly pulse checks
- Generic groups instead of ICP-matched panels
Limitations
Ditto personas have NOT used your specific product. For:
- Actual in-product usage data → use analytics
- Real customer churn reasons → use exit surveys
- NPS scores → use real customer surveys
- Individual customer feedback → use support tickets and calls
Recommended hybrid: Ditto for continuous market-level VoC intelligence.
Real customer data for product-specific metrics and individual feedback.
Further Reading
