Skip to main content


In this example, we will show you how you can get started working with the HubSpot API to produce a working use case that lists the companies in a HubSpot CRM.

Before you start

You'll need a HubSpot Private App Access Token. Find out how to set that up in the HubSpot private apps documentation.

Install & Authorize Superface

The Superface CLI provides all the tooling needed to author the Comlinks for your integration.

Install with Homebrew
brew install superfaceai/cli/superface

If you don't have a Superface account already, you can sign up here. You can use your account to authenticate the CLI.

superface login

Prepare the documentation

HubSpot's APIs are available as Open API Specifications, for this use case we will use the Companies OAS document.

superface prepare "hubspot"

Once the documentation has been indexed, you should check that the API baseUrl and securityScheme are correct in the hubspot.provider.json file. You can copy the example below if needed:

"name": "hubspot",
"defaultService": "default",
"parameters": [],
"services": [
"baseUrl": "",
"id": "default"
"securitySchemes": [
"type": "http",
"scheme": "bearer",
"id": "bearerAuth"

Define your use case

superface new hubspot "list companies"

A file called will be created in the superface folder as a result. This is a Comlink file that decribes the input and output expectations that the API expects to achieve this use case.

To turn the Comlink profile into runnable code in either Node.js or Python, use the following command and include the name of the provider and a use case profile you want to work with.

superface map hubspot companies-management/read-companies

Add your API key

If you don't already have your HubSpot API key in your environment, you can add it to your .env file as HUBSPOT_API_KEY=<your-hubspot-api-key>.

Set up your inputs

In order to list the companies correctly, and to save you some time, you will need to modify the boilerplate code from the HubSpot documentation so it contains a real request object. From the superface folder, open (or .py if you created Python files) and modify the object in the usecase.perform() function.
limit: 1,
archived: false

Test it

To test it you can use the execute command.

superface execute hubspot companies-management/read-companies

If everything is successful you should see output similar to the response below:

"paging": {
"next": {
"after": "64878",
"link": ""
"results": [
"archived": false,
"archivedAt": null,
"createdAt": "2022-09-20T15:25:10.907Z",
"id": "64878",
"properties": {
"createdate": "2022-09-20T15:25:10.907Z",
"domain": "",
"hs_lastmodifieddate": "2022-09-20T15:25:21.684Z",
"hs_object_id": "64878",
"name": ""
"updatedAt": "2022-09-20T15:25:21.684Z"