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

# HubSpot Contact Fetch

> Complete guide to implementing a HubSpot contact fetch tool for mid-call data queries

# HubSpot Contact Fetch Template

This template enables your AI assistant to automatically retrieve contact data from HubSpot during a conversation. As soon as a customer provides their email address, the relevant information becomes instantly available.

## Overview

<CardGroup cols={2}>
  <Card title="How it works" icon="gear">
    * Customer provides email address during the call
    * AI automatically extracts the email
    * Real-time query to HubSpot CRM
    * Immediate personalization of responses
  </Card>

  <Card title="Typical use cases" icon="phone">
    * Customer verification during support requests
    * Personalized greetings and addressing
    * Contextualized conversation handling
    * Automatic conversation logging
  </Card>
</CardGroup>

## Step-by-Step Configuration

### 1. Obtain HubSpot API Key

<Steps>
  <Step title="Open HubSpot Dashboard">
    * Log in to your HubSpot account
    * Navigate to "Settings" (⚙️)
  </Step>

  <Step title="Generate API Key">
    * Go to "Integrations" → "Private Apps"
    * Click on "Create a private app"
    * Give it a meaningful name (e.g., "Famulor Mid-call Actions")
  </Step>

  <Step title="Configure Permissions">
    ```yaml theme={null}
    Required scopes:
      - crm.objects.contacts.read
      - crm.objects.companies.read (optional)
      - crm.objects.deals.read (optional)
    ```
  </Step>

  <Step title="Secure the API Key">
    * Copy the generated API key
    * Store it securely (needed for tool configuration)
  </Step>
</Steps>

### 2. Configure Mid-call Action

#### Basic Tool Settings

<Tabs>
  <Tab title="Function Details">
    | Field             | Value                                                                                                                                                     | Description                      |
    | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
    | **Function name** | `get_hubspot_contact`                                                                                                                                     | Unique identifier without spaces |
    | **Description**   | "Fetches a contact from HubSpot based on the email address. Use this function when the customer provides their email to obtain personalized information." | Agent instructions               |
    | **HTTP Method**   | `GET`                                                                                                                                                     | Data retrieval (read-only)       |
    | **Timeout**       | `5000`                                                                                                                                                    | Milliseconds (5 seconds)         |
  </Tab>

  <Tab title="URL & Authentication">
    ```yaml theme={null}
    URL:
      https://api.hubapi.com/crm/v3/objects/contacts/{email}

    Headers:
      Authorization: "Bearer YOUR_HUBSPOT_API_KEY"
      Content-Type: "application/json"

    Query Parameters:
      idProperty: "email"
      properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"
    ```
  </Tab>
</Tabs>

#### Detailed Configuration

<AccordionGroup>
  <Accordion title="URL Configuration">
    **Base URL**: `https://api.hubapi.com/crm/v3/objects/contacts/{email}`

    * `{email}` is automatically replaced by the parameter
    * Also supports other identifiers like `{contact_id}` or `{phone}`

    **Alternative URLs for different lookup methods**:

    ```yaml theme={null}
    Email-based: /crm/v3/objects/contacts/{email}
    ID-based: /crm/v3/objects/contacts/{contact_id}
    Phone-based: /crm/v3/objects/contacts/{phone}
    ```
  </Accordion>

  <Accordion title="Header Configuration">
    **Authentication**:

    ```json theme={null}
    {
      "Authorization": "Bearer YOUR_HUBSPOT_API_KEY",
      "Content-Type": "application/json",
      "User-Agent": "Famulor-MidCall-Action/1.0"
    }
    ```

    <Warning>
      **Security Notice**: Use environment variables for API keys. Never store API keys directly in the code!
    </Warning>
  </Accordion>

  <Accordion title="Query Parameters">
    **Default parameters**:

    ```yaml theme={null}
    idProperty: "email"  # Specify lookup field
    properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"
    ```

    **Extended properties** (optional):

    ```yaml theme={null}
    # For more comprehensive data retrieval
    properties: "firstname,lastname,email,phone,company,jobtitle,
                 lastmodifieddate,lifecyclestage,hs_lead_status,
                 createdate,notes_last_updated,num_notes"

    # For performance-optimized queries (minimal)
    properties: "firstname,lastname,company"
    ```

    **Associations** (for related objects):

    ```yaml theme={null}
    associations: "companies,deals"  # Also loads company and deal data
    ```
  </Accordion>
</AccordionGroup>

