HubSpot CRM Notes
After a sales call, write the summary straight onto the HubSpot record: create notes on contacts, companies, deals or tickets, find earlier notes by record, owner or date with CRM search, and correct or batch-load notes. hs_note_body keeps the rich text your team sees on the timeline.
Connect this API to an AI agent Browse all specs
What you can do with HubSpot CRM Notes via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| POST | /crm/objects/2026-09/notes/search |
searchNotes | Find notes by associated record, owner, date or text |
| GET | /crm/objects/2026-09/notes |
listNotes | List notes page by page with the properties you choose |
| POST | /crm/objects/2026-09/notes |
createNote | Add a note to a contact, company, deal or ticket |
| GET | /crm/objects/2026-09/notes/{noteId} |
getNote | Get one note with its text and associated records |
| PATCH | /crm/objects/2026-09/notes/{noteId} |
updateNote | Edit a note's text, timestamp or owner |
| POST | /crm/objects/2026-09/notes/batch/read |
batchReadNotes | Read up to 100 notes at once by id |
| POST | /crm/objects/2026-09/notes/batch/create |
batchCreateNotes | Create up to 100 notes in one call |
| POST | /crm/objects/2026-09/notes/batch/update |
batchUpdateNotes | Update up to 100 notes in one call by id |
Authentication
private_app_token
Bearer token — sent as Authorization: Bearer <token>
HubSpot private app access token (or an OAuth access token), sent as Authorization: Bearer <token>.
How to get a credential
- In HubSpot, open Development (or Settings > Integrations) > Legacy apps / Private apps.
- Click Create legacy app > Private, and name it (e.g. VX Agents notes).
- On the Scopes tab add
crm.objects.contacts.readandcrm.objects.contacts.write(HubSpot uses these scopes for notes). - Create the app and copy the access token (
pat-...).
Permissions used
| Scope | Operations |
|---|---|
crm.objects.contacts.read |
listNotes, getNote, searchNotes, batchReadNotes |
crm.objects.contacts.write |
createNote, updateNote, batchCreateNotes, batchUpdateNotes |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing, expired or revoked | Copy the token again from the private app; rotate it if it was revoked. |
| 403 | Scope missing | Add the scope listed above to the app and save. |
| 400 | Bad property or association | Check property names (hs_note_body, hs_timestamp...) and association type ids. |
| 429 | Rate limit | Wait and retry; search allows about 5 requests per second. |
Store the token as a VX Agents credential (Bearer token).
Usage guide
Setup
- Add a HubSpot private app token (
pat-...) as a VX Agents Bearer credential, with scopescrm.objects.contacts.readandcrm.objects.contacts.write. - Optional: pin
propertiesonlistNotes/getNotetohs_note_body,hs_timestamp,hubspot_owner_id,hs_attachment_ids, otherwise HubSpot returns only a few default fields.
Log and review notes
- To read what was said before,
searchNoteswithfilterGroups, e.g. notes on one contact:associations.contactEQ<contact id>, or one rep's notes since a date:hubspot_owner_idEQ<owner id>andhs_timestampGTE<Unix ms>. Addsorts(hs_timestampdescending) andproperties. Page withafter. getNotefor one note; passassociations=contacts,companies,deals,ticketsto see which records it sits on.- To log a new note, show the text to the user and confirm, then
createNotewithproperties(hs_timestampis required;hs_note_bodyholds the text, HTML allowed) andassociations:{"to": {"id": "<contact id>"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 202}]}. Type ids: note to contact 202, company 190, deal 214, ticket 228. - To fix a note, confirm with the user, then
updateNotewith only the changed properties. - For many notes use
batchReadNotes,batchCreateNotesorbatchUpdateNotes(up to 100 inputs each).
Good to know
- Note properties:
hs_note_body(text, up to 65,536 characters),hs_timestamp(when it shows on the timeline),hubspot_owner_id,hs_attachment_ids(file ids separated by;). hs_timestamptakes Unix milliseconds or an ISO 8601 UTC time; search filters on dates use Unix milliseconds.- Owner ids are HubSpot user owner ids, not emails.
- Search returns at most 10,000 results per query and allows only a few requests per second; narrow the filters instead of paging far.
- Notes change customer records that the whole team sees: confirm before every create or update. Deleting notes is not part of this spec.
Source: HubSpot Notes API reference (https://developers.hubspot.com/docs/api-reference/latest/crm/activities/notes/guide), checked 2026-10-20.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “HubSpot CRM Notes” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.