Ditto political polling

Ditto for Political Polling & Voter Research

Run state-specific voter research, campaign messaging tests, and candidate perception 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. You ask them open-ended questions and get qualitative responses with the specificity of real voter 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 voter study completes in 10-12 minutes
• Traditional voter research: 2-4 weeks, $15,000-50,000

The Non-Negotiable Rule

Every political study MUST use a state-filtered research group.

• NEVER use generic groups like "American Voters" or "Suburban Voters"
• Group name format: {StateCode} State Voters (e.g., "MI State Voters")
• State filter: 2-letter codes ONLY (MI, TX, PA, OH, AZ)
• Full state names ("Michigan") return 0 agents
• political_affiliation is NOT a supported filter

State-specific groups produce dramatically more relevant responses than generic national groups. This has been validated across 50+ studies.

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 state filtering. Paid keys (rk_live_): state-specific 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 Voter Research Workflow (7 Steps)

Step 1: Research the Candidate

Before touching the API, research:

• Candidate background (career, previous offices, accomplishments)
• Party affiliation (Democrat/Republican/Independent)
• Key issues they are running on
• Opponent(s) — incumbent or challenger?
• Race dynamics (competitive? safe seat? toss-up?)
• Recent news (controversies, endorsements, polling numbers)
• Current campaign messaging and slogans

This research directly informs Q3 (candidate briefing) and Q6 (messaging test).

Step 2: Check for Existing State Group

Before creating a new group, check if one already exists:

curl -s "https://app.askditto.io/v1/research-groups?limit=50" \
  -H "Authorization: Bearer $DITTO_API_KEY"

Look for groups named {StateCode} State Voters. Reuse existing state groups for multiple races in the same state.

Step 3: Recruit State-Specific 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": "MI State Voters",
    "group_size": 10,
    "filters": {
      "country": "USA",
      "state": "MI",
      "age_min": 18,
      "age_max": 65
    }
  }'

Save the uuid. Use group_size (not size), group uuid (not id).

If recruitment returns 0 agents: wait 30 seconds and retry. If still 0, the study cannot proceed. NEVER fall back to a generic non-state group.

Step 4: 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": "John Smith Voter Research - Michigan",
    "objective": "Understand MI voter priorities and perception of John Smith in the congressional race",
    "research_group_uuid": "UUID_FROM_STEP_3"
  }'

Save the study id. Response nests under data.study — access via response["study"]["id"], NOT response["id"].

Naming convention:

• Title: [Candidate Name] Voter Research - [State]
• Objective: Understand [State] voter priorities and perception of [Candidate] in the [race type] race

Step 5: 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": "What are the top 2-3 issues that affect your daily life in Michigan? Walk me through what that looks like."}'

Returns job_ids. Poll until complete before asking the next question.

Step 6: Poll Until Complete

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

Polling strategy:

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

Step 7: Complete and Extract Insights

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

Use "force": true to re-run analysis on an already-completed study (avoids 409).

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

Use share_link field (preferred over share_url).

The Political Question Framework (7 Questions)

These questions are designed to surface real voter dynamics, not predictable partisan responses. The candidate is introduced at Q3 — never Q1.

Q1 — Ground in Local Reality

"What are the top 2-3 issues that affect your daily life in [state/district]? Walk me through what that looks like."

Purpose: Establishes what voters actually care about before any candidate context.

Q2 — Decision Drivers

"When you're deciding who to vote for, what matters most? What's an instant dealbreaker for a candidate?"

Purpose: Reveals decision criteria and red lines.

Q3 — Candidate Briefing + Reaction

"Let me tell you about [Candidate]. [Background, party, key positions, endorsements, campaign focus — 6-8 concrete details]. What's your honest first reaction?"

Purpose: Tests candidate perception. Include 6-8 specific details: party affiliation, career background, key policy positions, endorsements, recent actions, campaign slogans. Generic briefings get generic responses.

ANCHORING RULE: Introduce the candidate at Q3, NOT Q1. Establishing voter priorities first (Q1-Q2) produces unbiased baseline data.

Q4 — Competitive Frame

"How does [Candidate] compare to [opponent(s)]? Who feels more trustworthy on the issues you care about?"

Purpose: Reveals competitive positioning and trust dynamics.

Q5 — Persuasion Levers

"What would [Candidate] need to say or do to earn your vote? Be specific."

Purpose: Identifies what persuades undecided or soft-opposition voters. This is the most actionable question for campaign strategists.

Q6 — Messaging Test

"Here's their main campaign message: '[quote/slogan]'. Does this resonate? What's missing?"

Purpose: Tests whether the campaign's actual messaging lands or falls flat. Use the real campaign slogan or tagline.

