Leads

OverviewEndpoints

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.

Create leads

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" }

Properties

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:

Use this table to describe properties
PROPERTYDESCRIPTION
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.

Associations

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:

// 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:

Use this table to describe parameters / fields
ParameterDescription
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 associationCategoryand 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.

Retrieve leads

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:

Use this table to describe parameters / fields
ParameterDescription
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 to crm/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.

Update contacts

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.

Associate existing leads with records

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.

Remove an association

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.

Delete leads

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 batch deleting contacts on the Endpoints tab at the top of this article.

Limits

Batch operations for creating, updating, and archiving are limited to batches of 100. 

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.