Search HubSpot Contacts

Specialized skill for searching contacts in HubSpot CRM.

Pre-Flight Check

Before running, execute config check:

python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

If ai_action is not proceed_with_operation , follow hubspot-connect setup guide.

Usage

Search by Email

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--email "john@example.com"
--json

Search by Name

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--name "John"
--json

Search by Company

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--company "Acme"
--json

Combined Search with Limit

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py
--name "John"
--company "Acme"
--limit 20
--json

Output Format

{ "total": 5, "results": [ { "id": "12345", "properties": { "email": "john@example.com", "firstname": "John", "lastname": "Doe", "company": "Acme Corp" }, "url": "https://app.hubspot.com/..." } ] }

Display Format

Found 5 contacts matching "John":

1. John Doe Email: john@example.com Company: Acme Corp ID: 12345

2. Johnny Smith Email: johnny@corp.com Company: Tech Inc ID: 12346 ...

Search Behavior

• Name search uses CONTAINS_TOKEN operator (partial match)

• Email search uses EQ operator (exact match)

• Company search uses CONTAINS_TOKEN operator (partial match)

• Multiple filters are combined with AND logic

Error Handling

Error Solution

401 Invalid token - re-run setup

403 Missing crm.objects.contacts.read scope

429 Rate limited - wait and retry

Related Skills

• hubspot-list-contacts

• List all contacts

• hubspot-update-contact

• Update found contact

• hubspot-create-contact

• Create if not found