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

# Salesforce

> 8 production-ready jobs — CRM-to-persona pipelines, deal-stage focus groups, account intelligence, brand voice extraction, lead scoring validation, pipeline content, competitive battle cards, and QBR prep

Salesforce holds your richest buyer data — contacts, opportunities, accounts, notes, cases. These eight jobs pull that data through Mavera's surfaces (Personas, Focus Groups, Mave Agent, Brand Voices, Generations) so every campaign, battle card, and QBR is grounded in real CRM intelligence.

```mermaid theme={"dark"}
flowchart LR
  subgraph SF["Salesforce CRM"]
    Contacts
    Opportunities
    Accounts
    Notes
    Leads
    Cases
  end

  subgraph MV["Mavera"]
    CustomPersonas["Custom Personas"]
    FocusGroups["Focus Groups"]
    MaveAgent["Mave Agent"]
    BrandVoice["Brand Voice"]
    Generate
    Chat
  end

  subgraph OUT["Outputs"]
    PersonaLibrary["Persona Library"]
    WinLossReports["Win/Loss Reports"]
    IntelBriefs["Intelligence Briefs"]
    BattleCards["Battle Cards"]
    NurtureContent["Nurture Content"]
    QBRPrep["QBR Prep"]
  end

  Contacts --> CustomPersonas
  Opportunities --> FocusGroups
  Opportunities --> Generate
  Accounts --> MaveAgent
  Notes --> BrandVoice
  Leads --> FocusGroups
  Cases --> Chat

  CustomPersonas --> PersonaLibrary
  FocusGroups --> WinLossReports
  MaveAgent --> IntelBriefs
  MaveAgent --> BattleCards
  BrandVoice --> NurtureContent
  Generate --> NurtureContent
  Chat --> QBRPrep
```

***

## API Reference Card

| Detail          | Value                                                                    |
| --------------- | ------------------------------------------------------------------------ |
| **Base URL**    | `https://{your-domain}.my.salesforce.com/services/data/v66.0/`           |
| **Auth**        | OAuth 2.0 — Web Server flow, JWT Bearer, or Client Credentials           |
| **Rate limits** | 100,000 requests / rolling 24 h (Enterprise); 25 concurrent long-running |
| **Mavera base** | `https://app.mavera.io/api/v1`                                           |
| **Mavera auth** | `Authorization: Bearer mvra_live_...`                                    |

<Info>
  All examples use three environment variables: `SALESFORCE_INSTANCE` (e.g. `yourorg.my.salesforce.com`), `SALESFORCE_ACCESS_TOKEN`, and `MAVERA_API_KEY`. Store them in your secret manager — never commit tokens.
</Info>

***

## Jobs Directory

| # | Job                                                                                       | Description                                                                    |
| - | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 1 | [CRM-to-Persona Pipeline](/integrations/salesforce/crm-to-persona-pipeline)               | Pull contacts via SOQL, group by title/industry, create data-grounded personas |
| 2 | [Deal-Stage Focus Group](/integrations/salesforce/deal-stage-focus-group)                 | Win/loss analysis via synthetic focus groups mapped to opportunity stages      |
| 3 | [Account Intelligence Brief](/integrations/salesforce/account-intelligence-brief)         | AI research briefs from Account, Contact, and Task data                        |
| 4 | [Sales Note → Brand Voice](/integrations/salesforce/sales-note-brand-voice)               | Extract winning language from Closed Won deal notes into a Brand Voice profile |
| 5 | [Lead Scoring Validation](/integrations/salesforce/lead-scoring-validation)               | Validate lead scoring models with synthetic focus group feedback               |
| 6 | [Pipeline-Aware Content Generation](/integrations/salesforce/pipeline-content-generation) | Generate stage-specific nurture content tied to your real pipeline             |
| 7 | [Competitive Displacement Tracker](/integrations/salesforce/competitive-displacement)     | AI-generated battle cards from competitor mentions in opportunities            |
| 8 | [Customer Success Interview Prep](/integrations/salesforce/cs-interview-prep)             | QBR prep documents from Account health, Cases, and Activities                  |

