In HubSpot, leads are contacts or companies that are potential customers who have shown interest in your products or services. The leads endpoints allow you to create and manage lead records in your HubSpot account, as well as sync lead data between HubSpot and other systems.
Before using the API, be sure leads have been set up in your account.
Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.
To create new contacts, make a POST
request to /crm/v3/objects/leads
.
In the request body, include any details about the lead in a properties
object. Your new lead:
- Must have a lead name, specified using the hs_lead_name property.
- Must be associated with an existing contacts.
- Should only be assigned to a user with a seat. (Leads can only be worked via the workspace).
- For example, to create a warm lead named “Jane Doe” who has a type of New Business, your request body would resemble the following:
// Example POST request to /crm/v3/objects/leads
"associations": [
{
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId":578
}
],
"to": {
"id": "YOUR_CONTACT_ID"
}
}
]
"properties": {
"hs_lead_name": "Jane Doe",
"hs_lead_type": "NEW BUSINESS",
"hs_lead_label": "WARM"
}
Lead details are stored in lead properties. There are default HubSpot lead properties, but you can also create custom lead properties.
To view all available properties, you can retrieve a list of your account's lead properties by making a GET
request to /crm/v3/properties/leads
. Learn more about the properties API.
See the table below for some common properties for leads:
PROPERTY | DESCRIPTION |
---|---|
Lead name | The full name of the lead. |
Lead type | A dropdown list of lead types. You can edit or add new labels in your lead property settings. |
Lead label | The current status of the lead. You can edit or add new labels in your lead property settings. |
When creating a new lead you can also associate the lead with existing records or activities in an associations object. For example, to associate a new lead with an existing contact with an ID of 12345, your request would look like the following:
xxxxxxxxxx
// Example POST request to /crm/v3/objects/leads
"properties": {
"hs_lead_name": "Jane Doe",
"hs_lead_type": "NEW BUSINESS",
"hs_lead_label": "WARM",
}
In the associations object, you should include the following:
Parameter | Description |
---|---|
to | The record or activity you want to associate with the lead, specified by its unique id value. |
types | The type of the association between the lead and the record/activity. Include the associationCategory and associationTypeId . Default association type IDs are listed here, or you can retrieve the value for custom association types (i.e. labels) via the associations API. |
You can retrieve leads individually or in batches.
- To retrieve an individual lead, make a
GET
request to/crm/v3/objects/leads/{leadsId}
. - To request a list of all leads, make a
GET
request to/crm/v3/objects/leads
.
For these endpoints, you can include the following query parameters in the request URL:
Parameter | Description |
---|---|
properties | A comma separated list of the properties to be returned in the response. If the requested contact doesn't have a value for a property, it will not appear in the response. |
propertiesWithHistory | A comma separated list of the current and historical properties to be returned in the response. If the requested contact doesn't have a value for a property, it will not appear in the response. |
associations | A comma separated list of objects to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API. |
- To retrieve a batch of specific leads by ID, make a
POST
request tocrm/v3/objects/leads/batch/read
. The batch endpoint can't retrieve associations. Learn how to batch read associations with the associations API.
For the batch read endpoint, you can use the optional Property
parameter to retrieve leads by leadID
or a custom unique identifier property. By default, the id
values in the request refer to the record ID (hs_object_id
), so the idProperty
parameter isn't required when retrieving by record ID. If you're using a custom unique value property to retrieve leads, you must include the idProperty
parameter.
You can update leads individually or in batches. For existing leads, the leads ID is a unique value, so you can use leadsId
to update leads via the API.
To update an individual lead by its lead ID, make a PATCH
request to /crm/v3/objects/leads/{leadsId}
, and include the data you want to update in the request body.
To associate a lead with other CRM records or an activity, make a PUT
request to /crm/v3/objects/leads/{leadsId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
To retrieve the associationTypeId
value, refer to this list of default values, or make a GET
request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Learn more about the associations API.
To remove an association between a lead and a record or activity, make a DELETE
request to the following URL: /crm/v3/objects/leads/{leadsID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
If you remove all primary associations to the lead, the lead will automatically be deleted.
You can delete contacts individually or in batches, which will add the contact to the recycling bin in HubSpot. You can later restore the contact within HubSpot.
To delete an individual contact by its ID, make a DELETE
request to /crm/v3/objects/contacts/{contactId}
.
Learn more about deleting contacts in the reference documentation.
Batch operations for creating, updating, and archiving are limited to batches of 100.