Generate New Business With HubSpot's Leads API

Hey y', all, It's Brooke from HubSpot. Today I'm going to introduce you to the leads API. Did you know that HubSpot now has a Leads object? This object helps you manage your leads more efficiently and associate them with contacts and companies in your CRM. And now you can use the Leads API endpoints to create and manage lead records, as well as sync lead data between HubSpot and other systems. And did you know that you can actually test API endpoints within the developer docs? Today I'm going to show you how you can make test calls through the developer documentation. So on our developer documentation homepage in the main navigation on the left hand side, we're going to click on CRM and then we're going to click on Objects, and finally we'll click on Leads. The first thing you'll see is an introduction that tells you a bit more about what the Leads API does and the use cases for this API. In the right hand sidebar, you can actually choose which endpoints you want to look at based on whether they're batch endpoints, basic endpoints, or search inputs. For this one, we're going to use the basic Create input. So we're going to click on the basic and then you'll see all of the different endpoints that are considered a basic endpoint and the different CRUD methods that you use in order to call them. So now we're going to click on the Create, which will be a POST method, and this will tell you all of the requirements that you need to make this API call properly. So now we're going to scroll down to our parameters. So the first parameter that you need to add is the associations parameter. In this one you're going to define whether the association is HubSpot defined, user defined, or integrator defined. We're going to stick with a HubSpot defined, which means that we're going to use the standard CRM objects. In order to use this, we need the association type id. So to show you what the different association type ID numbers are, let's go over to the Associations documentation. On the Associations documentation page, scroll down until you see association type ID values. Now for leads, we're going to look for lead to object. So if we keep scrolling down, we'll see a table that reads lead to object. This will give us all of the different type IDs for all the different lead to object associations. We're going to do a lead to primary contact association. So we're going to use the type ID578. So now we're going to take this number and add it to our Leads API endpoint. So here where it says association type ID, you're just going to type in 578 and then you have to say to which object? And this takes in the ID of the object. So in order to find our ID of our object, we're going to actually go into our HubSpot account. Inside of our HubSpot account, in the main navigation, we're going to click on CRM and then Contacts, and I'm just going to go ahead and pick the top one here, Jason Mendoza. So we're going to click on his name. So now that we're on the Contact Record page, we're going to click on Actions and then we're going to click on View All Properties. And then we're just going to search for ID Under Contact information, you should see the record id. So now we can go ahead and copy this record id. Now let's go back to the Leads API endpoint. Now on our Leads API Endpoint page in the ID section, we're going to add in our record number that we just copied over. And finally we have to add in our properties. So for this to work, you have to have three properties that you're going to send along with your data. So the first one is going to be the HS lead name. And so for this one we're just going to call it Jason Mendoza. And then we need the HS lead label, and the third one is the HS lead type. So to understand what the different lead labels and lead types are, let's go back into our HubSpot account so I can show you all of the properties that are with the Leads object. Back in our HubSpot account, in the top navigation, click on the settings icon. And then in the right hand sidebar, we're going to scroll until we see objects and then we're going to click on Leads. If you've never used leads before, this will actually ask you to set up leads. But since I've already done this inside of this account, I'm going to go ahead and click on Manage Lead Properties. This page shows you all of the different lead properties that come with this standard. So now let's search for Lead Label so we can understand what a lead label does. So a lead label is a dropdown selection, and the different options you have are hot, warm and cold. So for this one, let's just say that the lead label is going to be warm. So now let's Search for lead type. Lead type is also a dropdown selection. So if you click on this it'll show you the different ones and you can add as many labels as you would like to each of these if you want them to be different from the standard. So this one has new business, upsell or reattending and then it will also have the internal values. Whenever you send along stuff with the API endpoints, you need to make sure that you type it just like it shows in the internal value. So we're going to do new underscore business for the lead type. Now let's go back to the API endpoint. So in our lead label we're going to choose warm and that's all capital letters. And then in lead type we're going to do new underscore business. So now if we scroll up and we look at our request, it should have all of the information that we put in. So if we scroll down to the area that says request write and it shows our associations first it'll say what type? We're doing a HubSpot defined one and it's going to be lead to primary contact, which is 578 and it's going to be to the contact with the ID shown here. And then it'll also show the properties that we're going to send along the HS lead name, lead label and lead type. The final thing that we need to do in order to make this call is to create a private app. So let's go back to our HubSpot account. In our HubSpot account, since we're on the Settings page already, let's click on integrations and then click on Private apps. Now on this page we're going to go ahead and click on Create a Private app. A private app will give you a token that you can use within the documentation in order to make this call. Let's just keep the basic information the same and then go over to the scopes. In order for this to work, let's click on the CRM. We need the CRM objects contactread. We don't need the write, we're not writing to it, we're just reading the information there. And then we need the CRM objects, leads, read and write. And now in the top right we're going to click on Create app. In the popup we're going to click on Continue creating. And then in the new pop up we're going to click on show token and then copy. And finally we're just going to use the X to X out of this. Now let's go back to the API endpoint documentation here. To run our request, we're going to click on the test call button and then we're going to choose from make a test call using Private App Access token. And then you're just going to paste in your Private App access token and you're going to click Send request. And it is a post request, so it will add data to your HubSpot account. So you're just going to say confirm post request. And now we're going to look at our response. Great, it worked because it shows an HTTP 201, which means that it was created. So now let's see where this lead lives in our HubSpot account. In the main navigation, we're going to click on workspaces and then we're going to click on prospecting. This workspace is a new area. A note about the prospecting tab, only people that are assigned a sell seat can see this, so make sure that whoever owns this contact will be able to see the leads because they have a sell seat. So now in the prospecting, we're going to click on the tab leads and then we'll see our lead. It will have the lead name, the label, the company and the stage. And then if you scroll over, you'll also see the lead type. And if you click on the name, it'll pull up the contact record right here and show you all the information. You can change the lead type from new business to upsell or reattempting. Additionally, you can add more lead types and you can change the stage from new to attempting, connected, qualified or disqualified. Awesome. So now you can create leads with the API. This is super helpful if you're creating an external integration that where you want to sync lead data between HubSpot and other systems and create leads automatically for your users so that they don't have to worry about recreating leads within HubSpot. Thanks so much for watching. Make sure to check out the documentation linked in the description below. Like this video? Subscribe to the HubSpot Developers YouTube channel and I'll see y' all in another video. Bye bye.