<CardGroup cols={2}>
  <Card title="CRM-to-Persona Pipeline" icon="users" href="/integrations/salesforce/crm-to-persona-pipeline">
    Pull contacts via SOQL, group by title/industry, create data-grounded personas
  </Card>

  <Card title="Deal-Stage Focus Group" icon="comments" href="/integrations/salesforce/deal-stage-focus-group">
    Win/loss analysis via synthetic focus groups mapped to opportunity stages
  </Card>

  <Card title="Account Intelligence Brief" icon="brain" href="/integrations/salesforce/account-intelligence-brief">
    AI research briefs from Account, Contact, and Task data
  </Card>

  <Card title="Sales Note → Brand Voice" icon="microphone" href="/integrations/salesforce/sales-note-brand-voice">
    Extract winning language from Closed Won deal notes into a Brand Voice profile
  </Card>

  <Card title="Lead Scoring Validation" icon="chart-bar" href="/integrations/salesforce/lead-scoring-validation">
    Validate lead scoring models with synthetic focus group feedback
  </Card>

  <Card title="Pipeline-Aware Content Generation" icon="file-lines" href="/integrations/salesforce/pipeline-content-generation">
    Generate stage-specific nurture content tied to your real pipeline
  </Card>

  <Card title="Competitive Displacement Tracker" icon="crosshairs" href="/integrations/salesforce/competitive-displacement">
    AI-generated battle cards from competitor mentions in opportunities
  </Card>

  <Card title="Customer Success Interview Prep" icon="clipboard-check" href="/integrations/salesforce/cs-interview-prep">
    QBR prep documents from Account health, Cases, and Activities
  </Card>
</CardGroup>

***

## Production Tips

<Tip>
  **Token refresh** — Access tokens expire. Use the OAuth 2.0 refresh token flow or JWT Bearer for server-to-server jobs. Never hardcode tokens.
</Tip>

<Warning>
  **Rate limit budgeting** — Enterprise orgs get 100,000 API calls per rolling 24 hours. Each SOQL query counts as one call. Batch queries and cache responses. Monitor usage at `GET /services/data/v66.0/limits`.
</Warning>

<Info>
  **SOQL pagination** — Queries returning more than 2,000 rows include a `nextRecordsUrl` field. Follow it until `done: true`:

  ```python theme={"dark"}
  results = []
  url = f"https://{SF}/services/data/v66.0/query?q={soql}"
  while url:
      resp = requests.get(url, headers=SF_HEADERS).json()
      results.extend(resp["records"])
      url = resp.get("nextRecordsUrl")
      if url:
          url = f"https://{SF}{url}"
  ```
</Info>

**Error handling checklist:**

| Error                   | Cause                               | Fix                                                    |
| ----------------------- | ----------------------------------- | ------------------------------------------------------ |
| `401 Unauthorized`      | Expired or invalid SF token         | Refresh via OAuth; check Connected App scopes          |
| `403 Forbidden`         | User lacks object/field permissions | Verify profile permissions; check field-level security |
| `429 Too Many Requests` | Rate limit exceeded                 | Back off exponentially; check `/limits` endpoint       |
| `400 MALFORMED_QUERY`   | SOQL syntax error                   | Validate query in Developer Console first              |
| `INVALID_FIELD`         | Custom field API name wrong         | Use `Describe` endpoint to verify field names          |
| Mavera `401`            | Invalid or expired API key          | Rotate key at app.mavera.io/settings                   |
| Mavera `422`            | Malformed request body              | Check required fields in API docs                      |

**Concurrency** — Salesforce allows 25 concurrent long-running requests. For batch jobs across hundreds of accounts, use a semaphore or queue (`asyncio.Semaphore(25)` in Python, `p-limit(25)` in Node).

**Custom field discovery** — Not sure if `Competitor__c` or `Health_Score__c` exists in your org? Use the Describe endpoint:

```
GET /services/data/v66.0/sobjects/Opportunity/describe
```

***

## What's Next

<CardGroup cols={2}>
  <Card title="HubSpot Integration" icon="envelope-open" href="/integrations/hubspot">
    8 jobs — lifecycle personas, deal replay, meeting analysis
  </Card>

  <Card title="Personas API" icon="users" href="/api-reference/personas">
    Full reference for POST /api/v1/personas
  </Card>

  <Card title="Focus Groups API" icon="comments" href="/api-reference/focus-groups">
    Full reference for POST /api/v1/focus-groups
  </Card>

  <Card title="Mave Agent" icon="brain" href="/api-reference/mave">
    Full reference for POST /api/v1/mave/chat
  </Card>
</CardGroup>