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

hubspot-list-companies skill

safe

/00-system/skills/hubspot/hubspot-list-companies

This skill lists HubSpot CRM companies and returns a paginated result to help you quickly browse, filter, and export company data.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-list-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-list-companies
description: "List companies from HubSpot CRM. Load when user says 'list companies', 'show companies', 'get companies', 'hubspot companies'. Returns paginated company list."
---

# List HubSpot Companies

**Specialized skill** for listing companies from 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

### Basic List (default 10 companies)
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_companies.py --json
```

### With Limit
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_companies.py --limit 25 --json
```

### With Pagination
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_companies.py --after "cursor_value" --json
```

---

## Output Format

```json
{
  "results": [
    {
      "id": "6493611979",
      "properties": {
        "name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Technology",
        "city": "San Francisco",
        "numberofemployees": "500",
        "phone": "+1234567890"
      },
      "url": "https://app.hubspot.com/contacts/.../record/0-2/6493611979"
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

```
Found {count} companies:

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

2. Tech Inc
   Domain: techinc.io
   ...
```

---

## 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-create-company` - Create new company
- `hubspot-search-companies` - Search by name/domain
- `hubspot-get-associations` - Get contacts at company

Overview

This skill lists companies from a HubSpot CRM account and returns a paginated JSON result and human-friendly summary. It is optimized for quick inspection of company records including name, domain, industry, city, employee count, phone, and HubSpot ID. Use it when you need to browse or export a subset of company records from HubSpot.

How this skill works

The skill calls HubSpot's companies API and returns a JSON payload with a results array and optional paging cursor for additional pages. It supports limiting the number of records returned and accepts an 'after' cursor to fetch subsequent pages. Command-line flags control limit and pagination; the skill also provides a formatted display summary for quick reading.

When to use it

When you need a quick list of companies in HubSpot for review or export
When you want paginated access to company records with a cursor for large datasets
When verifying company properties such as domain, industry, city, or employee count
When troubleshooting integrations that require checking company IDs and URLs
Before running operations that need a target company ID (e.g., updates or associations)

Best practices

Run the config pre-flight check before listing to ensure credentials and scopes are valid
Start with a small limit to preview results, then increase if needed
Use the 'after' cursor from the paging response to iterate through large result sets
Handle API rate limits (429) by backing off and retrying; ensure required scopes are granted
Filter or post-process the JSON output to extract only the fields your workflow needs

Example use cases

List the first 10 companies to verify recent imports or syncs
Fetch 25 companies to prepare a marketing outreach list with domains and phone numbers
Paginate through all companies to generate an external export or audit report
Locate a company ID quickly before creating associations or updating properties
Check for missing critical fields (e.g., domain or industry) to clean data

FAQ

What command checks setup before running the list?

Run the provided config check script to verify credentials and required scopes before listing.

How do I get the next page of results?

Use the 'after' cursor value from the paging.next.after field and pass it to the list command.

What should I do if I get a 401 or 403 error?

A 401 indicates invalid token—re-run the authentication setup. A 403 indicates a missing scope; ensure crm.objects.companies.read is granted.