home / skills / abdullahbeam / nexus-design-abdullah / hubspot-search-contacts

hubspot-search-contacts skill

safe

/00-system/skills/hubspot/hubspot-search-contacts

This skill helps you find HubSpot contacts by email, name, or company and retrieve matching results quickly.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-search-contacts

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: hubspot-search-contacts
description: "Search contacts in HubSpot CRM by email, name, or company. Load when user says 'search contacts', 'find contact', 'lookup contact', 'search for [name]'."
---

# Search HubSpot Contacts

**Specialized skill** for searching contacts in HubSpot CRM.

## Pre-Flight Check

Before running, execute config check:
```bash
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
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --email "[email protected]" \
  --json
```

### Search by Name
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --name "John" \
  --json
```

### Search by Company
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --company "Acme" \
  --json
```

### Combined Search with Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --name "John" \
  --company "Acme" \
  --limit 20 \
  --json
```

---

## Output Format

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

---

## Display Format

```
Found 5 contacts matching "John":

1. John Doe
   Email: [email protected]
   Company: Acme Corp
   ID: 12345

2. Johnny Smith
   Email: [email protected]
   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

Overview

This skill searches contacts in HubSpot CRM by email, name, or company. It returns structured results including contact ID, properties, and a HubSpot URL. Use natural triggers like "search contacts", "find contact", or "lookup contact" to invoke the skill. It supports combined filters and result limits for focused queries.

How this skill works

The skill queries the HubSpot Contacts API using appropriate operators: exact match for email and partial token matches for name and company. Multiple filters are combined with AND logic and an optional limit controls result size. Results are returned as JSON with total count and an array of contact objects, and can be rendered in a concise human-readable list.

When to use it

Find a contact by exact email address
Locate contacts that match a partial name or company
Narrow search with combined name and company filters
Quickly preview contact details before update or outreach
Confirm contact existence before creating a new record

Best practices

Run the pre-flight configuration check to verify credentials and permissions before searching
Use email for precise lookups and name/company for broader results
Combine filters to reduce false positives (e.g., name + company)
Set a reasonable limit to avoid large result sets and rate limits
Handle common HTTP errors: re-authenticate on 401, request missing scopes on 403, and back off on 429 rate limits

Example use cases

Search for a specific lead by email to fetch contact ID and profile URL
Lookup all contacts that contain a given name token to prepare outreach lists
Filter contacts by company name to aggregate accounts for a campaign
Combine name and company filters to disambiguate similarly named contacts
Quickly verify whether a prospect already exists before creating a duplicate

FAQ

What authentication is required?

An OAuth token or API key with crm.objects.contacts.read scope is required; run the configuration check if queries fail.

Why did my search return zero results for a known contact?

Email searches are exact matches; try searching by name or company with partial tokens if email returns nothing.

How should I handle rate limits?

On 429 responses implement exponential backoff and reduce query frequency or result limits.