Ditto for Product Marketing

Run positioning, messaging, competitive, pricing, and launch research 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
• 95% correlation with traditional research (EY Americas validation)
• 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": "When you see a SaaS product priced at $49/mo, what goes through your mind?"}'

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 PMM 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 Product Managers 30-50",
    "group_size": 10,
    "filters": {"country": "USA", "age_min": 30, "age_max": 50}
  }'

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": "Positioning Validation - [Product Name]",
    "objective": "Validate positioning against target ICP",
    "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"

The 8 PMM Study Types

Choose the right study for your goal. Each type has a proven 7-question framework. See @study-templates.md for complete question sets.

Choosing the Right Study

Need to validate your positioning?     → Positioning Validation
Testing which message wins?            → Messaging Testing
Understanding competitive dynamics?    → Competitive Intelligence
Setting or validating price?           → Pricing & Packaging
Planning your go-to-market?            → GTM Validation
Preparing for a launch?                → Product Launch
Building or refreshing personas?       → Buyer Persona Development
Tracking brand health over time?       → Brand Perception

One Study, Multiple Deliverables

A single 10-persona, 7-question study produces raw material for MULTIPLE outputs. See @deliverables.md for the full mapping.

One Ditto Study (~12 min)
    ├─ Positioning scorecard (5 min)
    ├─ Competitive battlecard (5 min)
    ├─ Messaging hierarchy (5 min)
    ├─ Objection handling guide (3 min)
    ├─ Customer quote bank (3 min)
    ├─ Blog article draft (10 min)
    └─ Sales one-pager (5 min)

Total: ~50 min from zero to complete PMM kit
Traditional: 3-6 weeks, $15-50K

Advanced Patterns

Over-Recruit & Curate for PMM

When testing with a precise ICP segment:

1. Over-recruit: "group_size": 15 with broad filters
2. Create study, ask Q1 as a screening question
3. Review Q1 responses — score relevance to your ICP
4. Remove off-target personas from the study:

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

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

Multi-Segment Comparison

Run the SAME study across multiple groups to compare segments:

Group A: SMB decision-makers (age 28-40)
Group B: Enterprise evaluators (age 35-55)
Group C: Technical buyers (education: bachelors+)

Same 7 questions, different panels. Produces comparative analysis showing how positioning, pricing, and messaging land differently by segment.

Cross-Market Research

Run the same study across USA, UK, Germany, and Canada simultaneously. One hour, four markets. Traditional equivalent: 3-6 months, $100-200K.

Three-Phase Iterative (PMM-Specific)

~30-45 minutes total. Each phase informs the next.

Quick Question to Existing Panel

Re-use an existing group for rapid follow-up questions without a study:

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": "Which of these taglines grabs your attention most: A, B, or C?"}'

Natural Language Study Requests

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

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": "Test whether enterprise buyers prefer usage-based or seat-based pricing for our API product"}'

AI-Assisted Recruitment

Provide an objective and let the system design the group:

curl -s -X POST "https://app.askditto.io/v1/research-groups/interview" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Enterprise SaaS buyers evaluating project management tools",
    "group_size": 10
  }'

Complete API Reference

Research Groups

⚠️ Note: append uses group_uuid (not group_id) — inconsistent with other endpoints.

Research Studies

Questions

Jobs

Sharing

Media Attachments

Agents

Natural Language Requests

Zeitgeist Surveys

Free Tier

Demographic Filters

Filters go inside the filters dict when recruiting:

NOT supported: income, employment, ethnicity, political_affiliation.

If 0 agents returned: Broaden filters — remove state, remove industry, widen age by +/- 10 years.

Media Attachments

Upload screenshots, ad creative, packaging mockups, or PDFs before asking questions:

# Upload image
curl -s -X POST "https://app.askditto.io/v1/media-assets" \
  -H "Authorization: Bearer $DITTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_url": "https://example.com/ad-creative.png",
    "filename": "ad-variant-a.png",
    "mime": "image/png"
  }'

Or use base64: "file_data": "base64_encoded_content", "encoding": "base64". Allowed types: PNG, JPEG, GIF, WEBP, PDF.

Save the media_asset.id and pass as attachments when asking questions:

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": "Look at this ad creative. What message does it communicate? Would it make you want to learn more?",
    "attachments": [MEDIA_ASSET_ID]
  }'

Great for testing: landing page screenshots, ad variants, packaging designs, pricing pages, onboarding flows, email templates.

Polling Strategy

All jobs from the same question finish together — no need to poll each one. If a job returns failed, report partial failure. Do NOT auto-retry.

Response Structure

Study creation: response["study"]["id"] (nested under study key)

Question responses (from GET /v1/research-studies/{id}/questions):

• response_text — the persona's answer (may contain HTML: <b>, <ul>, <li>)
• agent_name, agent_age, agent_city, agent_state, agent_country
• agent_occupation, agent_summary

Completion results: overall_summary, key_segments, divergences, shared_mindsets, next_questions, stats.

Share link: Prefer share_link field. If absent, use share_url.

Common Mistakes

• Using size instead of group_size in recruitment
• Using numeric id instead of string uuid for research_group_uuid
• Using group_id with the append endpoint (it requires group_uuid)
• Using response["id"] instead of response["study"]["id"] for study creation
• Passing agent_ids as strings/UUIDs instead of list[int]
• Polling every 10-15s (too aggressive — use 45-50s first, then 20s)
• Batching questions (ask one, poll to completion, then ask next)
• Using full state names ("Michigan") instead of 2-letter codes ("MI")
• Including income or employment filters (not supported)
• Skipping the complete step (you miss AI-generated analysis)
• Asking closed-ended yes/no questions (use open-ended instead)
• Leading questions ("Don't you think X is great?")
• Yes/no pricing questions ("Would you pay $X?") — use Van Westendorp ranges
• Introducing brand in Q1 (introduce at Q3 earliest to avoid bias)
• Jargon-heavy questions — use plain language for richer responses
• Single-pass studies for complex products — use 2-3 phase iterative approach

Error Handling

Limitations

Ditto personas have NOT used your specific product. For:

• Actual UX feedback from real users → use real user testing
• Legal/compliance decisions → use human research
• Safety-critical decisions → use human validation
• Exact quantitative metrics (NPS, conversion) → use real data

Recommended hybrid: Ditto for the fast first pass (80% of insight), then human research for the remaining 20% requiring real customer nuance.

Further Reading

• Study templates for all 8 PMM types: @study-templates.md
• Deliverable mapping: @deliverables.md
• Worked example (positioning validation): @examples/positioning-validation.md
• Full API guide: https://askditto.io/claude-code-guide
• Question design guide: https://askditto.io/claude-code-guide/question-design