HubSpot Leads
Browse all Hubspot APIs✓ Official Vendor SpecCRMDeal Pipelineoauth210 EndpointsREST
For Agents
Create, search, and update HubSpot lead records used in the Sales Hub prospecting workspace, including batch operations.
Use for: I need to push a new prospect into the HubSpot leads workspace, I want to update a lead's qualification status after an SDR call, Search for all leads assigned to a specific rep that are still in qualifying stage, List leads created in the last 24 hours for outreach
Not supported: Does not handle contact-record management, deal pipeline progression, or marketing email outreach — use for HubSpot prospecting lead records only.
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.
Install Jentic One Beta
Connect the Leads to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Leads, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Leads API.
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
Patterns agents use Leads API for, with concrete tasks.
★ 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.
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.
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.
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
10 endpoints — the hubspot crm leads api exposes the lead object that sits between contacts and deals in the hubspot sales hub prospecting workspace.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth and Private App tokens are stored encrypted in the Jentic vault. Agents receive scoped access references, never raw tokens.
Intent-based discovery
Agents search by intent (e.g., 'create a HubSpot lead') and Jentic returns the matching leads operations with full input schemas, including the associations array shape.
Time to first call
Direct integration: 1-2 days to handle OAuth, batch sync, and search query construction. Through Jentic: under 30 minutes.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Leads API through Jentic.
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.
GET STARTED