Leads

Name: Leads API
Brand: HubSpot Leads
Availability: InStock

✓ Official Vendor SpecCRMDeal Pipelineoauth210 EndpointsREST

For Agents

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

Quickstart

Get started with Leads in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"create a HubSpot lead and link it to a contact"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

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

GET STARTED

Start building with Leads API

Explore with Jentic

View OpenAPI Document

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.

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

Why though 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.

Complementary

HubSpot CRM Contacts

Each lead references an underlying contact record

Use CRM-contacts when you need to read or update the underlying person record rather than the prospecting lead

Complementary

HubSpot CRM Deals

Qualified leads are typically converted to deals in HubSpot

Use CRM-deals to create the downstream deal record after a lead is qualified

Alternative

Salesforce REST API

Salesforce Lead object covers the same prospecting role outside HubSpot

Choose Salesforce when the target CRM is Salesforce rather than HubSpot

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.