HubSpot CRM Integration API

Developer guide for connecting and querying your HubSpot CRM through the Yardee Vector API using Private App Tokens. Real-time access to contacts, deals, companies, and tickets.

Get Your Free API Key Learn More

HubSpot Connection Management

Connect and manage HubSpot CRM integrations for real-time querying.

Add HubSpot Connection

Connect your HubSpot CRM using a Private App Token for secure API access.

POST /api/v1/knowledgebases/{id}/connections/

curl -X POST https://app.yardee.ai/api/v1/knowledgebases/123/connections/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_type": "hubspot",
    "auth_type": "private_app",
    "hubspot_private_app_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "nickname": "HubSpot Production"
  }'

Response:
{
  "id": 456,
  "connection_type": "hubspot",
  "auth_type": "private_app",
  "nickname": "HubSpot Production",
  "status": "active",
  "portal_id": 12345678,
  "available_objects": ["contacts", "deals", "companies", "tickets"],
  "created_at": "2025-01-20T10:30:00Z"
}

List HubSpot Connections

GET /api/v1/knowledgebases/{id}/connections/

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.yardee.ai/api/v1/knowledgebases/123/connections/

Response:
{
  "connections": [
    {
      "id": 456,
      "connection_type": "hubspot",
      "auth_type": "private_app",
      "nickname": "HubSpot Production",
      "status": "active",
      "portal_id": 12345678,
      "available_objects": ["contacts", "deals", "companies", "tickets"],
      "last_indexed": "2025-01-20T11:00:00Z",
      "created_at": "2025-01-20T10:30:00Z"
    }
  ],
  "count": 1
}

Delete HubSpot Connection

DELETE /api/v1/connections/{connection_id}/

curl -X DELETE https://app.yardee.ai/api/v1/connections/456/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 204 No Content

HubSpot Authentication

Secure authentication with HubSpot Private App Tokens for API access.

Private App Token Authentication

Required for API access: Developers must use HubSpot Private App Tokens for direct API integration. This provides secure, programmatic access to your HubSpot CRM data.

{
  "connection_type": "hubspot", 
  "auth_type": "private_app",
  "hubspot_private_app_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "nickname": "HubSpot Production"
}

# How to Create a Private App Token:
# 1. Go to HubSpot Settings → Integrations → Private Apps
# 2. Create a new private app
# 3. Configure required scopes:
#    - crm.objects.contacts.read
#    - crm.objects.deals.read  
#    - crm.objects.companies.read
#    - tickets (if querying support data)
# 4. Copy the generated access token

Required HubSpot Scopes

# Minimum Required Scopes:
crm.objects.contacts.read     # Query contact data
crm.objects.deals.read        # Query deal/opportunity data  
crm.objects.companies.read    # Query company data
settings.users.read           # Portal information

# Optional Scopes:
tickets                       # Query support tickets (if available)
crm.objects.custom.read       # Query custom objects
timeline                      # Access engagement data

# OAuth Scopes (automatically requested):
oauth                         # OAuth authorization

Querying HubSpot CRM Data

Use the same search endpoint to query your HubSpot CRM with natural language.

Basic HubSpot Queries

POST /api/v1/knowledgebases/{id}/search/

curl -X POST https://app.yardee.ai/api/v1/knowledgebases/123/search/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many contacts do I have in HubSpot?",
    "top_k": 1
  }'

Response:
{
  "query": "How many contacts do I have in HubSpot?",
  "knowledge_base_id": 123,
  "total_results": 1,
  "results": [
    {
      "chunk": null,
      "content": "You currently have 8,547 contacts in your HubSpot CRM.",
      "similarity_score": null,
      "document_title": "hubspot_crm_connection",
      "metadata": {
        "type": "hubspot_query",
        "source": "HubSpot Production",
        "connection_id": 456,
        "portal_id": 12345678,
        "object_type": "contacts",
        "calculation_result": 8547
      }
    }
  ]
}

Sales Pipeline Analytics

POST /api/v1/knowledgebases/{id}/search/

curl -X POST https://app.yardee.ai/api/v1/knowledgebases/123/search/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the total value of deals in my pipeline?",
    "top_k": 1
  }'

Response:
{
  "query": "What is the total value of deals in my pipeline?",
  "total_results": 1,
  "results": [
    {
      "chunk": null,
      "content": "Your current pipeline has a total value of $2,847,350 across 127 active deals.",
      "similarity_score": null,
      "document_title": "hubspot_crm_connection",
      "metadata": {
        "type": "hubspot_query",
        "source": "HubSpot Production", 
        "connection_id": 456,
        "object_type": "deals",
        "calculation_result": 2847350,
        "record_count": 127
      }
    }
  ]
}

Customer Intelligence Queries

POST /api/v1/knowledgebases/{id}/search/

curl -X POST https://app.yardee.ai/api/v1/knowledgebases/123/search/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me companies in the technology industry with recent activity",
    "top_k": 5
  }'

Response:
{
  "query": "Show me companies in the technology industry with recent activity",
  "total_results": 1,
  "results": [
    {
      "chunk": null,
      "content": "Found 23 technology companies with recent activity: TechCorp Inc. (last activity: 2 days ago), InnovateTech LLC (last activity: 1 day ago), DataSystems Pro (last activity: 3 hours ago)...",
      "similarity_score": null,
      "document_title": "hubspot_crm_connection",
      "metadata": {
        "type": "hubspot_query",
        "source": "HubSpot Production",
        "connection_id": 456,
        "object_type": "companies",
        "filters_applied": ["industry = 'Technology'", "last_activity_date >= 7 days ago"],
        "record_count": 23
      }
    }
  ]
}

