Skip to content
Synthetic Users

Personas

A persona is the lens the synthetic user looks through. Same staging URL, same task, different persona → very different reports.

Library personas (read-only)

Your account comes with a set of ready-made personas curated by our team. Default is a neutral voice for a baseline review; the rest are specific people with specific frustrations:

  • Default — a general first-time visitor
  • Pat — small consulting firm owner
  • Maya — restaurant manager
  • Devon — junior backend developer
  • Sam — non-technical executive at a 50-person company
  • Riley — frustrated power user
  • Jordan — anxious first-time user
  • Kai — crypto trader and hobbyist developer
  • Avery — solo freelance designer
  • Morgan — healthcare administrator
  • Logan — marketing operations lead

List the current set (with their ids) any time by calling GET /personas.

Terminal window
curl -s "$API_URL/personas" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  | jq '.items[] | select(.source == "library") | { id, name }'

You cannot edit library personas. To customise, create your own.

Custom personas

Custom personas are owned by your customer and CRUD-able through the dashboard or API.

Terminal window
curl -s -X POST "$API_URL/personas" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mid-market HR director",
    "role_description": "Heads HR ops at a 200-person company. Owns the budget.",
    "technical_sophistication": "low",
    "patience_level": "medium",
    "goals": ["Reduce onboarding time", "Audit SOC 2 compliance"],
    "pain_points": ["Spreadsheet sprawl", "Compliance docs scattered"],
    "current_tools": ["BambooHR", "Notion", "Slack"]
  }'

The system generates a synthesized_prompt from these structured fields and pins it when you create the persona. Refining the field definitions later won’t retroactively change how your existing personas behave.

An official SDK is planned. For now, call the REST API directly (the curl example above works from any language’s HTTP client).

Picking the right voice

Choose by who you’re shipping for, not who you wish you were shipping for. If your product is a developer tool but your buyer is the CTO, run both — contradictions across personas are themselves a signal.

A practical rule: if you can’t picture the persona getting confused, you’re holding the persona wrong. Real users get confused. Pick a voice that will too.

Editing a custom persona

Terminal window
curl -s -X PATCH "$API_URL/personas/<id>" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "patience_level": "low" }'

PATCH regenerates synthesized_prompt. Existing run reports are unaffected because the prompt is captured into the transcript at run time.