### 3. Define Parameter Schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Email address of the contact you want to look up in HubSpot",
      "format": "email"
    }
  },
  "required": ["email"]
}
```

### 4. Advanced Parameter Options

<Tabs>
  <Tab title="Flexible Lookup">
    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "Contact's email address"
        },
        "contact_id": {
          "type": "string", 
          "description": "HubSpot contact ID (alternative to email)"
        },
        "phone": {
          "type": "string",
          "description": "Contact's phone number (alternative)"
        }
      },
      "oneOf": [
        {"required": ["email"]},
        {"required": ["contact_id"]},
        {"required": ["phone"]}
      ]
    }
    ```
  </Tab>

  <Tab title="With Filter Options">
    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "Contact's email address"
        },
        "include_deals": {
          "type": "boolean",
          "description": "Should linked deals also be retrieved?",
          "default": false
        },
        "include_companies": {
          "type": "boolean", 
          "description": "Should company data also be retrieved?",
          "default": true
        }
      },
      "required": ["email"]
    }
    ```
  </Tab>
</Tabs>

## Response Handling

### Typical API Response

```json theme={null}
{
  "id": "12345",
  "properties": {
    "firstname": "Max",
    "lastname": "Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+49 123 456789",
    "company": "Example GmbH",
    "jobtitle": "Managing Director",
    "lifecyclestage": "customer",
    "createdate": "2024-01-01T10:00:00.000Z",
    "lastmodifieddate": "2024-01-15T10:30:00.000Z",
    "hs_lead_status": "CONNECTED"
  },
  "createdAt": "2024-01-01T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

### AI Integration and Language Adjustments

#### Natural Language Usage

The AI assistant can use the retrieved data as follows:

<AccordionGroup>
  <Accordion title="Personalized Greeting">
    **Examples of natural integration**:

    * "Hello Mr. Mustermann! I see you are the Managing Director at Example GmbH."
    * "Great to speak with you again, Max. How is Example GmbH doing?"
    * "Perfect, I found your details. You have been in our system since January 2024."
  </Accordion>

  <Accordion title="Contextual Conversation Handling">
    **Based on lifecycle stage**:

    ```yaml theme={null}
    If lifecyclestage == "lead":
      "I see you are interested in our services. How can I assist you?"

    If lifecyclestage == "customer":
      "As an existing customer, you naturally have priority. What can I do for you?"

    If lifecyclestage == "opportunity":
      "I see we are already discussing a potential collaboration..."
    ```
  </Accordion>

  <Accordion title="Automatic Qualification">
    **Lead status based addressing**:

    ```yaml theme={null}
    hs_lead_status:
      "NEW": "Thank you for your interest! Let me assist you."
      "ATTEMPTED_TO_CONTACT": "Nice to hear from you! We tried reaching out."
      "CONNECTED": "Perfect, we have been in contact before. How can I help today?"
      "BAD_TIMING": "No problem, I understand last time wasn’t the best moment."
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

### Common Error Scenarios

<Tabs>
  <Tab title="404 - Contact Not Found">
    **Cause**: Email address does not exist in HubSpot

    **Graceful fallback**:

    ```yaml theme={null}
    Response: "I’m sorry, I couldn’t find your email address in our system. 
             Would you like to provide an alternative email, or 
             should I create a new customer profile for you?"

    Next steps:
      - Ask for alternative email
      - Offer lead creation
      - Escalate to manual support
    ```
  </Tab>

  <Tab title="401 - Authentication Error">
    **Cause**: API key invalid or expired

    **System reaction**:

    ```yaml theme={null}
    Internal: Log error for admin
    Customer: "Sorry, I’m currently experiencing a technical issue 
              accessing our customer database. Can I assist you otherwise?"

    Escalation: Notify technical team
    ```
  </Tab>

  <Tab title="429 - Rate Limit Exceeded">
    **Cause**: Too many API requests in a short time

    **Handling**:

    ```yaml theme={null}
    Retry logic: Automatic retry after 1-2 seconds
    Fallback: "One moment please, I’m retrieving your data..."

    If still failing:
      "I’m sorry, our system is currently busy. 
       May I handle your request manually?"
    ```
  </Tab>

  <Tab title="Timeout Handling">
    **Cause**: API response takes longer than 5 seconds

    **Graceful degradation**:

    ```yaml theme={null}
    After 3 seconds: "One moment, I’m checking in our system..."
    After 5 seconds: "The data retrieval is taking a bit longer than usual..."
    After 8 seconds: "Sorry for the delay. Could you please tell me your name 
                      so I can assist you anyway?"
    ```
  </Tab>
</Tabs>

## Testing and Validation

### Automated Tests

<Steps>
  <Step title="Test API Connectivity">
    System automatically runs tests with standard test values:

    * Email: "[test@example.com](mailto:test@example.com)"
    * Expected behavior: 404 or contact data
  </Step>

  <Step title="Performance Monitoring">
    Monitor key metrics:

    * Response Time: \<3 seconds (target)
    * Success Rate: >95%
    * Error Rate: \<5%
  </Step>
</Steps>

### Manual Tests

<AccordionGroup>
  <Accordion title="Functionality Test Checklist">
    **Positive test cases**:

    * [ ] Known email address → Correct data returned
    * [ ] Proper data formatting in response
    * [ ] Adequate response time (\<5 seconds)
    * [ ] Natural language integration

    **Negative test cases**:

    * [ ] Unknown email → Graceful 404 handling
    * [ ] Invalid email format → Meaningful error message
    * [ ] API timeout → Fallback behavior
    * [ ] Network error → Appropriate user notification
  </Accordion>

  <Accordion title="Conversation Flow Tests">
    **Test realistic scenarios**:

    1. **Standard customer contact**:
       * Customer: "My email is [max@example.com](mailto:max@example.com)"
       * Expected AI response: Personalized greeting with name and company

    2. **Unknown contact**:
       * Customer: "[test12345@notregisteredhere.com](mailto:test12345@notregisteredhere.com)"
       * Expected AI response: Polite request for an alternative email

    3. **Performance test**:
       * Multiple quick queries in succession
       * Expected behavior: Consistent performance without degradation
  </Accordion>
</AccordionGroup>

## Advanced Configurations

### Multi-Property Lookup

```yaml theme={null}
For more complex scenarios:
URL: https://api.hubapi.com/crm/v3/objects/contacts/search

POST Body:
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "EQ", 
          "value": "{email}"
        }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "company", "phone", "lifecyclestage"],
  "limit": 1
}
```

### Caching Optimization

<Tabs>
  <Tab title="Session-based Caching">
    ```yaml theme={null}
    Caching strategy:
      Duration: Until end of conversation
      Purpose: Avoid repeated API calls within the same conversation
      Implementation: Automatically handled by Famulor system
    ```
  </Tab>

  <Tab title="Time-based Cache">
    ```yaml theme={null}
    For frequently queried contacts:
      Cache duration: 5 minutes
      Refresh: Upon known data changes
      Fallback: Fresh data query on cache miss
    ```
  </Tab>
</Tabs>

## Integration with Other Tools

### Workflow Combination

```mermaid theme={null}
sequenceDiagram
    participant K as Customer
    participant A as AI Assistant
    participant H as HubSpot Tool
    participant C as Calendar Tool
    participant E as Email Tool
    
    K->>A: "My email is max@example.com"
    A->>H: get_hubspot_contact(max@example.com)
    H-->>A: Contact data + Lifecycle Stage
    
    Note over A: Lifecycle = "opportunity"
    
    A->>K: "Hello Max! I see we're discussing a project."
    K->>A: "Yes, can we schedule an appointment?"
    A->>C: check_calendar_availability()
    C-->>A: Available slots
    A->>K: "How about Thursday at 2 PM?"
    K->>A: "Perfect!"
    A->>C: book_appointment(Thursday 2 PM)
    A->>E: send_confirmation_email()
    A->>H: update_contact_notes("Appointment scheduled")
