Setup HubSpot Developer Account to use HubSpot API

Getting Started with HubSpot API – How to get HubSpot API key and Access Token

How to get HubSpot API key? How to get Hubspot Access Token? How to Refresh Access Token?

Howdy, wondering how you can get the HubSpot API setup done? Is it a complex process to get an Access Token, refresh token, client id, and client secret from HubSpot? How to use HubSpot Access Token for API calls? How to refresh Access Token using refresh token?

All the questions and doubts will be answered in this article. Don’t worry this article will help you out in understanding the process and will be there with you while you generate all the credentials you need to use HubSpot API.

Let’s dive in.

What is Hubspot API?

The HubSpot API is built to allow you to create a functional application or integration quickly and easily. HubSpot has several APIs to cover almost all possible client’s and developer’s needs.

All of the HubSpot APIs are organized around REST Conventions – if you have some experience with a REST API (also known as RESTful API) already. That’s great! many of the concepts used and discussed in this article will be familiar to you.

All API calls to HubSpot should be made to the https://api.hubapi.com base domain using some common methods (POSTGETPUTDELETE). JSON will be returned in all responses, including errors.

Since we have a rough idea of what is HubSpot API. Now it’s time to understand what are the requirement before using HubSpot API? How we can get Hubspot API? HubSpot API can be used by two ways of authentication/authorization :

  1. API keys Authentication
  2. Oauth Authentication

API Key Authentication

Generating API keys is one of the easiest processes, just need to follow the below steps.

1. Get HubSpot Account API key

Log in to your HubSpot Account. Click on “Setting”.

Scroll down and click on “Integration” > ”API key”.

