CRM API | Leads - HubSpot docs

Scope requirements

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 leads, 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 contact.
Should only be assigned to a user with a seat. (Leads can only be worked via the workspace).

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. See the table below for some common properties for leads:

Property	Description
`hs_lead_name`	The full name of the lead.
`hs_lead_type`	A dropdown list of lead types. You can edit or add new types in your lead property settings.
`hs_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 must associate the lead with existing records in an associations object provided in the request body. In the associations object, you should include the following:

Parameter	Description
`to`	The record 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.

For example, to create a warm lead named “Jane Doe” who has a type of New Business, your request body would resemble the following:

{
  "associations": [
    {
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 578
        }
      ],
      "to": {
        "id": "12345"
      }
    }
  ],
  "properties": {
    "hs_lead_name": "Jane Doe",
    "hs_lead_type": "NEW BUSINESS",
    "hs_lead_label": "WARM"
  }
}

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:

Parameter	Description
`properties`	A comma separated list of the properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a lead doesn’t have a value, it will be returned as `null`.
`propertiesWithHistory`	A comma separated list of the current and historical properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a lead doesn’t have a value, it will be returned as `null`.
`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 leads

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/{leadId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. If you remove all primary associations to the lead, the lead will automatically be deleted.

Delete leads

You can delete leads individually or in batches, which will add the lead to the recycling bin in HubSpot. You can later restore the lead within HubSpot. To delete an individual lead by its ID, make a DELETE request to /crm/v3/objects/leads/{leadId}. Learn more about deleting leads in the reference documentation.

Limits

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

​Create leads

​Properties

​Associations

​Retrieve leads

​Update leads

​Associate existing leads with records

​Remove an association

​Delete leads

​Limits

Create leads

Properties

Associations

Retrieve leads

Update leads

Associate existing leads with records

Remove an association

Delete leads

Limits