> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Personas

> AI personas for targeted audience insights

Personas are the core of Mavera's intelligence layer. They inject specialized audience knowledge into every AI interaction — shaping language, values, decision-making patterns, and behavioral tendencies to reflect how real demographics think and respond.

Instead of getting generic AI outputs, you get responses filtered through the lens of a specific audience: a Gen Z consumer, a B2B enterprise buyer, a health-conscious millennial, or any custom segment you define.

<Info>
  Personas work across **all** Mavera products: [Responses API](/features/responses), [Focus Groups](/features/focus-groups), and Speak. Create a persona once, reuse it everywhere.
</Info>

## Why Personas Matter

Traditional AI gives you one generic perspective. Mavera personas let you hear from the audience that actually matters to your business.

```mermaid theme={"dark"}
flowchart LR
    Q[Your Question] --> G[Generic AI]
    Q --> P1[Gen Z Persona]
    Q --> P2[B2B Buyer Persona]
    Q --> P3[Custom Persona]

    G --> R0["Generic answer"]
    P1 --> R1["Authenticity-focused,<br/>social-first response"]
    P2 --> R2["ROI-focused,<br/>integration-aware response"]
    P3 --> R3["Response tailored to<br/>your exact audience"]

    style G fill:#94a3b8,stroke:#64748b
    style P1 fill:#8b5cf6,stroke:#7c3aed
    style P2 fill:#8b5cf6,stroke:#7c3aed
    style P3 fill:#8b5cf6,stroke:#7c3aed
```

Each persona encodes:

* **Demographics** — age, location, income level, education
* **Psychographics** — values, motivations, lifestyle preferences
* **Behavioral patterns** — buying habits, media consumption, decision triggers
* **Communication style** — language register, cultural references, tone

## Persona Types

<CardGroup cols={2}>
  <Card title="Pre-built Personas" icon="users">
    50+ ready-to-use personas across generational, professional, lifestyle, industry, and expert categories. Battle-tested and immediately available.
  </Card>

  <Card title="Custom Personas" icon="user-plus">
    Define your exact target audience with three creation pipelines: North Star (simple), Intermediate (guided), and Advanced (full control).
  </Card>
</CardGroup>

## Pre-built Categories

Mavera provides 50+ pre-built personas organized into five categories. Each persona is a rich behavioral model, not just a label.