Mixed Results (Documents + HubSpot)

When your knowledge base contains both uploaded documents and HubSpot connections, the search endpoint returns unified results from all sources.

{
  "query": "customer retention strategy",
  "total_results": 3,
  "results": [
    {
      "chunk": {
        "id": 789,
        "content": "Our customer retention strategy focuses on...",
        "document_id": 123
      },
      "content": "Our customer retention strategy focuses on...",
      "similarity_score": 0.89,
      "document_title": "Customer_Strategy.pdf",
      "metadata": {
        "type": "document_chunk",
        "page": 3
      }
    },
    {
      "chunk": null,
      "content": "Current customer retention rate based on HubSpot data: 84.3% over the last 12 months, with an average customer lifespan of 2.1 years.",
      "similarity_score": null,
      "document_title": "hubspot_crm_connection", 
      "metadata": {
        "type": "hubspot_query",
        "source": "HubSpot Production",
        "connection_id": 456,
        "calculation_result": 0.843
      }
    }
  ]
}

Available HubSpot Objects

CRM objects you can query through the API.

Core CRM Objects

• Contacts - Individual people and prospects
• Companies - Organizations and accounts
• Deals - Sales opportunities and pipeline
• Tickets - Support requests and issues

Advanced Objects

• Custom Objects - Your custom CRM entities
• Products - Product catalog and pricing
• Quotes - Sales quotes and proposals
• Tasks - Follow-up activities

Natural Language Query Examples

Contact Queries:

• "How many new leads this week?"
• "Show contacts from California"
• "Which leads haven't been contacted?"
• "What's our lead conversion rate?"

Deal Queries:

• "Total pipeline value this quarter"
• "Deals closing this month"
• "Average deal size by region"
• "Win rate for large deals"

Company Queries:

• "Largest customers by revenue"
• "Companies in tech industry"
• "Enterprise accounts with open deals"
• "Customer growth by segment"

Support Queries:

• "Open support tickets count"
• "Average resolution time"
• "High priority tickets"
• "Customer satisfaction scores"

Security Best Practices

Secure your HubSpot integration and protect your CRM data.

Recommended Practices

• Create dedicated Private Apps for API access
• Grant minimal necessary scopes only
• Regularly review and rotate Private App tokens
• Monitor API usage and access logs
• Use read-only permissions whenever possible
• Store tokens securely and never expose in client-side code

Security Warnings

• Never share Private App tokens publicly
• Don't grant write permissions unless absolutely necessary
• Avoid using super admin accounts for integrations
• Don't store tokens in client-side code or version control
• Revoke access for unused integrations
• Never log tokens in application logs

HubSpot Private App Setup

# Step-by-Step Private App Creation:

1. Navigate to HubSpot Settings
   Settings → Integrations → Private Apps

2. Create New Private App
   Click "Create a private app"
   Name: "Yardee Vector API Integration" 

3. Configure Basic Info
   App name: Descriptive name for your records
   Description: Purpose and usage of this integration

4. Set Scopes (Permissions)
   CRM Scopes:
   ✓ crm.objects.contacts.read
   ✓ crm.objects.deals.read  
   ✓ crm.objects.companies.read
   ✓ tickets (if querying support data)
   
   Settings Scopes:
   ✓ settings.users.read (for portal info)

5. Create App & Copy Token
   Click "Create app"
   Copy the access token immediately
   Store securely - this is your hubspot_private_app_token

6. Test Connection
   Use the token in your API connection request

Error Handling

Common HubSpot connection errors and solutions.

Invalid Private App Token

Token is invalid or expired. Check token format and ensure Private App is active in HubSpot.

Insufficient Scopes

Private App lacks required permissions. Add necessary scopes in HubSpot Private App settings.

Connection Failed

Unable to establish connection with HubSpot. Verify your Private App Token and ensure the app is active in HubSpot.

Portal Access Denied

HubSpot account lacks access to requested objects. Upgrade subscription or check portal permissions.

Rate Limit Exceeded

Too many API calls to HubSpot. Requests are automatically retried, but consider spacing out queries.

Schema Indexing Failed

Unable to analyze HubSpot portal structure. Check connection permissions and portal accessibility.

Frequently Asked Questions

How do I connect my HubSpot CRM to the API?

Use the POST /api/v1/knowledgebases/{id}/connections/ endpoint with connection_type: 'hubspot' and provide your HubSpot Private App Token for authentication.

What HubSpot data can I query through the API?

You can query contacts, deals, companies, tickets, and custom objects from your HubSpot CRM. The API supports filtering, sorting, and aggregations across all available HubSpot properties.

Do I need special permissions in HubSpot?

Yes, you need to configure read-only scopes when creating your Private App in HubSpot. Required scopes include crm.objects.contacts.read, crm.objects.deals.read, crm.objects.companies.read, and tickets for support data.

How does the API query my HubSpot data?

When you ask questions, our AI analyzes your query, generates appropriate HubSpot API calls, and executes them against your CRM in real-time. Results are returned as natural language answers through the standard search endpoint.

Is my HubSpot data stored on your servers?

No, we only store lightweight schema metadata (object types, property names) to help the AI understand your CRM structure. Your actual CRM data stays in HubSpot and is queried in real-time.

Ready to Connect Your HubSpot CRM?

Start querying your HubSpot data with AI-powered natural language processing. Free to get started, no credit card required.

Get Your API Key Learn More