hubspot-search-companies_skill

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.