<AccordionGroup>
  <Accordion title="Generational">
    Personas based on generational cohorts, each with distinct values, media habits, and purchasing behavior.

    | Persona                         | Key Traits                                                                     |
    | ------------------------------- | ------------------------------------------------------------------------------ |
    | **Gen Z Consumer** (18–26)      | Digital native, values authenticity, social responsibility, short-form content |
    | **Gen Z Professional** (22–26)  | Career-driven, purpose-seeking, hybrid-work preference                         |
    | **Millennial Consumer** (27–42) | Experience-seeking, brand-loyal, subscription-friendly                         |
    | **Millennial Parent** (30–42)   | Safety-conscious, research-heavy, values convenience                           |
    | **Gen X Consumer** (43–58)      | Quality-focused, skeptical of trends, values reliability                       |
    | **Gen X Professional** (43–58)  | Leadership-oriented, pragmatic, prefers proven solutions                       |
    | **Baby Boomer** (59–77)         | Brand-loyal, values customer service, prefers established channels             |
    | **Silent Generation** (78+)     | Trust-driven, values simplicity, prefers personal interaction                  |
  </Accordion>

  <Accordion title="Professional">
    Personas representing different roles in business decision-making.

    | Persona                  | Key Traits                                                    |
    | ------------------------ | ------------------------------------------------------------- |
    | **B2B Decision Maker**   | ROI-focused, risk-averse, multi-stakeholder consensus builder |
    | **Startup Founder**      | Growth-obsessed, resourceful, values speed over perfection    |
    | **Enterprise CTO**       | Security-first, integration-aware, long evaluation cycles     |
    | **Marketing Director**   | Brand-conscious, data-driven, campaign-focused                |
    | **Product Manager**      | User-centric, prioritization-driven, roadmap-focused          |
    | **Small Business Owner** | Budget-conscious, wears many hats, values simplicity          |
  </Accordion>

  <Accordion title="Lifestyle">
    Personas defined by lifestyle choices and consumption patterns.

    | Persona                       | Key Traits                                                       |
    | ----------------------------- | ---------------------------------------------------------------- |
    | **Health-Conscious Consumer** | Reads labels, organic preference, fitness-oriented               |
    | **Eco-Warrior**               | Sustainability-first, willing to pay premium, activist mindset   |
    | **Budget Shopper**            | Price-comparison driven, coupon-savvy, values per-dollar         |
    | **Luxury Consumer**           | Experience-driven, brand-prestige seeking, quality over quantity |
    | **Digital Nomad**             | Location-independent, minimalist, values flexibility             |
    | **Urban Professional**        | Convenience-driven, time-scarce, delivery-dependent              |
  </Accordion>

  <Accordion title="Industry">
    Personas with deep domain knowledge in specific industries.

    | Persona                     | Key Traits                                                |
    | --------------------------- | --------------------------------------------------------- |
    | **Healthcare Professional** | Evidence-based, HIPAA-aware, patient-outcome focused      |
    | **Finance Expert**          | Risk-adjusted thinking, regulatory-aware, data-driven     |
    | **Tech Enthusiast**         | Early adopter, spec-driven, community-influenced          |
    | **Education Professional**  | Pedagogy-focused, accessibility-aware, outcomes-driven    |
    | **Real Estate Agent**       | Market-timing aware, relationship-driven, local expertise |
  </Accordion>

  <Accordion title="Expert">
    Personas that reason like domain specialists. Useful for strategic analysis and review.

    | Persona                | Key Traits                                                       |
    | ---------------------- | ---------------------------------------------------------------- |
    | **Market Analyst**     | Quantitative, trend-spotting, competitive-landscape aware        |
    | **Brand Strategist**   | Positioning-focused, narrative-driven, consumer-insight oriented |
    | **UX Researcher**      | User-empathy driven, usability-focused, evidence-based           |
    | **Growth Marketer**    | Funnel-optimizing, experiment-driven, metrics-obsessed           |
    | **Content Strategist** | Audience-first, channel-aware, narrative-arc thinking            |
  </Accordion>
</AccordionGroup>

## Listing Personas

Retrieve all available personas (pre-built and custom) for your workspace.

