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

How it works

Customer provides email address during the call
AI automatically extracts the email
Real-time query to HubSpot CRM
Immediate personalization of responses

Typical use cases

Customer verification during support requests
Personalized greetings and addressing
Contextualized conversation handling
Automatic conversation logging

Step-by-Step Configuration

1. Obtain HubSpot API Key

Open HubSpot Dashboard

Log in to your HubSpot account
Navigate to “Settings” (⚙️)

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”)

Configure Permissions

Required scopes:
  - crm.objects.contacts.read
  - crm.objects.companies.read (optional)
  - crm.objects.deals.read (optional)

Secure the API Key

Copy the generated API key
Store it securely (needed for tool configuration)

2. Configure Mid-call Action

Basic Tool Settings

Function Details
URL & Authentication

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)

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"

Detailed Configuration

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:

Email-based: /crm/v3/objects/contacts/{email}
ID-based: /crm/v3/objects/contacts/{contact_id}
Phone-based: /crm/v3/objects/contacts/{phone}

Header Configuration

Authentication:

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

Security Notice: Use environment variables for API keys. Never store API keys directly in the code!

Query Parameters

Default parameters:

idProperty: "email"  # Specify lookup field
properties: "firstname,lastname,company,phone,lastmodifieddate,lifecyclestage"

Extended properties (optional):

# 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):

associations: "companies,deals"  # Also loads company and deal data

3. Define Parameter Schema

{
  "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

Flexible Lookup
With Filter Options

{
  "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"]}
  ]
}

{
  "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"]
}

Response Handling

Typical API Response

{
  "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:

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

Contextual Conversation Handling

Based on lifecycle stage:

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

Automatic Qualification

Lead status based addressing:

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

Error Handling

Common Error Scenarios

404 - Contact Not Found
401 - Authentication Error
429 - Rate Limit Exceeded
Timeout Handling

Cause: Email address does not exist in HubSpotGraceful fallback:

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

Cause: API key invalid or expiredSystem reaction:

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

Cause: Too many API requests in a short timeHandling:

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?"

Cause: API response takes longer than 5 secondsGraceful degradation:

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?"

Testing and Validation

Automated Tests

Test API Connectivity

System automatically runs tests with standard test values:

Email: “test@example.com”
Expected behavior: 404 or contact data

Performance Monitoring

Monitor key metrics:

Response Time: <3 seconds (target)
Success Rate: >95%
Error Rate: <5%

Manual Tests

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

Conversation Flow Tests

Test realistic scenarios:

Standard customer contact:
- Customer: “My email is max@example.com”
- Expected AI response: Personalized greeting with name and company
Unknown contact:
- Customer: “test12345@notregisteredhere.com”
- Expected AI response: Polite request for an alternative email
Performance test:
- Multiple quick queries in succession
- Expected behavior: Consistent performance without degradation

Advanced Configurations

Multi-Property Lookup

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

Session-based Caching
Time-based Cache

Caching strategy:
  Duration: Until end of conversation
  Purpose: Avoid repeated API calls within the same conversation
  Implementation: Automatically handled by Famulor system

For frequently queried contacts:
  Cache duration: 5 minutes
  Refresh: Upon known data changes
  Fallback: Fresh data query on cache miss

Integration with Other Tools

Workflow Combination

Best Practices

Performance Optimization

Selective Properties

Fetch only necessary data:

Standard: firstname, lastname, company
When needed: jobtitle, lifecyclestage
Avoid: notes, all custom properties

Timeout Management

Appropriate timeout settings:

Standard: 5 seconds
Critical calls: 3 seconds
Batch operations: 10 seconds

Security and Compliance

API Security

Security best practices:

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

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

Identify Common Issues

API key expiration (401 errors)
Rate limiting (429 errors)
Network timeouts
Incorrect URL parameters

Set Up Monitoring

Automatic alerts for >5% error rate
Daily performance reports
Weekly usage analytics

Continuous Improvement

Monthly performance reviews
Quarterly API integration updates
Customer feedback integration

Next Steps

After implementing the HubSpot contact fetch tool, you can add further HubSpot integrations:

Deal Management Tool
Lead Creation Tool
Webhook Integration for more complex workflows

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

Need a whole toolset instead of building HTTP actions one by one? Connect an external MCP server — tools are discovered automatically. See MCP Servers.

Mid-Call Tools

Mid-Call Tool Integrations

HubSpot Contact Fetch

HubSpot Contact Fetch Template

Overview

How it works

Typical use cases

Step-by-Step Configuration

1. Obtain HubSpot API Key

2. Configure Mid-call Action

Basic Tool Settings

Detailed Configuration

3. Define Parameter Schema

4. Advanced Parameter Options

Response Handling

Typical API Response

AI Integration and Language Adjustments

Natural Language Usage

Error Handling

Common Error Scenarios

Testing and Validation

Automated Tests

Manual Tests

Advanced Configurations

Multi-Property Lookup

Caching Optimization

Integration with Other Tools

Workflow Combination

Best Practices

Performance Optimization

Selective Properties

Timeout Management

Security and Compliance

Monitoring and Analytics

Key Performance Indicators

Troubleshooting Guide

Next Steps

​HubSpot Contact Fetch Template

​Overview

How it works

Typical use cases

​Step-by-Step Configuration

​1. Obtain HubSpot API Key

​2. Configure Mid-call Action

​Basic Tool Settings

​Detailed Configuration

​3. Define Parameter Schema

​4. Advanced Parameter Options

​Response Handling

​Typical API Response

​AI Integration and Language Adjustments

​Natural Language Usage

​Error Handling

​Common Error Scenarios

​Testing and Validation

​Automated Tests

​Manual Tests

​Advanced Configurations

​Multi-Property Lookup

​Caching Optimization

​Integration with Other Tools

​Workflow Combination

​Best Practices

​Performance Optimization

Selective Properties

Timeout Management

​Security and Compliance

​Monitoring and Analytics

​Key Performance Indicators

​Troubleshooting Guide

Next Steps

HubSpot Contact Fetch Template

Overview

Step-by-Step Configuration

1. Obtain HubSpot API Key

2. Configure Mid-call Action

Basic Tool Settings

Detailed Configuration

3. Define Parameter Schema

4. Advanced Parameter Options

Response Handling

Typical API Response

AI Integration and Language Adjustments

Natural Language Usage

Error Handling

Common Error Scenarios

Testing and Validation

Automated Tests

Manual Tests

Advanced Configurations

Multi-Property Lookup

Caching Optimization

Integration with Other Tools

Workflow Combination

Best Practices

Performance Optimization

Security and Compliance

Monitoring and Analytics

Key Performance Indicators

Troubleshooting Guide