Q7 — Constituent Advice

"If [Candidate] sat down with you for 5 minutes, what would you tell them? Don't hold back."

Purpose: Surfaces unfiltered voter concerns, fears, and advice. Best source of quotable insights for reports and content.

Question Framework Variants

Mix these into the standard 7 questions or use standalone:

Variant	Question Template	Measures
Name Recognition	"What's your gut reaction when you hear [Name]?"	Awareness + first impressions
Issue Ownership	"Who do you trust more on [issue]: [A] or [B]?"	Competitive positioning per issue
Messaging Test	"[Candidate] says '[message]'. Your reaction?"	Message effectiveness
Switching Trigger	"What would make you change your mind about [Candidate]?"	Persuadable voter dynamics
Enthusiasm Gap	"How excited are you to vote for [Candidate]? 1-10."	Turnout likelihood proxy
Concern Surfacing	"What's your biggest concern about [Candidate]?"	Attack vulnerability mapping

Insight Extraction for Political Research

Good political insight: Specific voter concern with a direct quote, surprising perception gap, actionable messaging feedback, competitive vulnerability.

Weak political insight: Generic sentiment, expected partisan response, abstract observation, confirmation of already-known positions.

Extraction Template

For each study, structure findings as:

Key Finding 1: [Voter perception or concern]

• Best quote: "[direct quote from persona]"
• Campaign implication: [what the campaign should do]

Key Finding 2: [Issue priority or messaging reaction]

• Best quote: "[direct quote]"
• Actionable takeaway: [specific next step]

Key Finding 3: [Competitive dynamic or persuasion opportunity]

• Best quote: "[direct quote]"
• Strategic insight: [what this means for the race]

Overall Narrative: What story do these findings tell about the race?

Trust Patterns in Political Research

From cross-study analysis of 50+ voter studies:

• Voters reward local presence and track record over national endorsements
• "Show up at community events, not just campaign rallies" is a recurring theme
• Incumbents have a natural advantage on "knowing local issues"
• Challengers can win on "fresh perspective" and "not part of the problem"
• Voters are more persuaded by specific local actions than party platform

Multi-Race Studies

Run the same state group across multiple races:

Group: MI State Voters (10 personas)
Study 1: Governor's race (7 questions)
Study 2: Senate race (7 questions)
Study 3: Congressional race (7 questions)

Same panel, different candidate briefings. Produces cross-race comparison showing which candidates resonate with the same voters and where messaging conflicts exist. Reuse the group — create new studies for each race.

Cross-State Comparison

Run the same questions across different state groups:

Group A: PA State Voters — Senate messaging test
Group B: OH State Voters — Senate messaging test
Group C: MI State Voters — Senate messaging test

Same 7 questions, different state panels. Reveals how the same messaging lands differently in different states.

Complete API Reference

Research Groups

Method	Endpoint	Purpose
POST	/v1/research-groups/recruit	Recruit state-specific group
POST	/v1/research-groups/create	Create group from explicit agent IDs
POST	/v1/research-groups/interview	AI-assisted recruitment from objective
GET	/v1/research-groups	List all groups (check for existing state groups)
GET	/v1/research-groups/{id}	Get group details + voter profiles
POST	/v1/research-groups/{id}/update	Update name/description
DELETE	/v1/research-groups/{id}	Archive group
POST	/v1/research-groups/{id}/agents/add	Add agents by ID
POST	/v1/research-groups/{id}/agents/remove	Remove agents from group
POST	/v1/research-groups/{uuid}/append	Recruit more agents into existing group

⚠️ Note: append uses group_uuid (not group_id).

Research Studies

Method	Endpoint	Purpose
POST	/v1/research-studies	Create voter study (research_group_uuid required)
GET	/v1/research-studies	List studies
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 from study

Questions

Method	Endpoint	Purpose
POST	/v1/research-studies/{id}/questions	Ask question in study (returns job_ids)
GET	/v1/research-studies/{id}/questions	Get all Q&A data + voter profiles
POST	/v1/research-agents/{id}/questions	Quick question to one voter persona
POST	/v1/research-groups/{id}/questions	Quick question to entire state group

Jobs, Sharing, Media

Method	Endpoint	Purpose
GET	/v1/jobs/{job_id}	Poll async job status
POST	/v1/research-studies/{id}/share	Enable/disable sharing
GET	/v1/research-studies/{id}/share	Check current share state
POST	/v1/media-assets	Upload image/PDF (ad creative, mailers)

Agents

Method	Endpoint	Purpose
GET	/v1/agents/find	Find one matching persona
GET	/v1/agents/search	Search personas by demographics

Natural Language Requests

