canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-leads

# HubSpot Leads

The HubSpot CRM Leads API exposes the lead object that sits between contacts and deals in the HubSpot Sales Hub prospecting workspace. It supports create, read, update, archive, batch operations, and property-filtered search for lead records, allowing integrations to push prospect data into the prospecting queue and update qualification status as agents or reps progress them. It is the right entry point for connecting a SDR tool, lead-routing engine, or scoring model to HubSpot's prospecting workflow.

## For AI agents

Create, search, and update HubSpot lead records used in the Sales Hub prospecting workspace, including batch operations.

## Scope

Does not handle contact-record management, deal pipeline progression, or marketing email outreach - use for HubSpot prospecting lead records only.

## Capabilities

- Create individual or batched lead records and link them to existing contact and company records
- Search leads by property filters such as hs_lead_status, owner, or creation date
- Update lead qualification status, owner assignment, or custom scoring properties on a single record or in batch
- Archive disqualified leads to remove them from the active prospecting queue
- Read a batch of leads by ID or by a unique property value such as an external CRM ID

## Use cases

### Push MQLs into HubSpot Prospecting

When a marketing automation pipeline qualifies a contact as an MQL, create a corresponding lead record in HubSpot so the SDR team picks it up in the prospecting workspace. The Leads API accepts an associations array linking the lead to the source contact and company, which means the SDR sees full context the moment the lead lands. Throughput of several thousand leads per hour is achievable using POST /crm/v3/objects/leads/batch/create.

Example prompt: POST /crm/v3/objects/leads/batch/create with up to 100 lead records, each carrying an associations entry for the parent contact, then verify the response status array reports zero errors.

### Sync Lead Status from an External SDR Tool

Mirror lead status changes (working, qualified, disqualified) from a dialer or sales engagement platform back into HubSpot so reporting in the HubSpot CRM stays current. The batch update endpoint accepts up to 100 records per call keyed by the HubSpot lead ID. Most SDR-tool integrations run this sync every 1-5 minutes against the leads modified since the last sync watermark.

Example prompt: POST /crm/v3/objects/leads/batch/update with an array of {id, properties: {hs_lead_status}} entries reflecting the latest status from the upstream tool, capped at 100 per call.

### Agent-Driven Lead Triage

An AI agent can search for leads in a particular qualification stage, decide which to advance or disqualify based on enrichment data, and update properties accordingly. Through Jentic, the agent finds the search and update operations by intent, loads the input schemas, and chains them - useful for SDR copilots that surface the next-best-action across a queue of leads.

Example prompt: Search leads with hs_lead_status equals NEW and last_contacted older than 7 days via POST /crm/v3/objects/leads/search, then PATCH each via /crm/v3/objects/leads/{leadsId} to set status to ATTEMPTED.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/leads | Create a lead |
| GET | /crm/v3/objects/leads | List leads |
| GET | /crm/v3/objects/leads/{leadsId} | Read a specific lead |
| PATCH | /crm/v3/objects/leads/{leadsId} | Update a lead |
| POST | /crm/v3/objects/leads/search | Search leads by property filters |
| POST | /crm/v3/objects/leads/batch/create | Create a batch of leads |

## Key resources

- **Leads** — Single-record CRUD plus batch read, create, update, archive, and search for HubSpot prospecting leads

## Why Jentic

- **Setup:** Wiring HubSpot Leads by hand means implementing its OAuth2 authorization-code flow (or managing a private-app token), posting to api.hubapi.com with the correct properties and associations array, and handling token refresh yourself. Through Jentic you install once, import HubSpot Leads from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** This API works against the leads object collection, with the lead id in the URL path (/crm/v3/objects/leads/{leadsId}) on reads and updates. Limit the agent to the operations it needs, such as creating and searching leads, so an update or batch create path is not included unless you add it.
- **Credential handling:** Your HubSpot token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot lead' or 'search prospecting leads', and Jentic returns the matching leads operation with its input schema, including the associations array shape, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Contacts** — Each lead references an underlying contact record
- **HubSpot CRM Deals** — Qualified leads are typically converted to deals in HubSpot
- **Salesforce REST API** — Salesforce Lead object covers the same prospecting role outside HubSpot

## FAQ

### What authentication does the HubSpot Leads API use?

OAuth 2.0 Bearer tokens or HubSpot Private App tokens in the Authorization header. Jentic stores the token encrypted in the vault and gives the agent a scoped reference, so the raw token never enters the agent's prompt or context.

### Can I link a new lead to an existing contact in one call?

Yes. POST /crm/v3/objects/leads accepts an associations array on the request body so the new lead is linked to a contact, company, or deal at creation time without a separate association call.

### What are the rate limits for the HubSpot Leads API?

Standard HubSpot account-wide limits apply: 100 requests per 10 seconds for OAuth apps and 110 for Private Apps, with daily caps that vary by Hub subscription. Batch endpoints count as a single request regardless of how many records they carry, which is the recommended pattern for high-volume sync jobs.

### How do I search for leads by status through Jentic?

Run pip install jentic, call client.search('search HubSpot leads by status'), client.load to get the schema for POST /crm/v3/objects/leads/search, and client.execute with filterGroups targeting hs_lead_status. Pagination uses an after cursor returned in the response.

### Is the HubSpot Leads API the same as the Contacts API?

No. Leads and contacts are separate objects in HubSpot. Contacts are the long-lived person records, while leads are short-lived prospecting records that live in the Sales Hub prospecting workspace and reference an underlying contact via association.

### How do I bulk-disqualify leads that match a filter?

First call POST /crm/v3/objects/leads/search to get IDs matching the filter, then call POST /crm/v3/objects/leads/batch/archive with up to 100 IDs per call. Archiving removes leads from the active prospecting queue without permanently deleting them.

### Can I limit what my agent is allowed to do with the HubSpot Leads API?

Yes. Because you self-host Jentic One, your own rules decide which leads operations and credentials the agent can use. You can allow it to only create and search leads through POST /crm/v3/objects/leads and POST /crm/v3/objects/leads/search, while withholding update, batch create, or archive paths such as PATCH /crm/v3/objects/leads/{leadsId} until you choose to grant them. The agent can call only the operations you enable, so it cannot reach the wider leads object collection on its own.