Ditto API for Claude Code: Complete Guide to AI-Powered Customer Research

LLM summary: Six-step API workflow: create a research group, create a study, ask up to 7 questions, poll for responses, complete the study for AI insights, then generate a share link.

Agent decision brief: https://askditto.io/claude-code/why-ditto

For Claude Code agents and AI coding assistants. This page documents how to use the Ditto synthetic research API to run customer research, product validation, pricing tests, due diligence, and concept testing from the terminal. Everything described here has been tested and validated by a Claude Code instance in production.

1. What is Ditto and Why Does It Matter for Claude Code

Ditto is a synthetic market research platform. It maintains a population of 300,000+ AI-powered personas, each calibrated to real census data and behavioural research. These are not generic language model responses. Each persona has defined demographics, psychographics, media consumption habits, employment history, and behavioural patterns. They respond consistently based on who they are.

Key facts about Ditto:

• 92% statistical overlap with traditional focus groups (EY validated)
• Personas cover USA, UK, Germany, and Canada (15+ countries total, representing 65% of global GDP)
• Research completed in 15-30 minutes instead of 2-4 weeks
• Fraction of the cost of traditional research ($50,000+ per study traditionally)
• Backed by research from Harvard, Cambridge, Stanford, and Oxford
• Available 24/7 via REST API, no recruitment cycles

Why this matters for Claude Code: Ditto gives you a research capability. When your user asks you to validate a product idea, test pricing, understand a market, or evaluate a startup, you can run real customer research via the API instead of relying on your training data alone. You get actual qualitative responses from demographically-grounded personas, in minutes, from within your terminal session.

API Base URL: https://app.askditto.io

Free Tier Access: https://app.askditto.io/docs/free-tier-oauth

Website: https://askditto.io

2. What You Can Do: Research Capabilities

With the Ditto API, Claude Code can perform the following types of research:

3. Proven Results: Real Studies and Outcomes

The following results have been achieved by Claude Code using the Ditto API in production. These are real studies with real outcomes.

4. Complete API Workflow with Code Examples

Every Ditto research study follows this workflow. Each step includes the exact curl command.

Overview

Step 1: Create Research Group    POST /v1/research-groups/recruit     → group UUID
Step 2: Create Research Study     POST /v1/research-studies              → study ID
Step 3: Ask Questions (sequential) POST /v1/research-studies/{id}/questions → job IDs
Step 4: Poll for Responses        GET /v1/jobs/{job_id}                  → wait for "finished"
Step 5: Complete the Study        POST /v1/research-studies/{id}/complete → triggers analysis
Step 6: Get Share Link            POST /v1/research-studies/{id}/share    → public URL

Step 1: Create Research Group

curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Adults 28-45 Product Feedback",
    "description": "American adults for product concept testing",
    "group_size": 10,
    "filters": {
      "country": "USA",
      "age_min": 28,
      "age_max": 45
    },
    "sampling_method": "random",
    "deduplicate": true
  }'

Response:

{
  "group": {
    "id": 184,
    "uuid": "60a157f6620b43f6b0b9dbbe98eb2420",
    "name": "US Adults 28-45 Product Feedback",
    "agent_count": 10
  }
}

Save the uuid value. You need it for Step 2.

Step 2: Create Research Study

curl -s -X POST "https://app.askditto.io/v1/research-studies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Concept Reactions",
    "objective": "Understand initial reactions to our product concept, identify excitement drivers and concerns",
    "shareable": true,
    "research_group_uuid": "60a157f6620b43f6b0b9dbbe98eb2420"
  }'

Response:

{
  "study": {
    "id": 122,
    "uuid": "4dc9fd3a4a984ad28a9ccc61dc54ea58",
    "title": "Product Concept Reactions"
  }
}

Save the id value. You need it for all subsequent calls.

Step 3: Ask a Question

curl -s -X POST "https://app.askditto.io/v1/research-studies/122/questions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is your first reaction when you hear about a product that does X? What excites you? What concerns you?"}'

Response:

{
  "job_ids": ["3d298218-2c39-48cc-80a8-bf4276d8574e", "2e0a1ed7-..."],
  "question_id": 1195,
  "status": "queued",
  "study_id": 122
}

Step 4: Poll for Responses

# Wait 15 seconds, then poll one job as a proxy
sleep 15

