HubSpot CRM Leads
For sales reps working the HubSpot prospecting workspace: search the lead queue by hs_lead_label or owner, open a lead with its contact, add a new lead for an existing contact, and move it along by updating its hs_lead_label, type or owner.
Connect this API to an AI agent Browse all specs
What you can do with HubSpot CRM Leads 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 |
|---|---|---|---|
| GET | /crm/objects/2026-09/leads |
listLeads | List leads page by page with chosen properties |
| POST | /crm/objects/2026-09/leads |
createLead | Create a lead for an existing contact |
| POST | /crm/objects/2026-09/leads/search |
searchLeads | Search leads by label, type, owner or date |
| GET | /crm/objects/2026-09/leads/{objectId} |
getLead | Get one lead with its properties and associated contact |
| PATCH | /crm/objects/2026-09/leads/{objectId} |
updateLead | Update a lead's label, type or owner |
| POST | /crm/objects/2026-09/leads/batch/read |
batchReadLeads | Read up to 100 leads by id in one call |
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>. Leads need Sales Hub Professional or Enterprise, with leads set up in the account.
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 leads).
- On the Scopes tab add
crm.objects.leads.readandcrm.objects.leads.write. - Create the app and copy the access token (
pat-...).
Permissions used
| Scope | Operations |
|---|---|
crm.objects.leads.read |
listLeads, getLead, searchLeads, batchReadLeads |
crm.objects.leads.write |
createLead, updateLead |
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, or leads not available on the plan | Add the scopes above and save; leads need Sales Hub Professional or Enterprise. |
| 400 | Bad property or association | Every new lead needs hs_lead_name and an association to an existing contact (type id 578). |
| 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.leads.readandcrm.objects.leads.write. Leads need Sales Hub Professional or Enterprise and must be set up in the account. - Optional: pin
propertiesonlistLeads/getLeadtohs_lead_name,hs_lead_type,hs_lead_label,hubspot_owner_id, otherwise HubSpot returns only a few default fields.
Work the lead queue
searchLeadswithfilterGroups, e.g. one rep's open leads:hubspot_owner_idEQ<owner id>, or warm leads:hs_lead_labelEQWARM. Addproperties,sorts(e.g.hs_createdatedescending) and page withafter.getLeadwithassociations=contacts,companiesto see who the lead is;batchReadLeadsreads up to 100 leads by id.- To add a lead, confirm the details with the user, then
createLeadwithproperties.hs_lead_name(required), optionalhs_lead_type(e.g.NEW BUSINESS) andhs_lead_label(e.g.WARM), andassociations:{"to": {"id": "<contact id>"}, "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 578}]}. Every lead must be linked to an existing contact. - To move a lead along, confirm with the user, then
updateLeadwith only the changed properties (e.g. a newhs_lead_labelorhubspot_owner_id).
Good to know
hs_lead_typeandhs_lead_labelare dropdowns whose options each account can edit; read a few leads first to learn the internal values.- Assign leads only to users with a Sales seat; leads are worked in the prospecting workspace.
- Dates in search filters use Unix milliseconds. Search returns up to 200 results per page and at most 10,000 per query, at a few requests per second.
- Deleting or merging leads is not part of this spec.
- Leads change records the whole sales team sees: confirm before every create or update.
Source: HubSpot Leads API reference (https://developers.hubspot.com/docs/api-reference/latest/crm/objects/leads/guide), checked 2026-10-23.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “HubSpot CRM Leads” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.