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

# CRM Integrations

> Connect HubSpot or Attio to pull contacts directly into Demomatic for personalized demo generation.

Connect your CRM to Demomatic to pull contacts and use them as recipients when generating personalized demos. Demomatic supports **HubSpot** and **Attio**.

<Info>
  CRM integrations are available on the **starter** and **growth** plans. They are not available on solo or free plans.
</Info>

## How it works

Once you connect a CRM, you can search for contacts from the demo generation UI or pass them through the API. Demomatic uses the contact details — name, job title, company, and industry — to personalize the video narration and on-screen text.

## Connect HubSpot

The connection uses OAuth. Demomatic handles the token exchange; you only need to redirect the user to the authorize URL and handle the return.

<Steps>
  <Step title="Start the OAuth flow">
    Redirect the user to the Demomatic HubSpot authorize endpoint. Replace `{account_id}` with your Demomatic account ID and `{redirect_uri}` with the page you want to send the user to after connecting.

    ```
    GET /integrations/oauth/hubspot/authorize?account_id={account_id}&redirect_uri={redirect_uri}
    ```

    Demomatic redirects the user to HubSpot, where they approve the connection. HubSpot then redirects back to Demomatic, which stores the tokens and forwards the user to your `redirect_uri`.
  </Step>

  <Step title="Handle the return">
    On your `redirect_uri` page, check the query parameters to determine the outcome:

    * **Success:** `?connected=hubspot`
    * **Error:** `?integration_error=<code>` (e.g. `invalid_state`, `token_exchange_failed`, `plan_not_allowed`)

    ```javascript theme={null}
    const params = new URLSearchParams(window.location.search);
    const connected = params.get('connected');       // 'hubspot' | null
    const error = params.get('integration_error');   // error code | null

    if (connected === 'hubspot') {
      // show success message
    }
    if (error) {
      // show error message
    }

    // clear the query string so a refresh doesn't repeat the message
    window.history.replaceState({}, '', window.location.pathname);
    ```
  </Step>
</Steps>

## Connect Attio

The Attio flow works the same way as HubSpot:

<Steps>
  <Step title="Start the OAuth flow">
    Redirect the user to the Attio authorize endpoint:

    ```
    GET /integrations/oauth/attio/authorize?account_id={account_id}&redirect_uri={redirect_uri}
    ```
  </Step>

  <Step title="Handle the return">
    Check for `?connected=attio` or `?integration_error=<code>` on your `redirect_uri` page.
  </Step>
</Steps>

## List connected integrations

Retrieve all active CRM connections for an account:

```bash theme={null}
curl "https://api.demomatic.tech/integrations/connections?account_id=99" \
  -H "Authorization: Bearer dm_your_key_here"
```

Response:

```json theme={null}
{
  "data": [
    { "id": 1, "provider": "hubspot", "date_created": "2025-01-15T10:00:00.000Z" },
    { "id": 2, "provider": "attio",   "date_created": "2025-02-20T14:30:00.000Z" }
  ]
}
```

## Disconnect an integration

Delete a connection by its `id`:

```bash theme={null}
curl -X DELETE https://api.demomatic.tech/integrations/connections/1 \
  -H "Authorization: Bearer dm_your_key_here"
```

## Search contacts

Once a CRM is connected, search for contacts by name or email:

```bash theme={null}
curl "https://api.demomatic.tech/integrations/contacts?account_id=99&provider=hubspot&q=sarah&limit=25" \
  -H "Authorization: Bearer dm_your_key_here"
```

| Parameter    | Description                                              |
| ------------ | -------------------------------------------------------- |
| `account_id` | Your Demomatic account ID.                               |
| `provider`   | `"hubspot"` or `"attio"`.                                |
| `q`          | Search query (name or email).                            |
| `limit`      | Maximum number of results (default `25`, maximum `100`). |

### Contact shape

Each contact in the response follows this structure:

```typescript theme={null}
interface CrmContact {
  id: string;
  provider: 'hubspot' | 'attio';
  email: string | null;
  name: string | null;
  displayName: string;
}
```

## Use contacts in video generation

Pass contacts retrieved from your CRM into a video generation request. Demomatic personalizes the narration and on-screen text for each recipient:

```bash theme={null}
curl -X POST https://api.demomatic.tech/v1/videos/42 \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Show how to set up automated reporting",
    "font": "Poppins",
    "captions": true,
    "bRoll": true,
    "contacts": [
      {
        "name": "Sarah Kim",
        "email": "sarah@example.com",
        "jobTitle": "VP of Sales",
        "company": "Acme Corp",
        "industry": "SaaS"
      }
    ]
  }'
```

For a full list of contact fields, see [Generating Demos](/guides/generating-demos#personalizing-demos-with-recipient-contacts).