> ## 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.

# Typeform

> Integrate Mavera with Typeform — survey-to-persona discovery, open-ended theme analysis, NPS-tiered messaging, and real vs synthetic calibration

## Overview

Pull data from **Typeform** (Form Responses, Open-Ended Answers, NPS Scores) → analyze with **Mavera** (Custom Personas, Focus Groups, Chat, Mave Agent) → discover audience segments from real survey data, extract themes from qualitative responses, test NPS-tiered messaging, and calibrate synthetic vs real research.

<Info>
  **Typeform API** — Base URL: `https://api.typeform.com/`. Auth: Bearer Token or OAuth 2.0. Rate limits: **2 req/sec** (strict). Responses endpoint returns up to 1,000 items per page with cursor pagination.
</Info>

***

## Prerequisites

<Steps>
  <Step title="Typeform access token">Create a [Personal Access Token](https://www.typeform.com/developers/get-started/personal-access-token/) with scopes: `forms:read`, `responses:read`.</Step>
  <Step title="Mavera API key">Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).</Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export TYPEFORM_TOKEN="tfp_xxxxx"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                                   | Typeform Data            | Mavera Surface         | Output                       |
| - | --------------------------------------------------------------------- | ------------------------ | ---------------------- | ---------------------------- |
| 1 | [Survey Response → Persona Discovery](survey-persona-discovery)       | Form responses           | Mave Agent + Personas  | Discovered audience segments |
| 2 | [Open-Ended Response → Focus Group Questions](open-ended-focus-group) | Open-ended answers       | Chat + Focus Groups    | Theme-targeted focus groups  |
| 3 | [NPS Response → Brand Voice Impact](nps-brand-voice)                  | NPS scores + qualitative | Focus Groups           | NPS-tier messaging           |
| 4 | [Typeform × Mavera A/B Research](mavera-calibration)                  | Parallel survey data     | Focus Groups + Compare | Calibration data             |

***

***

## Overall Calibration Score: 74/100

### Theme Overlap

* "Biggest challenge": 82% overlap. Both identified tool sprawl, manual
  reporting, and team alignment. Real humans also mentioned "burnout"
  and "manager expectations" — more emotional/personal themes.

* "Describe our product": 68% overlap. Synthetics were more polished
  ("an integrated platform for..."). Real humans used informal language
  ("it's like Notion but for marketing data").

### Sentiment Alignment

* Positive sentiment: Strong match (89%)
* Negative sentiment: Moderate match (61%). Real detractors are more
  visceral ("this thing crashes every Tuesday"). Synthetics are more
  measured and constructive.

### Specificity Gap

* Real responses include specific numbers ("took 3 weeks to onboard",
  "\$12K over budget"). Synthetics tend toward ranges and generalities.

### Blind Spots

1. Internal politics — Real: "My VP doesn't believe in data"
2. Personal frustration — Real: "I'm the only one who knows how to use it"
3. Competitor-specific comparisons — Real: "Mixpanel does this better"

### Recommendations

✅ Safe to delegate: Feature feedback, value prop testing, message ranking
⚠️ Use with caution: Pricing research, competitive positioning
❌ Needs real humans: Emotional/personal topics, internal politics, burnout

### Per-Question Reliability

| Question                | Calibration Score |
| ----------------------- | ----------------- |
| Biggest challenge       | 78/100            |
| Describe product        | 72/100            |
| What nearly stopped you | 69/100            |
| Onboarding rating       | 81/100            |
| Change one thing        | 71/100            |

```

### Error Handling

<AccordionGroup>
  <Accordion title="Question matching between platforms">The code matches Typeform fields to shared questions by partial string comparison. If Typeform question wording differs slightly, adjust the matching threshold or use explicit field ID mapping.</Accordion>
  <Accordion title="Sample size imbalance">Real surveys may have 500+ responses while Focus Groups produce 5-15. The comparison accounts for this, but note that synthetic responses represent archetypes, not statistical distributions.</Accordion>
  <Accordion title="Calibration drift over time">Run this calibration quarterly. As your product and audience evolve, the accuracy of synthetic personas may change. Track calibration scores over time.</Accordion>
  <Accordion title="Typeform survey must exist first">This job assumes you've already deployed the Typeform survey with the shared questions. Create the Typeform first, collect responses, then run the comparison.</Accordion>
</AccordionGroup>

---

## Rate Limits & Production Notes

| Endpoint | Limit | Strategy |
|----------|-------|----------|
| Form structure | 2 req/sec | Cache form definition locally |
| Responses (paginated) | 2 req/sec | 600ms delay; max 1,000/page |
| All Typeform endpoints | 2 req/sec (shared) | Strict — throttle all calls |

<Warning>
Typeform's **2 req/sec** limit is the strictest among survey platforms. A form with 3,000 responses needs 3 paginated calls — budget 2+ seconds between each. Cache form definitions and responses locally for repeated analysis.
</Warning>

**Production checklist:**

- Store `TYPEFORM_TOKEN` and `MAVERA_API_KEY` in a secrets manager.
- Cache form definitions — they rarely change and each lookup costs a rate-limited request.
- For large surveys (5,000+ responses), download responses incrementally using the `since` parameter to avoid re-fetching all data.
- The calibration job (Job 4) requires a deployed Typeform survey with responses. Plan for 1-2 weeks of real data collection before running the comparison.
- Monitor Mavera credits at [Dashboard](https://app.mavera.io/settings/usage).

---

<CardGroup cols={3}>
  <Card title="All Integrations" icon="plug" href="/integrations" />
  <Card title="Typeform API" icon="square-check" href="https://www.typeform.com/developers/" />
  <Card title="Personas" icon="user" href="/features/personas" />
  <Card title="Focus Groups" icon="users" href="/features/focus-groups" />
  <Card title="Mave Agent" icon="brain" href="/features/mave-agent" />
  <Card title="Chat" icon="comments" href="/features/chat" />
</CardGroup>
```