<CodeGroup>
  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      "https://app.mavera.io/api/v1/personas",
      headers={"Authorization": "Bearer mvra_live_your_key_here"}
  )

  personas = response.json()["data"]
  for persona in personas:
      print(f"{persona['name']} ({persona['category']})")
      print(f"  ID: {persona['id']}")
      print(f"  Custom: {persona['is_custom']}")
      print(f"  {persona['description'][:100]}...")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/personas", {
    headers: { Authorization: "Bearer mvra_live_your_key_here" },
  });

  const { data: personas } = await response.json();
  personas.forEach((persona) => {
    console.log(`${persona.name} (${persona.category})`);
    console.log(`  ID: ${persona.id}`);
    console.log(`  Custom: ${persona.is_custom}`);
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/personas \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```
</CodeGroup>

### Filtering by Category

```python theme={"dark"}
response = requests.get(
    "https://app.mavera.io/api/v1/personas",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    params={"category": "Generational"}
)
```

### Persona Response Object

```json theme={"dark"}
{
  "id": "persona_abc123",
  "name": "Gen Z Consumer",
  "category": "Generational",
  "description": "Digital native aged 18-26 who values authenticity, social responsibility, and personalized experiences.",
  "is_custom": false,
  "is_expert": false,
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Using Personas

### In the Responses API

Pass `persona_id` to shape AI responses through the persona's lens.

<CodeGroup>
  ```python Python theme={"dark"}
  from openai import OpenAI

  client = OpenAI(
      api_key="mvra_live_your_key_here",
      base_url="https://app.mavera.io/api/v1",
  )

  response = client.responses.create(
      model="mavera-1",
      input=[
          {"role": "user", "content": "What makes a brand authentic?"}
      ],
      extra_body={"persona_id": "gen_z_consumer"},
  )

  print(response.output[0].content[0].text)
  ```

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "mvra_live_your_key_here",
    baseURL: "https://app.mavera.io/api/v1",
  });

  const response = await client.responses.create({
    model: "mavera-1",
    input: [
      { role: "user", content: "What makes a brand authentic?" },
    ],
    persona_id: "gen_z_consumer",
  });

  console.log(response.output[0].content[0].text);
  ```
</CodeGroup>

### In Focus Groups

Supply multiple `persona_ids` to simulate diverse audience panels.

```python theme={"dark"}
response = requests.post(
    "https://app.mavera.io/api/v1/focus-groups",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "name": "Brand Perception Study",
        "sample_size": 50,
        "persona_ids": [
            "gen_z_consumer",
            "millennial_professional",
            "gen_x_parent",
            "luxury_consumer"
        ],
        "questions": [
            {
                "question": "How likely are you to recommend this brand?",
                "type": "NPS",
                "order": 1
            }
        ],
        "workspace_id": "your_workspace_id"
    }
)
```

### In Speak (Video)

Attach a persona to video-generation requests for audience-specific delivery.

```python theme={"dark"}
response = requests.post(
    "https://app.mavera.io/api/v1/speak",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "text": "Introducing our new sustainable product line...",
        "persona_id": "eco_warrior",
        "workspace_id": "your_workspace_id"
    }
)
```

## Creating Custom Personas

When pre-built personas don't match your exact target audience, create a custom one. Mavera offers three creation pipelines with increasing levels of control.

```mermaid theme={"dark"}
flowchart TD
    Start[Need a Custom Persona] --> Q{How much control?}

    Q -->|Minimal input| NS[North Star Pipeline]
    Q -->|Some guidance| IM[Intermediate Pipeline]
    Q -->|Full control| ADV[Advanced Pipeline]

    NS -->|Name + Description| AI1[AI generates full profile]
    IM -->|Goals, Pains, Stage| AI2[AI enriches with psychographics]
    ADV -->|Everything specified| AI3[AI validates & fills gaps]

    AI1 --> Done[Persona Ready]
    AI2 --> Done
    AI3 --> Done

    style NS fill:#8b5cf6,stroke:#7c3aed
    style IM fill:#8b5cf6,stroke:#7c3aed
    style ADV fill:#8b5cf6,stroke:#7c3aed
