Ditto Product Research

Run customer research, pricing tests, and product validation studies 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 interviews.

• 92% overlap with traditional focus groups (EY Americas validation)
• 95% correlation with traditional research
• Harvard/Cambridge/Stanford/Oxford peer-reviewed methodology
• A 10-persona, 7-question study completes in 10-12 minutes
• Traditional equivalent: 4-8 weeks, $10,000-50,000

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

Or visit: https://app.askditto.io/docs/free-tier-oauth

Ask a question immediately:

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about grocery shopping?"}'

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 Standard Workflow (6 Steps)

IMPORTANT: Follow these steps in order. Questions MUST be asked sequentially — wait for all responses before asking the next.

Step 1: Recruit 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 Adults 30-55",
    "group_size": 10,
    "filters": {"country": "USA", "age_min": 30, "age_max": 55}
  }'

Save the uuid from the response (5-15 seconds).

CRITICAL: Use group_size not size. Use group uuid not id. State filter uses 2-letter codes ("MI" not "Michigan").

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": "Product Concept Validation",
    "objective": "Understand customer pain points and validate pricing",
    "research_group_uuid": "UUID_FROM_STEP_1"
  }'

Save the study id. Response nests under data.study — access via response["study"]["id"], NOT response["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 open-ended question here"}'

Returns job_ids (one per persona). Poll until complete before asking next.

Step 4: Poll Until Complete

curl -s "https://app.askditto.io/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $DITTO_API_KEY"

Polling strategy for 10-persona study:

• Wait 45-50 seconds before first poll
• Then poll every 20 seconds
• Poll ONE job_id as proxy — all jobs from the same question finish together
• Status: queued → started → finished (or failed)

ALL jobs must show finished before asking the next question.

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}'

Triggers AI analysis: summary, segments, divergences, recommendations (20-40s). Use "force": true to re-run analysis on an already-completed study (avoids 409).

Step 6: Get Share Link

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}'

Returns a public URL. Use share_link field (preferred over share_url). To check existing share state without changing it:

curl -s "https://app.askditto.io/v1/research-studies/STUDY_ID/share" \
  -H "Authorization: Bearer $DITTO_API_KEY"

Workflow Patterns

Standard 7-Question Study

The default. Recruit 10 personas → create study → ask 7 questions → complete → share. ~10-12 minutes total.

Over-Recruit & Curate

For niche audiences or when participant quality matters most (e.g., VC diligence):

1. Recruit 15-20 participants: "group_size": 15
2. Create study from that group
3. Ask Q1 as a screening question ("Tell me about your role and how often you...")
4. Review Q1 responses — score each agent: High / Medium / Low relevance
5. Remove low-relevance agents from the study (not the group):

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

   agent_ids must be list[int] — never strings or UUIDs.
6. Ask Q2-Q7 to curated panel only. Keep minimum 8 personas.

Quick Question (No Study)

For 1-5 quick answers without creating a full study:

To a specific agent:

curl -s -X POST "https://app.askditto.io/v1/research-agents/AGENT_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

To an entire group:

curl -s -X POST "https://app.askditto.io/v1/research-groups/GROUP_ID/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What matters most when choosing a coffee brand?"}'

Free Tier

~12 shared personas, no demographic filtering. Good for quick tests:

curl -s -X POST "https://app.askditto.io/v1/free/questions" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What frustrates you most about meal planning?"}'

Three-Phase Iterative

For deeper validation, run 3 sequential studies (can share the same group):

Each phase's questions should be informed by the previous phase's findings. ~30-45 minutes total.

Resume Stalled Study

If a study was interrupted mid-way:

1. Get study details: GET /v1/research-studies/STUDY_ID
2. List existing questions: GET /v1/research-studies/STUDY_ID/questions
3. Resume from the next unanswered question
4. Complete when all questions are asked

Zeitgeist Survey

Quick single-question survey with predefined answer options:

curl -s -X POST "https://app.askditto.io/v1/zeitgeist/surveys/create" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brand Awareness Pulse",
    "question": "Which brand comes to mind first for sustainable coffee?",
    "research_group_uuid": "GROUP_UUID",
    "answer_options": ["Brand A", "Brand B", "Brand C", "Other"]
  }'

Get results: GET /v1/zeitgeist/surveys/SURVEY_ID/results Delete: DELETE /v1/zeitgeist/surveys/SURVEY_ID

Natural Language Requests

Let the system design your study or group from a plain-text brief:

Study request:

curl -s -X POST "https://app.askditto.io/v1/research-study-requests" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_text": "I want to understand why millennials are