The Leads API is deprecated, and will be discontinued on December 31, 2013. If you need help migrating off of the API, please refer to our developer forum.


The new APIs that are offered as part of HubSpot3 have significant new functionality while preserving the core use cases that we saw customers using heavily.

Along with the new features there were several architectural changes that we are very excited about, that allow HubSpot to now scale to serve customers with hundreds of thousands or even millions of marketing contacts.

HubSpot3 marketers can now keep their contact database segmented automatically based on whatever is important to their business, whether it be information collected on forms and in imports, or website and email behavior, social media influence, and much more.

These major changes pave a road for what we believe is marketing transformation, and a world in which marketers can offer personalized experiences across a range of interactive media from their website, to email, to social media, SMS messaging and beyond.

Smart Lists: The Power of a Segmented Contact Database

By making use of the Lists area of the Contacts API you are helping to create a well-segmented marketing database of contacts to whom your company can communicate more effectively. HubSpot3 offers tools to create personalized experiences, through targeted email messages, dynamic website content and much more.

The core element of this massively powerful system is the idea of a list, particularly the idea of a Smart List, which is a list that HubSpot manages automatically for you, adding and removing contacts as they meet or fail to meet the criteria that are most important to your business.

By managing lists over the Contacts API you set your marketing team up for remarkable success. Inside HubSpot it’s easy and straightforward to choose to either send one-time emails to members of a list, or to automatically message them as they become part of the list, or to display alternate calls to action on the website. All of this personalization is accomplished using the idea of Smart Lists.

API users of Smart Lists may find the concept of the Smart List particularly useful for reporting purposes as well. Once the list is set up and initialized (which typically takes a minute or two) HubSpot keeps the list up to date. As the lists are kept up to date, the system can add contacts into HubSpot3 Workflows automatically.

Searching for Contacts

Contacts offers a new interface for search for contacts. There are three ways of locating a specific contact in the system.

  • If any stable identifier is known for the contacts (VID, Usertoken, or email address) then the lookup is as simple as requesting the resources.
  • If an identifier is not known for the contact, the Search resource can be used to query for contacts by first name, last name, email address, or company name. This endpoint is indexed and returns results nearly instantly. The limitation of this interface is that searching by additional or complex criteria are not possible.
  • For more complex lookups we recommend using the Lists interface.

Adding Contacts to HubSpot

There are two ways to add contacts using our APIs:

If you have worked with the HubSpot Leads API in the past you are likely familiar with the concept of the first option. Note that we have a new Forms API that we recommend you use for new integrations, though the legacy lead form submission API has been modified to route directly into Contacts.

The advantage of the second approach is that the developer can work entirely within the context of the main HTTP verbs of the Contacts API, without having to use a separate forms API. The disadvantage is that it is not possible to associate a usertoken (cookie) to the new contact, meaning that the contact will appear under "Offline Sources" in the Sources app.

What you need to do

If you are using the form submission aspect of the Leads API it is not critical that you move to the Contacts API, but we nevertheless recommend that you do so, favoring the new Forms component of the Contacts API.

If you are using the read and search aspects of the Leads API you should move to use the Lists portion of the Contacts API as soon as possible.

If you are using the read and search aspects of the Leads API you should move to use the Lists portion of the Contacts API as soon as possible.

When you need to do it

The Leads and Lead Nurturing APIs are now officially deprecated. They will continue to function until we retire them on December 31st, 2013. Our team is in the process of reaching out to customers on an individual basis to ensure that everyone has responded appropriately before removing these APIs from service.

If you have any questions while going through this process, please don’t hesitate to post them in our developer forum.