HubSpot CRM Calls
Who did the team call this week, and what happened? Search logged calls by contact, owner, outcome or date, log a new call against a contact, company, deal or ticket with hs_call_body and hs_call_disposition, and fix or batch-load call records.
Connect this API to an AI agent Browse all specs
What you can do with HubSpot CRM Calls 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/calls/search |
searchCalls | Find calls by associated record, owner, outcome or date |
| GET | /crm/objects/2026-09/calls |
listCalls | List logged calls page by page with the properties you choose |
| POST | /crm/objects/2026-09/calls |
createCall | Log a call on a contact, company, deal or ticket |
| GET | /crm/objects/2026-09/calls/{objectId} |
getCall | Get one call with its notes, outcome and associated records |
| PATCH | /crm/objects/2026-09/calls/{objectId} |
updateCall | Edit a call's notes, outcome, duration or owner |
| POST | /crm/objects/2026-09/calls/batch/read |
batchReadCalls | Read up to 100 calls at once by id |
| POST | /crm/objects/2026-09/calls/batch/create |
batchCreateCalls | Log up to 100 calls in one request |
| POST | /crm/objects/2026-09/calls/batch/update |
batchUpdateCalls | Update up to 100 calls in one request 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 calls).
- On the Scopes tab add
crm.objects.contacts.readandcrm.objects.contacts.write(HubSpot uses these scopes for calls). - Create the app and copy the access token (
pat-...).
Permissions used
| Scope | Operations |
|---|---|
crm.objects.contacts.read |
listCalls, getCall, searchCalls, batchReadCalls |
crm.objects.contacts.write |
createCall, updateCall, batchCreateCalls, batchUpdateCalls |
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_call_body, hs_timestamp, hs_call_disposition...) 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
propertiesonlistCalls/getCalltohs_call_title,hs_call_body,hs_timestamp,hs_call_direction,hs_call_disposition,hs_call_duration,hs_call_status,hubspot_owner_id, otherwise HubSpot returns only a few default fields.
Review and log calls
- To see recent calls,
searchCallswithfilterGroups, e.g. calls with one contact:associations.contactEQ<contact id>, or one rep's calls since a date:hubspot_owner_idEQ<owner id>andhs_timestampGTE<Unix ms>. Addsorts(hs_timestampdescending) andproperties. Page withafter. getCallfor one call; passassociations=contacts,companies,deals,ticketsto see which records it is logged on.- To log a call, show the details to the user and confirm, then
createCallwithproperties(hs_timestampis required; alsohs_call_title,hs_call_body,hs_call_directionINBOUND/OUTBOUND,hs_call_durationin ms,hs_call_statuse.g. COMPLETED) andassociations:{"to": {"id": "<contact id>"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 194}]}. Type ids: call to contact 194, company 182, deal 206, ticket 220. - To fix a call, confirm with the user, then
updateCallwith only the changed properties. - For many calls use
batchReadCalls,batchCreateCallsorbatchUpdateCalls(up to 100 inputs each).
Good to know
hs_call_disposition(the outcome) takes an internal GUID, not a label; read existing calls to learn the GUIDs your account uses (e.g. Connected, Left voicemail).hs_timestamptakes Unix milliseconds or an ISO 8601 UTC time; search filters on dates use Unix milliseconds.hs_call_durationis in milliseconds.hs_call_recording_urlmust be an HTTPS link to an .mp3 or .wav file.- 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.
- Calls change customer records the whole team sees: confirm before every create or update. Deleting calls is not part of this spec.
Source: HubSpot Calls API reference (https://developers.hubspot.com/docs/api-reference/latest/crm/activities/calls/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 Calls” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.