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

hubspot-list-notes skill

safe

/00-system/skills/hubspot/hubspot-list-notes

This skill lists HubSpot CRM notes and returns recent note records, helping you quickly review contact history.

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

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

Files (1)

SKILL.md

1.9 KB

---
name: hubspot-list-notes
description: "List note engagements from HubSpot CRM. Load when user says 'list notes', 'show notes', 'note history', 'hubspot notes'. Returns logged note records."
---

# List HubSpot Notes

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

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

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

---

## Output Format

```json
{
  "results": [
    {
      "id": "16977760701",
      "properties": {
        "hs_note_body": "<p>Important note about this contact...</p>",
        "hs_timestamp": "2025-12-13T10:00:00Z"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}
```

---

## Display Format

```
Found {count} notes:

1. Note ID: 16977760701
   Date: 2025-12-13 10:00
   Content: Important note about this contact...

2. Note ID: 16977942725
   Date: 2025-12-12 15:30
   Content: Meeting follow-up...
```

---

## Note Content

- Notes can contain HTML formatting
- Strip HTML tags for plain text display
- Notes may include links, lists, and formatted text

---

## Error Handling

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

---

## Related Skills

- `hubspot-create-note` - Create new note
- `hubspot-get-associations` - Get note's linked contacts

Overview

This skill lists note engagements from HubSpot CRM and returns logged note records in a structured JSON form. It provides paginated results, strips HTML for readable display, and includes timestamps and note IDs. Use it to quickly review recent note history across contacts and objects.

How this skill works

The skill queries HubSpot's notes endpoint and returns note objects with properties like body and timestamp. It supports limits and pagination cursors, and will strip HTML tags for plain-text previews while preserving links and formatting metadata in the raw output. Errors map to common HubSpot issues (authentication, scopes, rate limits) so you can remediate quickly.

When to use it

Review recent notes across contacts, companies, or deals.
Audit communication history before customer calls or meetings.
Export a page of notes for reporting or QA.
Detect missing follow-ups or summarize recent engagement context.

Best practices

Run a config/auth check before calling the skill to ensure credentials and scopes are valid.
Use a reasonable --limit to avoid rate limits; paginate when large datasets are needed.
Strip HTML for display but keep raw body for storage or downstream parsing.
Handle 401/403/429 errors programmatically and implement retry/backoff for rate limits.
Request only needed properties to minimize payload size.

Example use cases

Show the 10 most recent notes before a customer meeting to refresh context.
Fetch 25 notes when preparing a weekly engagement summary for a sales rep.
Paginate through notes for a compliance review or audit trail export.
Quickly surface note timestamps and plain-text excerpts to include in a handoff document.

FAQ

What if notes contain HTML?

The skill strips HTML for plain-text previews but preserves the raw HTML in the returned properties for any downstream parsing or rendering.

How do I handle pagination?

Use the provided cursor from the paging.next.after field to request the next page and repeat until no cursor is returned.

Which errors should I expect and how to fix them?

401 indicates invalid or expired token; re-authenticate. 403 means missing crm.objects.notes.read scope; update app scopes. 429 indicates rate limiting; implement backoff and retry.