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

hubspot-search-companies skill

safe

/00-system/skills/hubspot/hubspot-search-companies

This skill helps you search HubSpot companies by name or domain and return structured results for quick follow-up.

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

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

Files (1)

SKILL.md

2.0 KB

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

# Search HubSpot Companies

**Specialized skill** for searching companies 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 Name
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py \
  --name "Acme" \
  --json
```

### Search by Domain
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py \
  --domain "acme.com" \
  --json
```

### With Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py \
  --name "Tech" \
  --limit 20 \
  --json
```

---

## Output Format

```json
{
  "total": 3,
  "results": [
    {
      "id": "6493611979",
      "properties": {
        "name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Technology",
        "city": "San Francisco"
      },
      "url": "https://app.hubspot.com/..."
    }
  ]
}
```

---

## Display Format

```
Found 3 companies matching "Acme":

1. Acme Corp
   Domain: acme.com
   Industry: Technology
   City: San Francisco
   ID: 6493611979

2. Acme Industries
   Domain: acmeindustries.com
   ...
```

---

## Search Behavior

- Name search uses `CONTAINS_TOKEN` operator (partial match)
- Domain search uses `CONTAINS_TOKEN` operator (partial match)
- Results sorted by relevance

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.companies.read` scope |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-list-companies` - List all companies
- `hubspot-create-company` - Create if not found
- `hubspot-get-associations` - Get company contacts

Overview

This skill searches companies in HubSpot CRM by company name or domain and returns structured results including core properties and the HubSpot URL. It supports partial matches, result limits, and returns totals with relevance-sorted results. Useful for quick lookups before outreach, enrichment, or automation flows.

How this skill works

The skill queries HubSpot Companies using partial-match (CONTAINS_TOKEN) operators for name and domain filters and sorts results by relevance. It accepts optional limit parameters and returns a JSON payload with total count, company properties (name, domain, industry, city, etc.), ID, and direct HubSpot URL. It validates configuration and permission scopes before running and surfaces common API errors.

When to use it

You need to find a company record by full or partial name.
You want to look up companies by domain to confirm ownership or records.
Preparing personalized outreach and need company metadata (industry, city).
Checking whether a company already exists before creating a new record.
Integrating company lookup into automation or enrichment pipelines.

Best practices

Run the pre-flight configuration check to confirm credentials and scopes before searching.
Prefer domain searches to reduce false positives when multiple companies share similar names.
Use a reasonable limit to avoid rate limits; paginate if you expect many matches.
Handle 401/403/429 errors explicitly: reauthorize for 401, ensure crm.objects.companies.read scope for 403, and implement backoff for 429.
Validate and normalize input (trim whitespace, lowercase domains) for more consistent partial matches.

Example use cases

Sales rep searches for a prospect by partial company name before sending an email.
Marketing enrichment process looks up companies for a list of domains to attach industry and location.
Automation checks for existing company record by domain before triggering a create-company step.
Customer success verifies account details (ID, city, industry) prior to a renewal call.

FAQ

What search operators does this skill use?

Name and domain searches use CONTAINS_TOKEN for partial matching, with results ranked by relevance.

What common errors should I expect and how to fix them?

401 means invalid token — re-run authorization. 403 indicates missing crm.objects.companies.read scope — update app scopes. 429 means rate limited — wait and retry with exponential backoff.