```

## Best Practices

### Performance Optimization

<CardGroup cols={2}>
  <Card title="Selective Properties" icon="filter">
    **Fetch only necessary data**:

    * Standard: firstname, lastname, company
    * When needed: jobtitle, lifecyclestage
    * Avoid: notes, all custom properties
  </Card>

  <Card title="Timeout Management" icon="clock">
    **Appropriate timeout settings**:

    * Standard: 5 seconds
    * Critical calls: 3 seconds
    * Batch operations: 10 seconds
  </Card>
</CardGroup>

### Security and Compliance

<AccordionGroup>
  <Accordion title="GDPR Compliance">
    **Data protection measures**:

    * Minimum data retrieval (only necessary properties)
    * No storage of sensitive data beyond conversation end
    * Audit logging of all data accesses
    * Opt-out mechanisms for customers
  </Accordion>

  <Accordion title="API Security">
    **Security best practices**:

    * Store API keys in environment variables
    * Regular key rotation (quarterly)
    * IP whitelisting if possible
    * SSL/TLS for all connections
  </Accordion>
</AccordionGroup>

## Monitoring and Analytics

### Key Performance Indicators

| Metric                    | Target Value | Critical Threshold |
| ------------------------- | ------------ | ------------------ |
| **Success Rate**          | >98%         | \<90%              |
| **Average Response Time** | \<2s         | >5s                |
| **Error Rate**            | \<2%         | >10%               |
| **Customer Satisfaction** | >4.5/5       | \<4.0/5            |

### Troubleshooting Guide

<Steps>
  <Step title="Identify Common Issues">
    * API key expiration (401 errors)
    * Rate limiting (429 errors)
    * Network timeouts
    * Incorrect URL parameters
  </Step>

  <Step title="Set Up Monitoring">
    * Automatic alerts for >5% error rate
    * Daily performance reports
    * Weekly usage analytics
  </Step>

  <Step title="Continuous Improvement">
    * Monthly performance reviews
    * Quarterly API integration updates
    * Customer feedback integration
  </Step>
</Steps>

***

<Card title="Next Steps" icon="arrow-right">
  After implementing the HubSpot contact fetch tool, you can add further HubSpot integrations:

  * [Deal Management Tool](/en/automation-platform/mid-call-tools/integration-templates/hubspot-deal-management)
  * [Lead Creation Tool](/en/automation-platform/mid-call-tools/integration-templates/hubspot-lead-erstellung)
  * [Webhook Integration](/en/automation-platform/mid-call-tools/integration-templates/webhook-automation) for more complex workflows
</Card>

<Warning>
  **Important Note**: Test the integration first in a development environment before deploying to production. Continuously monitor performance and implement appropriate fallback mechanisms.
</Warning>

<Tip>
  Need a whole toolset instead of building HTTP actions one by one? Connect an external **MCP server** — tools are discovered automatically. See [MCP Servers](/en/platform/mcp-servers).
</Tip>