Ditto Recruitment Strategies for Claude Code

For Claude Code agents and AI coding assistants. This guide documents how to create effective research groups for Ditto synthetic research studies. It covers demographic filtering, industry proxy mapping, the over-recruit-and-curate methodology, and every known pitfall from 50+ production studies.

1. Research Group API Basics

Create a 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
  }
}

Request Schema

{
  "name": "string (required) - descriptive name for the group",
  "description": "string (optional) - what these participants represent",
  "group_size": "integer (required, 1-20) - MUST use group_size, NOT size",
  "filters": {
    "country": "string (required) - USA, UK, Germany, or Canada",
    "state": "string (optional) - 2-LETTER CODE ONLY for US states",
    "age_min": "integer (optional) - minimum age",
    "age_max": "integer (optional) - maximum age",
    "gender": "string (optional) - male, female, non_binary",
    "is_parent": "boolean (optional) - true or false",
    "education": "string (optional) - high_school, bachelors, masters, phd",
    "employment": "string (optional) - employed, self_employed, unemployed, retired",
    "industry": "array of strings (optional) - industry categories"
  },
  "sampling_method": "string (optional, default: random)",
  "deduplicate": "boolean (optional, default: true)"
}

2. Complete Filter Reference

3. Country Availability and Aliases

Ditto supports 4 countries for research groups. The API accepts multiple name variants:

Ditto covers 15+ countries total representing 65% of global GDP, but these 4 are the most extensively calibrated and available via the API.

4. US State Filtering (Critical)

Correct State Codes

Example: Creating a State-Filtered Group

# CORRECT - uses 2-letter code
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",
    "group_size": 10,
    "filters": {
      "country": "USA",
      "state": "MI",
      "age_min": 25,
      "age_max": 70
    }
  }'

# WRONG - full name, will return 0 agents silently
# "state": "Michigan"  <-- DO NOT DO THIS

Naming Convention for State Groups

Use the format "{StateCode} State Voters" to enable group reuse:

• "MI State Voters"
• "TX State Voters"
• "PA State Voters"

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

curl -s "https://app.askditto.io/v1/research-groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for groups with names matching the "{StateCode} State Voters" pattern. If one exists and was created with the correct state filter, reuse it.

5. Industry Proxy Mapping

Ditto's industry filters cover broad categories. When your target audience does not have an exact match, use these validated proxy mappings:

Validated Industry Proxy Table

The Q1 Screening Strategy

When exact industry filters do not exist, use broad demographic filters and make Question 1 a relevance screen:

This strategy was used successfully for:

• Pet owners: Age 30-60 + USA, Q1: "Do you currently have a pet, or have you had one in the past 5 years?"
• Frequent travellers: Age 25-55 + employed, Q1: "How often do you fly, and for what purposes?"
• Eye care practitioners: Healthcare industry, Q1: "What is your role in eye care or healthcare?"

6. The Over-Recruit and Curate Strategy

For niche audiences where demographic filters cannot perfectly target the desired participants, use the over-recruit and curate strategy.

The Process

1. Recruit 15-20 participants (more than you need for the study)
2. Review each participant's profile (name, occupation, summary, age, location)
3. Score each participant for relevance (see Section 7)
4. Create the study using the full group UUID
5. Remove low-relevance agents from the STUDY (not the group)
6. Run the study with the remaining 8-12 curated participants

Why This Works

Ditto's population is broad. An "Automotive Manufacturing" filter might return a mix of service advisors, assembly line workers, and supply chain managers. For a study about auto parts sourcing, service advisors are ideal, assembly line workers are somewhat relevant, and supply chain managers may not be useful. Over-recruiting lets you select the best participants instead of hoping the random sample is good enough.

API Workflow

# Step 1: Over-recruit (15-20 participants)
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": "MotorMinds - Auto Service Professionals",
    "group_size": 15,
    "filters": {
      "industry": ["Automotive Manufacturing"],
      "age_min": 25,
      "age_max": 60
    }
  }'

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

# Step 3: Create study (use uuid, not id)
curl -s -X POST "https://app.askditto.io/v1/research-studies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Auto Parts Sourcing Study",
    "objective": "Understand parts sourcing pain points for auto repair shops",
    "research_group_uuid": "uuid-from-step-1"
  }'

# Step 4: Remove irrelevant agents from the 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": [irrelevant_id_1, irrelevant_id_2, irrelevant_id_3]}'

# Step 5: Now ask questions to the curated group

7. Participant Relevance Scoring

When reviewing participant profiles after over-recruiting, score each persona using this framework:

What to Check in Profiles

The participant profile from GET /v1/research-groups/{group_id} includes:

• name - The persona's name
• occupation - Job title (primary relevance indicator)
• summary - Brief bio describing background, interests, and experience (secondary relevance indicator)
• age - Current age
• location - Geographic location

8. Removing Agents from Studies and Groups

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

Agents remain in the research group. Only their participation in this specific study is removed.

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

This permanently removes agents from the group. Use sparingly.

9. Appending to Existing Groups

Add more participants to an existing group with different or additional 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
  }'

When to Append

• The initial group lacks demographic diversity (e.g., all male, all under 30)
• You need participants from a different state or age range
• The initial recruit was too small and you need more coverage
• You want to add a specific demographic segment to a broad group

10. Building Representative Panels

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

1. Recruit initial group with broad filters (age 25-65, USA)
2. Analyse demographics (age distribution, gender balance, geographic spread)
3. Identify gaps (e.g., no one over 55, no suburban representation, all from coastal states)
4. Append targeted recruits to fill gaps (e.g., state-specific, older age range, gender filter)
5. Remove outliers or over-represented groups if needed
6. Repeat until the panel reflects the target population

11. Reusing Existing Groups

Groups persist in Ditto and can be reused across multiple studies. This is valuable when:

• Running follow-up studies on the same topic (personas maintain context within a study, but each new study starts fresh)
• Multiple contacts at the same company need the same research (store the research_study_link on the company record)
• Running iterative multi-phase research (Phase 1 discovery, Phase 2 validation)

Checking for Existing Groups

curl -s "https://app.askditto.io/v1/research-groups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for groups with descriptive names that match your target:

• State-specific voter groups: "MI State Voters", "TX State Voters"
• Industry groups: "Cybersecurity Professionals", "Healthcare Eye Care Providers"
• Broad demographic groups: "US Adults 28-45 Product Feedback"

12. Group Sizing Guidelines

13. Demographic Targeting by Use Case

CPG / Consumer Goods

B2C Tech / Product

Political / Voter Research

14. Common Errors and Solutions

15. Production Examples

Research groups from real production studies, showing the exact filters and group sizes used:

16. Frequently Asked Questions