HubSpot CRM Tasks
What does each rep still owe a customer this week? Search HubSpot tasks by owner, due date and status, create follow-up calls, emails and to-dos tied to contacts, companies or deals, then mark them done or move the due date, one task or a batch at a time.
Connect this API to an AI agent Browse all specs
What you can do with HubSpot CRM Tasks 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/tasks/search |
searchTasks | Find tasks by owner, due date, status, type or any property |
| GET | /crm/objects/2026-09/tasks |
listTasks | List tasks page by page with the properties you choose |
| POST | /crm/objects/2026-09/tasks |
createTask | Create a task and link it to a contact, company or deal |
| GET | /crm/objects/2026-09/tasks/{taskId} |
getTask | Get one task with its properties and associated records |
| PATCH | /crm/objects/2026-09/tasks/{taskId} |
updateTask | Update a task: complete it, change its due date, owner or notes |
| POST | /crm/objects/2026-09/tasks/batch/read |
batchReadTasks | Read up to 100 tasks at once by id |
| POST | /crm/objects/2026-09/tasks/batch/create |
batchCreateTasks | Create up to 100 tasks in one call |
| POST | /crm/objects/2026-09/tasks/batch/update |
batchUpdateTasks | Update up to 100 tasks 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 tasks).
- On the Scopes tab add
crm.objects.contacts.readandcrm.objects.contacts.write(HubSpot uses these scopes for tasks). - Create the app and copy the access token (
pat-...).
Permissions used
| Scope | Operations |
|---|---|
crm.objects.contacts.read |
listTasks, getTask, searchTasks, batchReadTasks |
crm.objects.contacts.write |
createTask, updateTask, batchCreateTasks, batchUpdateTasks |
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_task_subject, 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
propertiesonlistTasks/getTasktohs_task_subject,hs_task_status,hs_task_priority,hs_task_type,hs_timestamp,hubspot_owner_id, otherwise HubSpot returns only a few default fields.
Review and follow up on tasks
searchTaskswithfilterGroups, e.g. open tasks for one rep due this week:hs_task_statusNEQCOMPLETED,hubspot_owner_idEQ<owner id>,hs_timestampBETWEEN two dates. Addsorts(hs_timestampascending) andproperties. Page withafter.getTaskfor one task; passassociations=contacts,companies,dealsto see who it is about.- To add a follow-up, confirm the details with the user, then
createTaskwithproperties(hs_timestampis required: the due date) andassociations:{"to": {"id": "<contact id>"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 204}]}links the task to a contact. Use the associations guide for company and deal type ids. - To complete or reschedule, confirm with the user, then
updateTaskwith only the changed properties, e.g.{"properties": {"hs_task_status": "COMPLETED"}}or a newhs_timestamp. - For many tasks at once use
batchReadTasks,batchCreateTasksorbatchUpdateTasks(up to 100 inputs each).
Good to know
- Task properties:
hs_task_subject(title),hs_task_body(notes),hs_task_status(NOT_STARTEDorCOMPLETED),hs_task_priority(LOW,MEDIUM,HIGH),hs_task_type(EMAIL,CALL,TODO),hubspot_owner_id,hs_task_reminders(Unix ms). 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 is limited to a few requests per second; narrow the filters instead of paging far.
- Deleting tasks is not part of this spec.
Source: HubSpot Tasks API reference (https://developers.hubspot.com/docs/api-reference/latest/crm/activities/tasks/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 Tasks” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.