playbooks

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

hubspot-list-contacts skill

/00-system/skills/hubspot/hubspot-list-contacts

This skill lists HubSpot contacts with email, name, phone, and company, returning paginated results for easy browsing.

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

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-contacts
description: "List contacts from HubSpot CRM. Load when user says 'list contacts', 'show contacts', 'get contacts', 'hubspot contacts'. Returns paginated contact list with email, name, phone, company."
---

# List HubSpot Contacts

**Specialized skill** for listing contacts 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 contacts)
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/list_contacts.py --json
```

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

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

---

## Output Format

```json
{
  "results": [
    {
      "id": "12345",
      "properties": {
        "email": "[email protected]",
        "firstname": "John",
        "lastname": "Doe",
        "phone": "+1234567890",
        "company": "Acme Corp"
      },
      "url": "https://app.hubspot.com/contacts/.../record/0-1/12345"
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

Present results to user as:
```
Found {count} contacts:

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

2. Jane Smith
   Email: [email protected]
   ...
```

---

## 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-create-contact` - Create new contact
- `hubspot-search-contacts` - Search by email/name
- `hubspot-update-contact` - Update existing contact

Overview

This skill lists contacts from HubSpot CRM and returns a paginated contact list with key fields like email, name, phone, company, and contact ID. It is designed for quick retrieval of recent contacts or for browsing large contact sets with cursor-based pagination. Results are formatted for easy display and follow HubSpot API conventions.

How this skill works

The skill calls the HubSpot Contacts API to fetch contact records and returns results along with paging cursors for subsequent requests. Each contact includes id, properties (email, firstname, lastname, phone, company) and a link to the HubSpot record. It supports limit and after (cursor) parameters to control page size and pagination. The skill performs a config check before operation to ensure credentials and scopes are valid.

When to use it

  • Quickly view a list of recent contacts in HubSpot
  • Bulk-browsing contacts with pagination for outreach or review
  • Confirm contact details (email, phone, company) before follow-up
  • Integrate into workflows that need a contact roster or directory

Best practices

  • Run the configuration check before first use to verify tokens and required scopes
  • Request a reasonable limit (default 10) to avoid hitting rate limits
  • Use the returned paging.after cursor to fetch the next page reliably
  • Handle common HTTP errors: 401 (invalid token), 403 (missing crm.objects.contacts.read scope), 429 (rate limited)

Example use cases

  • "List contacts" to get the first page of contacts for a sales call list
  • Fetch 25 contacts with --limit 25 to prepare a batch email campaign
  • Use the after cursor to paginate through contacts for data export or cleanup
  • Verify a contact’s phone and company quickly before a meeting

FAQ

What fields are returned for each contact?

Each contact includes id, email, firstname, lastname, phone, company, and a HubSpot record URL when available.

How do I get more contacts than the default?

Specify a larger limit parameter and use the paging.after cursor to retrieve subsequent pages.

What if I get a 401, 403, or 429 error?

401 means invalid token—re-run setup; 403 indicates missing crm.objects.contacts.read scope; 429 means rate limited—wait and retry.