There you go, now you must see the HubSpot key on your screen. Note down this Hubs[to API key in JSON file or notepad for now. Remember HubSpot API is valid for 6 months.

Note: If you are not able to see the above-mentioned label/buttons. It is possible that you need have Super Admin access to your account.

2. Test Hubspot API Key – Hubspot contact api call using API key

Create a python file named “sample.py”.

#!/usr/bin/python3
#Command to run code: python3 ./sample.py
import requests
import json
import urllib
#Define a variable with Hubspot API key.
hsapikey = “replace it with your HubSpot account API key”
#set the count, number of contacts you want to extract.
count = 1
#API url to make the call
api_url = "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey="+str(hsapikey)+"&count="+str(count)
#header keep it empty for now
headers = {}
#make a request
res = requests.get(url= api_url, headers = headers)
response_dict = json.loads(res.text)
 
print("\n response_dict :",response_dict)
 

After running the above code, if the API call is successful. You should see a JSON format result printed on the console. That will give you some details about a contact.

Which should look something like below JSON data.

response_dict : {'contacts': [{'addedAt': 154*******, 'vid': 1, 'canonical-vid': 1, 'merged-vids': [], 'portal-id': 54***00, 'is-contact': True, 'profile-token': 'AO_T-mOry2mmtYmBOhCtvj3bRimYtKXWkE4ORaPRaAWHVVwKlVDVy******...', 'profile-url': 'https://app.hubspot.com/contacts/54***00/contact/1', 'properties': {'firstname': {'value': 'Cool'}, 'lastmodifieddate': {'value': '15*******812'}, 'company': {'value': 'HubSpot'}, 'lastname': {'value': 'Robot (Sample Contact)'}}, 'form-submissions': [], 'identity-profiles': [{'vid': 1, 'saved-at-timestamp': 1549725367650, 'deleted-changed-timestamp': 0, 'identities': [{'type': 'EMAIL', 
'value': '[email protected]', 'timestamp': 1549725367540, 'is-primary': True}, {'type': 'LEAD_GUID', 'value': '91ec18a2**********', 'timestamp': 1549725367646}]}], 'merge-audits': []}], 'has-more': True, 'vid-offset': 1}

OAuth Authentication

1. Create a Developer Account and Hubspot App

Go to Hubspot Developer Account and create a new developer account. If you already have one you can use that too. Once you’re set up and signed in, you’ll start on the developer account homepage, where you’ll have the option to create your first app or create a test account. Click “Create an app”.

NOTE: You may create up to 100 apps per developer account.

Next, you’ll fill out some basic information and settings for your app. When users authenticate your app with their HubSpot account, they’ll see the name, description, logo, and any support contact info you provide on this page.

In the next tab, you’ll find your Auth settings, including the client ID and client secret. This is also where you’ll set up scopes for your app. You’ll need this information for initiating an OAuth connection between your app and HubSpot.

2. Get the Code for Authentication

To initiate OAuth Access, you’ll need to send HubSpot users to your authorization URL. Use the query parameters detailed below to identify your app and outline its required scopes to users who land on the authorization page.

Users must be signed into HubSpot to grant their app access. Any user that isn’t logged into HubSpot will be directed to a login screen before being directed back to the authorization page.

The authorization screen will show the details for your app and the permissions being requested (based on the scopes you include in the URL). Users will have the option to select the Hub ID for the account they wish to grant access to.

After the user grants access, they will be redirected to the specified redirect_uri. A code query parameter will be appended to the URL, which you’ll use to get an access token from HubSpot.

POST URL: https://app.hubspot.com/oauth/authorize
Data:client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/

The URL should look something like the below one. Run this code in your browser (FYI: I used chrome) and follow the steps to grant access.

https://app.hubspot.com/oauth/authorize?client_id=<replace this with your app client id>&redirect_uri=http://localhost:8090/&scope=contacts

You should be redirected to the login page of HubSpot.


After completing the process you must see “code=” in the URL. Below is the example to give an idea of how its gonna look -> code=beeb6fee-639c-4b82-8d8e-cbd0ff7b628b

3. Generate the HubSpot Access Token and Refresh Token

Use the code you get after a user authorizes your app to get an access token and refresh token. The access token will be used to authenticate requests that your app makes. Remember access tokens expire after six hours, so you can use the refresh token to get a new access token when the first access token expires.

POST URL:https://api.hubapi.com/oauth/v1/token
Headers:Content-Type: application/x-www-form-urlencoded;charset=utf-8
Data:grant_type=authorization_code&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&redirect_uri=https://www.example.com/&code=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

The URL should look something like this. Run this code with post methods in postman.

https://api.hubapi.com/oauth/v1/token?grant_type=authorization_code&client_id=<replace with client id>&client_secret=<replace with client secret>&redirect_uri=http://localhost:8090/&code=<replace with code>

If successful, you will receive a JSON response with the tokens:
{
  "access_token": "xxxx",
  "refresh_token": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
  "expires_in": 21600
}
 
If there are any problems with the request, you'll receive a 400 response with an error message.
{
  "status": "EXAMPLE_ERROR_CODE",
  "message": "A human-readable error message",
  "correlationId": "da1e1d2f-fa6b-472a-be7b-7ab9b9605d59",
  "requestId": "ecc0b50659814f7ca37f5d49cdf9cbd3"
}

4. How to Refresh Access Token?

Use a previously obtained refresh token to generate a new access token. If you need offline access to HubSpot data, store the refresh token, you get when initiating your OAuth integration and use it to generate a new access token once the initial one expires.

POST URL: https://api.hubapi.com/oauth/v1/token
Headers:  Content-Type: application/x-www-form-urlencoded;charset=utf-8
Data:grant_type=refresh_token&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&refresh_token=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

The URL should look something like this. Run this code with post methods in postman.

https://api.hubapi.com/oauth/v1/token?grant_type=refresh_token&client_id=<Replace with client_id>&client_secret=<Replace with client secret>&refresh_token=<Replace with refresh token>&redirect_uri=http://localhost:8090/

If successful, you will receive a JSON response with a new access_token:
{
  "access_token": "xxxx",
  "refresh_token": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
  "expires_in": 21600
}
 
If there are any problems with the request, you'll receive a 400 response with an error message.
{
  "status": "EXAMPLE_ERROR_CODE",
  "message": "A human readable error message",
  "correlationId": "da1e1d2f-fa6b-472a-be7b-7ab9b9605d59",
  "requestId": "ecc0b50659814f7ca37f5d49cdf9cbd3"
}

Hooray! you have generated all the credentials needed to make a successful Hubspot API call.

5. Test Access Token by making HubSpot contact API call

Now let’s make our first API call using Hubspot Access Token through the OAuth authentication process. Diving in we are going to understand python code for Hubspot API call using Hubspot access token. I named below python file sample_oauth.py, you can name it as you want.

#!/usr/bin/python3
#Command to run code: python3 ./sample.py
import requests
import json
import urllib
#Define a variable with Hubspot API key.
access_token = "replace this with access token"
#set the count, number of contact you want to extract.
count = 10
#API url to make the call
api_url = "https://api.hubapi.com/contacts/v1/lists/14/contacts/recent?count="+str(count)
#header keep it empty for now
headers = {"Authorization": "Bearer "+access_token}
#make a request
res = requests.get(url = api_url, headers = headers)
response_dict = json.loads(res.text)
 
print("\n response_dict :",response_dict)
 

After the successful run of the above code, you see JSON output for 10 contacts. Where each contact data will look something like the below image.

response_dict : {'contacts': [{'addedAt': 154*******, 'vid': 1, 'canonical-vid': 1, 'merged-vids': [], 'portal-id': 54***00, 'is-contact': True, 'profile-token': 'AO_T-mOry2mmtYmBOhCtvj3bRimYtKXWkE4ORaPRaAWHVVwKlVDVy******...', 'profile-url': 'https://app.hubspot.com/contacts/54***00/contact/1', 'properties': {'firstname': {'value': 'Cool'}, 'lastmodifieddate': {'value': '15*******812'}, 'company': {'value': 'HubSpot'}, 'lastname': {'value': 'Robot (Sample Contact)'}}, 'form-submissions': [], 'identity-profiles': [{'vid': 1, 'saved-at-timestamp': 1549725367650, 'deleted-changed-timestamp': 0, 'identities': [{'type': 'EMAIL', 
'value': '[email protected]', 'timestamp': 1549725367540, 'is-primary': True}, {'type': 'LEAD_GUID', 'value': '91ec18a2**********', 'timestamp': 1549725367646}]}], 'merge-audits': []}], 'has-more': True, 'vid-offset': 1}

Congratulation! you have successfully set up and got the credentials needed to make a HubSpot API call. You can refer to python code to get the HubSpot contact data guide to learn how to use the above credentials. The ABove guide will also help you with developing a complete Python code for extracting data from HubSpot using HubSpot API, with proper code structuring.

For any suggestions or doubts ~ Get In Touch

Check out my other API Integration Guide