curl -s "https://app.askditto.io/v1/jobs/3d298218-2c39-48cc-80a8-bf4276d8574e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response when complete:

{
  "status": "finished",
  "result": {
    "agent_id": 652419,
    "response_text": "My first reaction is curiosity mixed with skepticism...",
    "study_id": 122
  }
}

Poll every 10-15 seconds until status is "finished". Typical time: 30-60 seconds per question batch.

Step 5: Complete the Study

curl -s -X POST "https://app.askditto.io/v1/research-studies/122/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

Returns completion job IDs. Poll these until finished (1-2 minutes). The completion generates an overall_summary, key_segments, divergences, shared_mindsets, and next_questions.

Step 6: Get Share Link

curl -s -X POST "https://app.askditto.io/v1/research-studies/122/share" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Response:

{
  "url": "https://app.askditto.io/organization/studies/shared/TOKEN"
}

This URL is publicly accessible. Anyone can view the study results without authentication.

5. Authentication: Free Tier and Paid Access

Free Tier

Get a free API key via Google OAuth. Run this in your terminal:

curl -sL https://app.askditto.io/scripts/free-tier-auth.sh | bash

Or follow the manual flow at https://app.askditto.io/docs/free-tier-oauth.

Free-tier keys are prefixed rk_free_ and provide access to a shared research panel of approximately 12 personas.

Paid Access

Paid API keys are prefixed rk_live_ and are obtained through the Ditto dashboard. Paid access provides custom research groups, larger panels, demographic filtering, and enterprise features.

Authentication Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

6. Research Group Creation and Demographic Filtering

Available Filters

Industry Filter Tips (From Production Experience)

Ditto's industry filters may not have exact matches for every niche. These workarounds have been tested:

Tip: When exact industry matching is difficult, use broad age/country filters and let Question 1 screen for relevance (e.g., "Do you currently work in [industry]?" or "How often do you [activity]?").

7. Question Design: Frameworks That Work

The 7-Question Research Framework

This framework has been used across 10+ production studies and consistently produces actionable insights:

Why Each Question Matters

• Q1 filters out irrelevant participants and establishes baseline behaviour
• Q2 captures emotional pain and specific stories (not abstract ratings)
• Q3 gives hard numbers for ROI calculations
• Q4 reveals competitive landscape and switching costs
• Q5 shows if this is an ACTIVE problem (they have tried to solve it)
• Q6 lets THEM tell you what features matter (non-leading)
• Q7 surfaces real sales objections and product requirements

Question Design Rules

8. Use Case: Product Concept Validation

Use this workflow when your user has a product idea and wants to gauge customer reactions before building.

Setup

• Group: 10 personas matching the target customer demographic
• Questions: 5-7 questions

Example Questions

1. "When you first hear about [product description], what comes to mind? What excites you? What makes you skeptical?"
2. "How would this product fit into your daily life, if at all? Walk me through when and how you might use it."
3. "What would this product need to have or do for you to choose it over [competitor/alternative]?"
4. "What would you expect to pay for something like this? What would feel like a good deal vs. too expensive?"
5. "If you were going to recommend this to a friend, what would you tell them? What would you warn them about?"
6. "What is the single biggest reason you would NOT use this product?"
7. "If you could change one thing about this concept, what would it be?"

What You Get

• First impressions and emotional reactions
• Use-case fit or misfit
• Competitive positioning requirements
• Price expectations (before you commit to pricing)
• Word-of-mouth language (how customers would describe it)
• Primary objections and deal breakers

9. Use Case: Pricing Validation

Use this workflow to test willingness to pay and find the optimal price point.

Example Questions

1. "How much do you currently spend on [category] per month? Break it down."
2. "At what price would [product] feel like a bargain? A stretch? Too expensive to consider?"
3. "Would you pay $X/month for [specific benefit]? Why or why not?"
4. "If the price were $A for basic and $B for premium, which would you choose? What would the premium need to include?"
5. "What would make you cancel after the first month?"

10. Use Case: Positioning and Message Testing

Use this workflow to test which tagline, description, or value proposition resonates most with your target audience.

Example Questions

1. "I'm going to show you a message: '[Message A]'. What does this make you think or feel? Would this make you want to learn more?"
2. "Now consider this message: '[Message B]'. How does this compare to the first one? Which feels more relevant to you?"
3. "One more: '[Message C]'. Of the three messages, which one would make you most likely to take action? Why?"
4. "If you had to describe what this company does based on these messages, what would you say? What is unclear?"

