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

# Setup

> Connect HubSpot CRM to Ravenna using OAuth 2.0 with read scopes for deals, companies, contacts, and tickets to power agent CRM lookups.

<Info>Connect to HubSpot CRM using OAuth 2.0</Info>

This guide walks you through connecting your HubSpot account to Ravenna for CRM data access.

## Prerequisites

Before you begin, ensure you have:

* A HubSpot account with CRM access
* Admin or super admin permissions in HubSpot
* Organization admin access in Ravenna

## Required permissions

The HubSpot integration requires the following OAuth scopes:

| Scope                        | Purpose                           |
| ---------------------------- | --------------------------------- |
| `crm.objects.deals.read`     | Access deal data                  |
| `crm.objects.companies.read` | Access company data               |
| `crm.objects.contacts.read`  | Access contact data               |
| `crm.objects.owners.read`    | Access owner/user data            |
| `crm.objects.users.read`     | Access user information           |
| `crm.schemas.deals.read`     | Read deal property definitions    |
| `crm.schemas.companies.read` | Read company property definitions |
| `crm.schemas.contacts.read`  | Read contact property definitions |
| `settings.users.read`        | Read user settings                |
| `settings.users.teams.read`  | Read team information             |

<Note>
  These are read-only permissions. Ravenna does not create, modify, or delete any data in your HubSpot account.
</Note>

## Setup guide

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **HubSpot** in the CRM section
  </Step>

  <Step title="Start OAuth flow">
    Click **Connect with HubSpot** to begin the authorization process.

    You'll be redirected to HubSpot to authorize the connection.
  </Step>

  <Step title="Authorize access">
    1. Sign in to HubSpot if prompted
    2. Select the HubSpot account you want to connect
    3. Review the requested permissions
    4. Click **Connect app** to authorize Ravenna

    <Warning>
      Make sure you select the correct HubSpot portal if you have access to multiple accounts.
    </Warning>
  </Step>

  <Step title="Complete setup">
    After authorization, you'll be redirected back to Ravenna. The integration will:

    1. Validate the OAuth tokens
    2. Fetch your HubSpot portal information
    3. Enable HubSpot agent tools

    You'll see a confirmation that HubSpot is connected.
  </Step>
</Steps>

## Enable agent tools

After connecting HubSpot, enable the tools on your AI agents:

<Steps>
  <Step title="Navigate to agent settings">
    Go to **Settings > AI > Agents** or your workspace agent configuration.
  </Step>

  <Step title="Enable HubSpot tools">
    Toggle on the HubSpot tools you want your agent to use:

    * **List Deals** - For browsing recent deals
    * **Search Deals** - For filtered deal queries
    * **Get Deal** - For detailed deal information
    * **Search Companies** - For company lookups
    * **List Owners** - For owner/user lookups
    * **Search Contacts** - For contact lookups
  </Step>

  <Step title="Test the integration">
    Try asking your agent questions like:

    * "Show me recent deals"
    * "What are our high priority deals?"
    * "Find deals for ABC Company"
    * "Who owns the XYZ deal?"
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth authorization failed" icon="circle-x">
    **Cause**: Authorization was denied or failed during the OAuth flow

    **Solution**:

    * Ensure you have admin permissions in HubSpot
    * Check that you selected the correct HubSpot portal
    * Try the connection process again
    * Clear browser cookies and cache if issues persist
  </Accordion>

  <Accordion title="Insufficient permissions" icon="shield-x">
    **Cause**: Your HubSpot user doesn't have access to required CRM data

    **Solution**:

    * Verify you have CRM access in your HubSpot account
    * Check with your HubSpot admin about user permissions
    * Ensure the connected portal has the required HubSpot subscription tier
  </Accordion>

  <Accordion title="No deals found" icon="folder-open">
    **Cause**: The search returned no results

    **Solution**:

    * Verify deals exist in your HubSpot account
    * Check that the search filters match existing data
    * Try broader search criteria
    * Ensure the connected HubSpot portal is the correct one
  </Accordion>

  <Accordion title="Company associations missing" icon="building">
    **Cause**: Deals don't have associated companies in HubSpot

    **Solution**:

    * Associate companies with deals in HubSpot
    * Check that company records exist in your HubSpot account
    * Verify associations are set up correctly in HubSpot
  </Accordion>

  <Accordion title="Token expired error" icon="clock">
    **Cause**: OAuth access token has expired

    **Solution**:

    * Ravenna automatically refreshes tokens, but if issues persist:
    * Disconnect and reconnect the HubSpot integration
    * Check that your HubSpot account is still active
  </Accordion>
</AccordionGroup>

## Data access

<Info>
  Ravenna accesses HubSpot data in real-time. There is no data sync or storage of your CRM data in Ravenna.
</Info>

When an agent uses HubSpot tools:

1. The query is sent to HubSpot's API
2. Results are returned and formatted for the agent
3. The agent uses the data to answer the user's question
4. No CRM data is stored in Ravenna