HubSpot Contacts

HubSpot Contact Management

Overview

Contacts in HubSpot represent individual people -- clients, prospects, vendors, or any person your MSP interacts with. Contacts are the foundational entity in HubSpot CRM. They can be associated with companies, deals, tickets, and activities to build a complete picture of every relationship. For MSPs, contacts typically represent client employees, decision-makers, technical contacts, and billing contacts at managed companies.

Anti-triggers

• The organization rather than the person — "look up Acme Corp" wants a company record; use hubspot-companies.
• The organization as an entity you invoice — a HubSpot contact carries no balance, terms, or tax details; the AR-side record is xero-contacts or qbo-customers.
• A company or person detected on the website but not yet in the CRM — that is intent data, not a contact record; use warmly-visitor-intelligence.
• filterGroups, sort, and pagination syntax — the search grammar is shared across every object type; use hubspot-api-patterns.

MCP Tools

Available Tools

Search Contacts

Call hubspot_search_contacts with filter groups to find contacts:

Search by email domain (find all contacts at a company):

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "CONTAINS_TOKEN",
          "value": "acmecorp.com"
        }
      ]
    }
  ],
  "limit": 100
}

Search by name:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "firstname",
          "operator": "EQ",
          "value": "John"
        },
        {
          "propertyName": "lastname",
          "operator": "EQ",
          "value": "Smith"
        }
      ]
    }
  ]
}

Search by lifecycle stage (find all customers):

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "lifecyclestage",
          "operator": "EQ",
          "value": "customer"
        }
      ]
    }
  ],
  "sorts": [
    {
      "propertyName": "lastname",
      "direction": "ASCENDING"
    }
  ],
  "limit": 100
}

Create a Contact

Call hubspot_create_contact with the contact's properties:

Example: Create a new client contact:

• email: jane.doe@acmecorp.com
• firstname: Jane
• lastname: Doe
• phone: 555-987-6543
• company: Acme Corporation
• jobtitle: IT Director
• lifecyclestage: customer

Update a Contact

Call hubspot_update_contact with the contactId and the properties to change:

Example: Update lifecycle stage and lead status:

• contactId: 12345
• lifecyclestage: customer
• hs_lead_status: CONNECTED

Retrieve a Contact

Call hubspot_retrieve_contact with the contactId:

Example:

• hubspot_retrieve_contact with contactId=12345

Key Concepts

Lifecycle Stages

Lifecycle stages track where a contact is in your MSP's sales and service process:

Lead Status

Lead status tracks the disposition of sales outreach:

Contact Owner

The hubspot_owner_id property assigns a contact to a specific user in your HubSpot account. For MSPs, this is typically the account manager or sales rep responsible for the relationship.

Field Reference

Core Fields

MSP-Relevant Custom Fields

Many MSPs add custom properties for contacts. Common examples:

Common Workflows

Find a Contact by Email

1. Call hubspot_search_contacts with a filter on email using EQ operator
2. If not found, try CONTAINS_TOKEN for partial domain matching
3. Review the results and note the id for further operations

Find All Contacts at a Company

1. Call hubspot_search_contacts with a filter on email using CONTAINS_TOKEN with the company's email domain
2. Alternatively, use hubspot_access_associations on the company object to get associated contacts
3. For each contact, review role and lifecycle stage

Create a New Client Contact

1. Check for duplicates - Search by email first using hubspot_search_contacts
2. Create the contact - Call hubspot_create_contact with email, name, phone, company, job title, and lifecyclestage=customer
3. Associate with company - Call hubspot_create_association to link the contact to the company record
4. Log onboarding note - Call hubspot_create_note to document the new contact setup

Update Contact After Sales Conversion

1. Call hubspot_update_contact with:
   • lifecyclestage: customer
   • hs_lead_status: CONNECTED
2. Call hubspot_create_note to log the conversion details
3. Call hubspot_create_task to create onboarding follow-up tasks

Contact Audit for a Client Company

1. Find the company with hubspot_search_companies
2. Call hubspot_access_associations to get all contacts associated with the company
3. Retrieve each contact with hubspot_retrieve_contact
4. Build a report with name, email, job title, lifecycle stage, and last activity date
5. Flag contacts without email addresses or with stale last activity dates

Response Examples

Single Contact:

{
  "id": "12345",
  "properties": {
    "email": "john.smith@acmecorp.com",
    "firstname": "John",
    "lastname": "Smith",
    "phone": "555-123-4567",
    "company": "Acme Corporation",
    "jobtitle": "IT Director",
    "lifecyclestage": "customer",
    "hs_lead_status": "CONNECTED",
    "hubspot_owner_id": "67890",
    "createdate": "2025-06-15T10:30:00.000Z",
    "lastmodifieddate": "2026-02-10T14:15:00.000Z"
  },
  "createdAt": "2025-06-15T10:30:00.000Z",
  "updatedAt": "2026-02-10T14:15:00.000Z"
}

Search Results:

{
  "total": 3,
  "results": [
    {
      "id": "12345",
      "properties": {
        "email": "john.smith@acmecorp.com",
        "firstname": "John",
        "lastname": "Smith",
        "company": "Acme Corporation"
      }
    },
    {
      "id": "12346",
      "properties": {
        "email": "jane.doe@acmecorp.com",
        "firstname": "Jane",
        "lastname": "Doe",
        "company": "Acme Corporation"
      }
    }
  ]
}

Error Handling

Common Errors

Best Practices

1. Use lifecycle stages consistently - Define clear criteria for each stage in your MSP's process
2. Associate contacts with companies - Always link contacts to their company record for full context
3. Track lead status - Update lead status as sales conversations progress
4. Assign owners - Set hubspot_owner_id so team members know who manages each relationship
5. Log activities - Create notes and tasks on contacts to maintain a complete activity history
6. Audit regularly - Review contacts quarterly for stale records and missing information
7. Standardize job titles - Use consistent job title formats for better reporting
8. Respect data privacy - PHI properties are excluded from MCP responses by design

Related Skills

• HubSpot API Patterns - MCP tools reference and connection info
• HubSpot Companies - Company management and associations
• HubSpot Deals - Deals associated with contacts
• HubSpot Tickets - Support tickets for contacts
• HubSpot Activities - Notes, tasks, and engagement tracking