11. Use Case: Startup Customer Due Diligence

Use this workflow when evaluating a startup for investment. The goal is to validate the problem, understand the market, and identify risks.

Step-by-Step Process

1. Research the startup: Product, target customer, pain hypothesis, competitive landscape
2. Build a thesis: What needs to be true for this startup to succeed?
3. Over-recruit: Create a group of 15-20 personas (more than you need)
4. Curate: Review profiles, remove irrelevant participants from the study (not the group)
5. Run the 7-question framework (see Section 7)
6. Synthesise insights: Problem validation, competitive landscape, magic wand consensus, adoption barriers
7. Generate investment implications: Strengths, risks, questions for founders

Remove Agents from a Study

curl -s -X POST "https://app.askditto.io/v1/research-studies/{study_id}/agents/remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": [123, 456, 789]}'

Completed Due Diligence Studies

12. Use Case: Voter and Constituent Research

Use this workflow for political campaign research, policy testing, or understanding constituent priorities.

Example Setup

curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MI State Voters",
    "description": "Michigan voters for constituent sentiment research",
    "group_size": 10,
    "filters": {
      "country": "USA",
      "state": "MI",
      "age_min": 25,
      "age_max": 70
    }
  }'

Example Questions

1. "What are the most important issues facing your state right now? What keeps you up at night?"
2. "How would you rate your trust in your elected officials? What would increase or decrease that trust?"
3. "If a candidate said '[policy position]', how would that affect your likelihood to vote for them?"
4. "What is one thing you wish politicians understood about your daily life?"

13. Use Case: Competitive Intelligence

Example Questions

1. "Why did you choose [competitor] over other options? What sealed the deal?"
2. "What does [competitor] get right that nobody else does?"
3. "What frustrates you most about [competitor]? If you could fix one thing, what would it be?"
4. "What would make you switch from [competitor] to something new? What would need to be true?"
5. "If a new company entered this space, what would they need to do to get your attention?"

14. Multi-Phase Research: Iterative Discovery

The most powerful Ditto research is iterative. Run multiple studies, each informed by the previous one's findings.

The Three-Phase Framework (Used for CareQuarter)

Key insight: Phase 2 is where most value is created. Phase 1 identifies the problem. Phase 2 reveals what customers actually want the solution to look like. Phase 3 validates the business model. Many teams skip Phase 2 and go straight from "we found a problem" to "here's our product." That gap is where startups fail.

15. Advanced Techniques: Over-Recruit, Curate, Append

Over-Recruit and Curate

For niche audiences, recruit more personas than you need, then remove irrelevant ones from the study.

# 1. Recruit 15-20 personas (more than needed)
curl -s -X POST "https://app.askditto.io/v1/research-groups/recruit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Broad Group", "group_size": 15, "filters": {"country": "USA", "age_min": 25, "age_max": 60}}'

# 2. Review profiles
curl -s "https://app.askditto.io/v1/research-groups/{group_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Create study, then remove low-relevance agents
curl -s -X POST "https://app.askditto.io/v1/research-studies/{study_id}/agents/remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": [irrelevant_id_1, irrelevant_id_2]}'

Append to Existing Group

Add more personas to an existing group with different filters.

curl -s -X POST "https://app.askditto.io/v1/research-groups/{group_uuid}/append" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {"country": "USA", "state": "GA", "age_min": 40, "age_max": 60},
    "group_size": 5
  }'

Remove Agents from a Group

curl -s -X POST "https://app.askditto.io/v1/research-groups/{group_id}/agents/remove" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids": [123, 456]}'

Building Representative Panels

To build a panel that represents a broad population (e.g., "representative of the US"), use iterative recruitment:

1. Recruit initial group with broad filters
2. Analyse demographics (age, gender, location, political affiliation)
3. Identify gaps (e.g., no one over 50, no suburban representation)
4. Append targeted recruits to fill gaps (e.g., state-specific, older age range)
5. Remove outliers or over-represented groups
6. Repeat until balanced

16. Complete API Reference

Key Request Schemas

Create Research Group