Method	Endpoint	Purpose
POST	/v1/research-study-requests	Create study from plain-text brief
POST	/v1/research-group-requests	Create group from description
GET	/v1/research-group-requests/{id}	Get group request status

Zeitgeist Surveys

Method	Endpoint	Purpose
POST	/v1/zeitgeist/surveys/create	Quick single-question voter poll
GET	/v1/zeitgeist/surveys/{id}/results	Get survey results
DELETE	/v1/zeitgeist/surveys/{id}	Delete survey

Free Tier

Method	Endpoint	Purpose
POST	/v1/free/questions	Ask question to shared free-tier group

Demographic Filters

Filters go inside the filters dict when recruiting:

Filter	Type	Examples	Notes
country	string	"USA"	Always "USA" for political research
state	string	"MI", "TX", "PA"	2-letter codes ONLY. Mandatory for political.
city	string	"Detroit", "Houston"	Optional — narrows pool
age_min	integer	18	Voting age minimum
age_max	integer	65	Typical voter range
gender	string	"male", "female", "non_binary"	Optional
is_parent	boolean	true, false	Good for family voter segments
education	string	"high_school", "bachelors"	Optional

NOT supported: income, employment, ethnicity, political_affiliation.

All political segmentation (party, ideology, voter type) must happen through question design and response analysis — not recruitment filters.

Polling Strategy

Study size	First poll delay	Subsequent interval	Strategy
10 personas	45-50 seconds	20 seconds	Poll ONE job_id as proxy
12-15 personas	50-60 seconds	20 seconds	Poll ONE job_id as proxy

Response Structure

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

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

• response_text — the voter's answer (may contain HTML)
• agent_name, agent_age, agent_city, agent_state, agent_country
• agent_occupation, agent_summary

Use demographics to segment: urban vs suburban, younger vs older, occupation-based.

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

Zeitgeist: Quick Voter Polls

For rapid single-question polls with predefined 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": "MI Governor Issue Priority",
    "question": "Which issue matters most to you in the governor race?",
    "research_group_uuid": "STATE_GROUP_UUID",
    "answer_options": ["Economy & Jobs", "Healthcare", "Education", "Infrastructure", "Public Safety"]
  }'

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

Media Attachments

Upload campaign mailers, ad creative, or debate screenshots:

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/campaign-mailer.png",
    "filename": "mailer-draft.png",
    "mime": "image/png"
  }'

Then reference in a question:

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 campaign mailer. What message does it communicate? Does it make you more or less likely to support this candidate?",
    "attachments": [MEDIA_ASSET_ID]
  }'

Common Mistakes

• Using generic groups ("American Voters") instead of state-filtered groups
• Using full state names ("Michigan") instead of 2-letter codes ("MI")
• Filtering by political_affiliation (not supported)
• Introducing the candidate in Q1 instead of Q3 (anchoring bias)
• Asking leading partisan questions ("Would you vote for a Democrat?")
• Generic candidate briefings in Q3 (include 6-8 concrete details)
• Using size instead of group_size in recruitment
• Using response["id"] instead of response["study"]["id"]
• Passing agent_ids as strings instead of list[int]
• Polling every 10-15s (too aggressive — use 45-50s first, then 20s)
• Skipping the complete step (miss AI-generated voter analysis)
• Falling back to non-state groups when recruitment returns 0 agents
• Assuming voter alignment from demographics alone

What NOT to Ask

These produce predictable, useless responses:

• "Would you vote for a Democrat/Republican?" (partisan reflex)
• "Do you care about the economy?" (everyone says yes)
• "Is honesty important in a politician?" (obviously)
• "Do you support lower taxes?" (leading)

Instead, ask: "What are the top 2-3 issues that affect your daily life?" — let them tell you what matters without prompting.

Error Handling

Error	Cause	Fix
0 agents returned	Full state name used	Use 2-letter code
0 agents returned	Very small state	Try city filter instead, or widen age
409 Conflict	Study already completed	Retry with "force": true
429 Too Many Requests	Rate limited	Wait 30-60s
Job failed	Persona error	Report partial failure, don't auto-retry

Limitations

• Political affiliation cannot be filtered — segment via responses only
• Only USA, UK, Germany, Canada available (no state-level outside USA)
• Personas reflect general voter sentiment, not predictions of actual results
• For legally defensible polling → use certified human pollsters
• For get-out-the-vote targeting → use voter file data

Recommended hybrid: Ditto for rapid campaign intelligence (messaging tests, perception studies, issue discovery). Human polling for final pre-election numbers and legally reportable results.

Further Reading

• Full API guide: https://askditto.io/claude-code-guide
• Question design: @question-playbook.md
• State group strategy: @advanced/political-state-groups.md