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 seg