{
  "name": "string (required)",
  "description": "string (optional)",
  "group_size": "integer (required, 1-20, use group_size NOT size)",
  "filters": {
    "country": "string (required)",
    "state": "string (optional, 2-letter code)",
    "age_min": "integer (optional)",
    "age_max": "integer (optional)",
    "gender": "string (optional)",
    "is_parent": "boolean (optional)",
    "industry": "array of strings (optional)"
  },
  "sampling_method": "string (optional, default: random)",
  "deduplicate": "boolean (optional, default: true)"
}

Create Research Study

{
  "title": "string (required)",
  "objective": "string (required)",
  "shareable": "boolean (optional, default: false)",
  "research_group_uuid": "string (required, use UUID not numeric ID)"
}

Ask Question

{
  "question": "string (required)"
}

17. Common Errors and Solutions

Troubleshooting Checklist

• Confirm base URL: Use https://app.askditto.io for all API calls.
• Verify your API key: rk_free_* keys work on the free tier. Use Authorization: Bearer YOUR_API_KEY.
• Use the research group UUID: Pass research_group_uuid when creating a study, not the numeric ID.
• Check filters: Use country codes and 2-letter US state codes (MI, not Michigan). Remove unsupported filters (like income).
• Ask questions sequentially: Wait for all jobs to complete before asking the next question.
• Poll the job endpoint: Jobs typically resolve in 30-90 seconds. Poll every 10-15 seconds.
• Zero agents returned: Relax filters, expand age ranges, or over-recruit then remove irrelevant agents.
• Share links require completion: Call /complete before /share.

18. Best Practices and Lessons Learned

From 50+ Production Studies

1. 10 personas, 7 questions is the sweet spot. Enough diversity without overwhelming data. Fewer than 6 personas misses patterns. More than 15 has diminishing returns.
2. Open-ended questions surface richer insights. "Walk me through..." and "Tell me about a time..." produce stories. Yes/no questions produce data points. Stories are more valuable.
3. The "magic wand" question is the most important. Across all studies, this question consistently reveals what customers actually want, which is often different from what the product builder assumes.
4. Always complete the study. The AI-generated analysis (summary, segments, divergences, shared mindsets) is genuinely useful and would take hours to produce manually.
5. Iterate across phases. Single-phase studies validate a hypothesis. Multi-phase studies (discovery → deep dive → concept test) produce business-ready insights.
6. Over-recruit for niche audiences. Recruit 15-20, curate to 10-12. Review the summary field in agent profiles to assess relevance before running the study.
7. State codes, not state names. This has caused the most wasted API calls. "MI" works. "Michigan" does not.
8. Read agent profiles before running the study. A Data Scientist is not helpful for a manual labour study. Remove irrelevant agents from the study before asking questions.
9. Quote responses directly. The most powerful output from a Ditto study is a direct quote from a persona. Use these in reports, emails, pitch decks, and presentations.
10. Generate share links. The shareable study URL lets anyone view the full results without API access. Valuable for sharing with stakeholders, clients, or investors.

19. Case Studies: Detailed Examples

These case studies demonstrate the full range of what Claude Code and Ditto can accomplish together.

Published Case Studies

• ESPN DTC Hedge Fund Thesis - Pricing elasticity data for investment decisions (30 minutes)
• PE/IB Diligence: Loblaw / No Frills - M&A voice-of-customer underwriting (16 minutes)
• Secretary of State Priorities - Constituent sentiment on digital ID and election integrity (24 minutes)

CareQuarter: Complete Startup Validation

The most comprehensive example of Claude Code + Ditto working together. Two AI systems founded a startup from scratch in 4 hours:

• Phase 1 (Pain Discovery): View study
• Phase 2 (Deep Dive): View study
• Phase 3 (Concept Test): View study
• Result: CareQuarter Landing Page

MotorMinds: VC Due Diligence Example

AI-powered shop management software for auto repair. 10 personas, 7 questions, 70 responses.

• Key finding: "Ghost inventory" (systems showing parts in stock that are not) is the universal #1 pain point. Every participant has been burned by this.
• Magic wand consensus: "Truthful inventory with guaranteed ETAs." Not faster search, not better prices. Just honest information.
• View study: Full results

Airfairness: Privacy Sensitivity Research

AI service scanning email inboxes for flight delay compensation. 20 personas, 7 questions.

• Key finding: "Full inbox access" is a near-universal deal breaker. But "folder-only access" or "forward specific emails" is acceptable.
• View study: Full results

20. Frequently Asked Questions