Add Persona

POST /api/visibility/personas

Authentication: Required An account in read-only mode can't do this (it's a write) — the call returns/throws a read-only error.

Add a buyer persona that Pendium will use in future visibility scans. You have two options:

1. AI-generated (recommended): Describe the persona in a sentence or two, and Pendium expands it into a full profile with demographics, goals, pain points, and system context.
2. Manual: Provide all the fields yourself for full control.

In AI-generated mode the persona is built around the brand's current name. A former name or DBA, whether it comes from the profile's Also Known As field or still sits in the profile's competitors list, counts as the brand and is never framed as a rival in the generated context.

Request body

AI-generated (recommended):

{
  "syntheticId": 1234,
  "prompt": "technical startup founder who evaluates developer tools and cares about API quality"
}

That's it. Pendium uses AI to build the full persona from your description.

Manual:

{
  "syntheticId": 1234,
  "name": "Technical Startup Founder",
  "role": "CTO / Co-founder",
  "goals": ["Find tools that scale", "Minimize context switching"],
  "painPoints": ["Too many tools", "Integration complexity"],
  "demographics": {
    "companySize": "10-50",
    "industry": "SaaS",
    "expertiseLevel": "expert"
  }
}

When you use the prompt (AI-generated) mode, whether Pendium fills in a location is judged from the brand's stated geographic focus and what it does: a genuinely local business (a physical premises or specific service area — a restaurant, plumber, dentist, contractor, and the like) gets a location, while an online, national, or SaaS brand (or one whose focus is a broad market like "US" or "Global") stays location-free, so scans aren't skewed by an assumed "near me" context. Manual mode always stores whatever location you pass.

Example

curl -X POST https://pendium.ai/api/visibility/personas \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{
    "syntheticId": 1234,
    "prompt": "enterprise procurement manager comparing vendor options for a 500-person company"
  }'

Response

{
  "success": true,
  "persona": {
    "id": "persona-uuid-new",
    "name": "Enterprise Procurement Manager",
    "role": "Procurement Lead",
    "goals": ["Reduce vendor sprawl", "Negotiate enterprise pricing"],
    "painPoints": ["Long evaluation cycles", "Security compliance requirements"],
    "demographics": {
      "companySize": "500+",
      "industry": "Enterprise",
      "expertiseLevel": "intermediate"
    }
  },
  "_pendium": {
    "what_happened": "Persona 'Enterprise Procurement Manager' created...",
    "next_steps": ["Trigger a scan to test queries from this persona's perspective..."]
  }
}

Tips

• Be specific in your prompt. "startup founder" is okay, but "technical startup founder who evaluates developer tools and cares about API quality and documentation" gives Pendium much more to work with.
• Think about who actually buys your product. The best personas map to real customer segments — not abstract demographics.
• Add 2–4 personas. Enough to cover your key buyer types without making scans too expensive.