How to Setup Your HubSpot API Connection for Lead Generation

When we work with new clients on lead generation, one of the first steps that we take is to make sure we can connect to their Marketing Automation API so that we can pass new leads into the system. In this instance, we're going to be focusing on HubSpot and how to setup HubSpot for third-party lead generation. We created this documentation as an instructional post for our clients to maximize lead flow and conversions, and we want to share it with all B2B marketers. 

We do this using the HubSpot API. API stands for Application Program Interface, which is a set of tools and protocols that allow for different software platforms to interact with each other. HubSpot connects to over one hundred different platforms, including popular brands like Zapier, Wistia, and SalesForce. You can check out the complete list of available integrations over at the HubSpot Integrations Directory. You can also use your API key to connect your own custom-developed software and data.

To pass leads into your system, we’ll need to connect to your HubSpot account through the API. This will require a few steps on your part. The first step in that process is to gather the necessary information.

Step #1: Gather the Information You’ll Need to Allow API Connection

To gain access to your HubSpot API, which will allow third parties the ability feed leads into your account, you will need to provide them with a few different pieces of information. To find the information, you’ll have to navigate through a few different menus within your HubSpot account.

In this section, we’ll break down exactly what information you’ll need, and show you where to find it within the HubSpot system. Here are the first things that you’ll need to collect:

Information Needed for API Integration:

  • HubSpot API Key

  • HubSpot API Field Names

Your HubSpot API Key is the code that allows third parties to connect to your API. By inputting the key into another software suite, it allows outside tools and platforms to connect directly to your own account. The key also allows you to protect your own data from would-be intruders. Without the API key, you can’t connect to your account. You can also deactivate your API Key at any given time.

The “HubSpot API Field Names” refer to the different contact data fields within the HubSpot platform. They include things like a customer or lead’s first name, email, website and more.

Now let’s dive into how to access this information within your HubSpot account.

Obtaining your HubSpot API Key

Important: To access your HubSpot API Key within the HubSpot system, your user role must be Account Administrator or Marketing Administrator. This goes for any user that wants to access the HubSpot API key.

To access your HubSpot API key, please follow the link here: https://app.hubspot.com/keys/get.

This page can also be accessed by navigating to your account menu and selecting “Integrations.”

HubSpot API 1.png

Once you’re on the Integrations page, select “HubSpot API key” from the menu on the left-hand side of the page.

HubSpot API 2.png

Once on the API request page, account administrators will be able to click the orange, "View Key" button. Once you click the button, the API key for your account will be displayed. Please copy the API key and save it in a secure location.

HubSpot API 3.png

Obtaining Your HubSpot API Field Names


To have contact data sent to your HubSpot instance, you will need all of the internal property names associated with any visible and hidden fields you need data for.

To access your internal field names, start by clicking on the “Contacts” tab on the main menu at the top of the page, then select “Contacts” from the dropdown menu. You can see this menu here:

HubSpot API 4.png

Now you’ll be taken to a page that will allow you to search through all of the different data that you have available for the variety of different contacts in your HubSpot account. You’ll want to make sure that you stay on the “Contact properties” tab and not click on the “Company properties” or “Deal properties” tabs.

Now, start searching for the contact properties that you would like to include in our lead generation efforts in the “Contact properties” section.

Start by searching “First name” in the search field. This will bring up any properties that match your search. The “First name” property should appear in the “Contact information” section, like this:

HubSpot API 5.png

 

 

Click on “First name” to go to the property details page for that data point. This page will show you how many contacts you have in HubSpot that include data for the “First name” property.

At the bottom of the page, you’ll find the “Internal name” listed.

Here’s what it should look like:

HubSpot API 6.png

Store the internal field name, along with the label that it is attached to. You will need the internal name for each field that you want to populate with contact information.

Go back to the Contacts>Contacts page, and search for the next data property. Repeat the above steps, obtaining the internal name field name for every property that you will need data for. If there is a hidden property, you will need to provide those values as well.

Additionally, if a property has a normalized picklist (a dropdown field), you will need to provide each of the values for the picklist as well. Without every value, data will not send appropriately and may cause errors in the data delivery process.

You will want to provide all internal field names, along with any picklist or normalized data options, along with your HubSpot API Key to any individual, partner or third party that you would like to post to your HubSpot API.

Now let’s take a look at the next step.

Step #2: How to POST to the API

When you, or a third party, POST to the API, you are simply using the API to transfer data into the system. This is best demonstrated by showing you an example POST URL for HubSpot. Take note of the different aspects included within the URL itself:

Example POST URL:

https://api.hubapi.com/contacts/v1/contact/?hapikey=example

When properly filled out with real data, the POST URL gives HubSpot all the necessary information it needs to update its databases, including your HubSpot API, and the fields that will be populated.

As an example here is a HubSpot POST URL for creating or updating an email in the system:

https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/test@hubspot.com/?hapikey=demo

When you use the contacts API, the POST URL must be entered using an API REST client, or by performing the API call directly in your code.

Here’s a quick example of an API call:

Example POST body:


The code sample below represents an example JSON script with standard fields. This code will pass the body of your request through the API in order to create a new contact within the HubSpot system with all of the relevant data.
{
 "properties": [
   {
     "property": "email",
     "value": "testingapis@hubspot.com"
   },
   {
     "property": "firstname",
     "value": "Adrian"
   },
   {
     "property": "lastname",
     "value": "Mott"
   },
   {
     "property": "website",
     "value": "http://hubspot.com"
   },
   {
     "property": "company",
     "value": "HubSpot"
   },
   {
     "property": "phone",
     "value": "555-122-2323"
   },
   {
     "property": "address",
     "value": "25 First Street"
   },
   {
     "property": "city",
     "value": "Cambridge"
   },
   {
     "property": "state",
     "value": "MA"
   },
   {
     "property": "zip",
     "value": "02139"
   }
 ]
}
       
This code returns an HTTP 200 response on success, with the response body containing the details of the new contact record. Inside HubSpot, a new contact will be created with the values that were contained within the code.

That’s It!

This should give you a good overview of how to setup your HubSpot for lead generation with a partner and ensure that the correct data is passed into your system.