HubSpot Leads

Name: Leads API
Brand: HubSpot Leads
Availability: InStock

✓ Official Vendor SpecCRMDeal Pipelineoauth210 EndpointsREST

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.

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Leads API

Explore with Jentic

View OpenAPI Document

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.

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 Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

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.

Intent-based discovery

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.

Time to first call

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.

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.

HubSpot Leads

Connect the Leads to your agent

Capabilities

Start building with Leads API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs