How do I set up an API integration on HubSpot?

Utilising the HubSpot Developers’ portal in your application.

There are 2 methods of authentication using HubSpot’s API. First is via the HAPI Key, which although convenient, is less secure than the other method, OAuth 2.0.

With the HAPI key, you can access data in a HubSpot account like so:


Get Contact with ID:


With this method, getting data is quick, and if it’s a one-time action that’s needed (or every now and then), then this option might be more suitable as less setup is involved.

However, with OAuth 2.0, you will need to build a HubSpot app, and grant authorisation from there.

Start by creating a HubSpot Developers’ account, and select the ‘An app’ option. From there, you will see that you will have a new developer account listed when you log into HubSpot. Once you click inside, you will be faced with a screen that gives you the option to manage apps or test accounts:


It is useful to create a test account to test your new apps with, but we won’t get into that for now.

When you create a new app, you will be taken to the settings screen. Give your app a name and move onto the OAuth section.


At the bottom, select the scopes you require your app to be able to access within your HubSpot account, enter a redirection URL, and save your changes. The redirection can be any valid URL as it’s mainly used for HubSpot to return a ‘code’ back in order for your OAuth connection to gain access and refresh tokens. 

Once the page has been saved, you will notice that the OAuth URL has been updated. Paste this into your browser, and select the account you want to install the app on to get the ‘code’ required for the OAuth 2.0 process to create access and refresh tokens.

Once you get the token, you can make the API call.


Ruby Example (Get all contacts API):

uri = URI.parse(‘’)

http =, uri.port)

http.use_ssl = true

request =

request[‘Authorization’] = ‘Bearer #{token

response = http.request(request)



This will return the first 100 contacts in your HubSpot account in the response body.

In order to use this in a real application, a plugin or a library like OmniAuth (For Ruby on Rails applications) will probably be required unless you want to write all the logic from scratch. To see the strategies available for OmniAuth, click here.

Of course, API access is not the only thing you can do within HubSpot Apps. Other examples include:

  • Set up Workflow Extensions
  • Webhooks
  • Live API/Webhook monitoring
  • Timeline Events
  • CRM Cards


If you’d like to know more about API integrations, please contact one of our experts.