```

### North Star (Simplest)

Provide a name and description — AI generates the complete behavioral profile.

<CodeGroup>
  ```python Python theme={"dark"}
  response = requests.post(
      "https://app.mavera.io/api/v1/personas",
      headers={"Authorization": "Bearer mvra_live_your_key_here"},
      json={
          "pipeline_type": "NORTH_STAR",
          "name": "Sustainable Fashion Buyer",
          "description": "Eco-conscious millennial interested in sustainable fashion, shops primarily online, values transparency in supply chains",
          "workspace_id": "your_workspace_id"
      }
  )

  persona = response.json()
  print(f"Created persona: {persona['id']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/personas", {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pipeline_type: "NORTH_STAR",
      name: "Sustainable Fashion Buyer",
      description: "Eco-conscious millennial interested in sustainable fashion, shops primarily online, values transparency in supply chains",
      workspace_id: "your_workspace_id",
    }),
  });

  const persona = await response.json();
  console.log(`Created persona: ${persona.id}`);
  ```
</CodeGroup>

<Tip>
  Include specific details in the description for better results. "Eco-conscious millennial who shops online and values supply chain transparency" produces a richer persona than "someone who likes sustainability."
</Tip>

### Intermediate (Guided)

A 3-step process with explicit goals, pain points, and buying stage.

<CodeGroup>
  ```python Python theme={"dark"}
  response = requests.post(
      "https://app.mavera.io/api/v1/personas",
      headers={"Authorization": "Bearer mvra_live_your_key_here"},
      json={
          "pipeline_type": "INTERMEDIATE",
          "name": "Enterprise IT Buyer",
          "persona_type": "B2B",
          "buying_stage": "SOLUTION_AWARE",
          "decision_role": "ECONOMIC_BUYER",
          "goals": ["Reduce IT costs by 20%", "Improve security posture", "Consolidate vendors"],
          "pains": ["Budget constraints", "Integration complexity", "Compliance requirements"],
          "workspace_id": "your_workspace_id"
      }
  )
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/personas", {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pipeline_type: "INTERMEDIATE",
      name: "Enterprise IT Buyer",
      persona_type: "B2B",
      buying_stage: "SOLUTION_AWARE",
      decision_role: "ECONOMIC_BUYER",
      goals: ["Reduce IT costs by 20%", "Improve security posture", "Consolidate vendors"],
      pains: ["Budget constraints", "Integration complexity", "Compliance requirements"],
      workspace_id: "your_workspace_id",
    }),
  });
  ```
</CodeGroup>

**Buying stage options:** `UNAWARE`, `PROBLEM_AWARE`, `SOLUTION_AWARE`, `PRODUCT_AWARE`, `DECISION`

**Decision role options:** `ECONOMIC_BUYER`, `CHAMPION`, `TECHNICAL_BUYER`, `END_USER`, `GATEKEEPER`

### Advanced (Full Control)

Complete customization with psychographics, tech stack, channels, and triggers.

<CodeGroup>
  ```python Python theme={"dark"}
  response = requests.post(
      "https://app.mavera.io/api/v1/personas",
      headers={"Authorization": "Bearer mvra_live_your_key_here"},
      json={
          "pipeline_type": "ADVANCED",
          "name": "SMB SaaS Buyer",
          "persona_type": "B2B",
          "role_title": "Operations Manager",
          "company_size": "SMB_51_200",
          "buying_stage": "DECISION",
          "decision_role": "CHAMPION",
          "budget_authority": "RECOMMENDER",
          "goals": ["Automate workflows", "Scale operations", "Reduce manual errors"],
          "pains": ["Manual processes", "Team bandwidth", "Tool sprawl"],
          "triggers": ["Growth phase", "New funding round", "Key employee departure"],
          "channels": ["LinkedIn", "Industry podcasts", "Peer recommendations", "G2 reviews"],
          "tech_stack": ["Slack", "HubSpot", "Notion", "Zapier"],
          "workspace_id": "your_workspace_id"
      }
  )
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/personas", {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pipeline_type: "ADVANCED",
      name: "SMB SaaS Buyer",
      persona_type: "B2B",
      role_title: "Operations Manager",
      company_size: "SMB_51_200",
      buying_stage: "DECISION",
      decision_role: "CHAMPION",
      budget_authority: "RECOMMENDER",
      goals: ["Automate workflows", "Scale operations", "Reduce manual errors"],
      pains: ["Manual processes", "Team bandwidth", "Tool sprawl"],
      triggers: ["Growth phase", "New funding round", "Key employee departure"],
      channels: ["LinkedIn", "Industry podcasts", "Peer recommendations", "G2 reviews"],
      tech_stack: ["Slack", "HubSpot", "Notion", "Zapier"],
      workspace_id: "your_workspace_id",
    }),
  });
  ```
</CodeGroup>

<Info>
  Custom persona creation costs **300 credits**. Personas are permanent and reusable across all API calls at no additional cost.
</Info>

## Single vs Multi-Persona Strategies

Choosing between one persona and several depends on your research goal.

| Strategy                     | When to Use                                              | Example                                                    |
| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| **Single persona**           | You have a clear target audience and want depth          | "How would a Gen Z consumer react to this ad?"             |
| **Multi-persona comparison** | You need to compare reactions across segments            | Chat with 3 different personas and compare answers         |
| **Focus Group panel**        | You need quantitative + qualitative data at scale        | Run a Focus Group with 4 personas, N=50                    |
| **Expert + audience pair**   | You want strategic analysis grounded in audience reality | Ask a Brand Strategist, then validate with a Gen Z persona |

### Multi-Persona Comparison in Code

<CodeGroup>
  ```python Python theme={"dark"}
  from openai import OpenAI

  client = OpenAI(
      api_key="mvra_live_your_key_here",
      base_url="https://app.mavera.io/api/v1",
  )

  personas = {
      "Gen Z": "gen_z_consumer",
      "Millennial": "millennial_consumer",
      "Gen X": "gen_x_consumer",
  }

  question = "Would you pay a premium for sustainable packaging?"

  for label, persona_id in personas.items():
      response = client.responses.create(
          model="mavera-1",
          input=[{"role": "user", "content": question}],
          extra_body={"persona_id": persona_id},
      )
      print(f"\n--- {label} ---")
      print(response.output[0].content[0].text[:300])
  ```

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "mvra_live_your_key_here",
    baseURL: "https://app.mavera.io/api/v1",
  });

  const personas = {
    "Gen Z": "gen_z_consumer",
    "Millennial": "millennial_consumer",
    "Gen X": "gen_x_consumer",
  };

  const question = "Would you pay a premium for sustainable packaging?";

  for (const [label, personaId] of Object.entries(personas)) {
    const response = await client.responses.create({
      model: "mavera-1",
      input: [{ role: "user", content: question }],
      persona_id: personaId,
    });
    console.log(`\n--- ${label} ---`);
    console.log(response.output[0].content[0].text.slice(0, 300));
  }
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Match persona to use case">
    Use **generational** personas for consumer insights, **professional** personas for B2B research, **expert** personas for strategic analysis, and **lifestyle** personas for psychographic segmentation. Don't use a CTO persona to test consumer messaging.
  </Accordion>

  <Accordion title="Layer personas with system prompts">
    Persona intelligence is most powerful when combined with a clear task. "You are a market researcher interviewing this persona about brand loyalty" produces richer results than a bare question.
  </Accordion>

  <Accordion title="Create custom personas for niche audiences">
    If your target audience isn't covered by pre-built personas, invest the 300 credits to create a custom one. The Advanced pipeline gives you full control over psychographics and behavioral triggers.
  </Accordion>

  <Accordion title="Reuse personas across products">
    A persona created for Chat also works in Focus Groups and Speak. Build your persona library once and leverage it across all Mavera products.
  </Accordion>

  <Accordion title="Start broad, then narrow">
    Begin with a pre-built persona to validate your research direction, then create a custom persona for precision. This saves credits during the exploratory phase.
  </Accordion>

  <Accordion title="Use analysis mode to quantify differences">
    When comparing personas, enable `analysis_mode` in Chat to get confidence scores and emotional analysis. This turns qualitative comparisons into quantifiable data.
  </Accordion>
</AccordionGroup>

<Warning>
  Personas simulate audience perspectives based on behavioral models — they are not real people. Use persona outputs as directional input for research, not as definitive audience data. Always validate critical business decisions with real user research.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Responses API" icon="message" href="/features/responses">
    Use personas in the Responses API
  </Card>

  <Card title="Focus Groups" icon="users" href="/features/focus-groups">
    Run persona-powered synthetic focus groups
  </Card>

  <Card title="Persona Selection Cookbook" icon="book" href="/cookbooks/persona-selection">
    Choose the right personas by use case
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/personas/list-personas">
    Full API specification for persona endpoints
  </Card>
</CardGroup>