How Do You Get Started With the HubSpot API?

To get started with the HubSpot API, developers must understand the core customer relationship management (CRM) object architecture and authenticate their integrations using OAuth 2.0. By mapping external data requirements to specific REST endpoints, businesses can build secure, bi-directional synchronisations that connect HubSpot natively to external enterprise applications.

Understanding HubSpot CRM Data Structures

Before writing any code, developers must understand how HubSpot structures its data. The main object architecture for HubSpot is simplified into four primary categories:

• Contacts: Information pertaining to an individual person. Uniquely identified by email address and a specific contact ID.
• Companies: Information pertaining to businesses. Uniquely identified by the Company Domain Name and a company ID.
• Deals: Information tracking an individual sales opportunity within a pipeline. Uniquely identified by a deal ID.
• Tickets: Information tracking customer support requests. Uniquely identified by an object ID.

These CRM objects can be associated with each other to create relationships, such as linking a Contact to a Deal. Additionally, developers can utilise HubDB, a relational database within HubSpot, to store non-sensitive data for dynamic website content.

API Architecture and Rate Limits

HubSpot APIs use a REST architecture. This includes standard HTTP verbs (GET, PUT, POST, DELETE). All API calls are made to the base domain (https://api.hubapi.com), and all request and response data is formatted in JSON.

To ensure platform stability, all calls to the HubSpot APIs are subject to rate limiting. These limits are determined by your HubSpot subscription tier. The standard allowance is 250,000 total calls per day and a maximum of 100 requests per 10 seconds. Integrations that exceed these limits will receive a 429 HTTP error response code.

Securing Integrations with OAuth 2.0

While API keys were historically used for prototyping, modern commercial integrations must use OAuth 2.0 for authentication. OAuth allows you to authorise your integration to work with specific components of the HubSpot API by assigning granular scopes.

The authorisation process follows a standard flow:

1. The application sends the user to the HubSpot OAuth 2.0 server.
2. The user reviews the requested permissions and grants access.
3. The user is redirected back to the application with an authorisation code.
4. The application exchanges this code for an Access Token and a Refresh Token.

The Access Token authenticates calls made to the HubSpot API. Because this token expires (typically after six hours), your application must use the Refresh Token to request a new Access Token automatically.

 {    headers: {      'Authorization': `Bearer ${ACCESS_TOKEN}`,      'Content-Type': 'application/json'    }  }

Data Mapping and Endpoint Planning

The most critical step in building a custom integration is mapping the object relationships between your external system and HubSpot. You must determine field types, object types, and whether the data synchronisation is one-way or bi-directional.

If standard properties do not match your data schema, you must create custom properties in HubSpot before initiating the API sync. Using middleware solutions like strutoIX, development teams can streamline this data transformation process securely.

When organisations deploy custom integrations using structured data mapping frameworks, they typically reach measurable time to value in an average of 32 days.*

[Results and timelines are based on historical programme data and defined scope. Your outcomes depend on data readiness, resourcing and agreed assumptions. See terms.]

Using Webhooks for Efficient Synchronisation

For bi-directional integrations, constantly polling the HubSpot API to check for new data is inefficient and consumes your rate limits quickly.

The Webhooks API offers a superior alternative. Webhooks trigger HTTP requests to a specified external endpoint whenever a specific event occurs in HubSpot, such as a contact being created or a deal property updating. Subscriptions are configured within your developer application dashboard, ensuring your external systems receive real-time updates securely.

People Also Ask

What is the HubSpot API used for?

The HubSpot API is used to build custom integrations that connect HubSpot natively to external business systems, such as enterprise resource planning (ERP) software or bespoke billing platforms, enabling seamless data synchronisation and process automation.

How do you authenticate the HubSpot API?

Commercial applications authenticate the HubSpot API using OAuth 2.0. This secure protocol generates an Access Token that verifies the application's identity and restricts its access to specific CRM scopes defined by the administrator.

What are the API rate limits in HubSpot?

HubSpot API rate limits depend on your software subscription tier. The standard limit is 250,000 calls per day, with a burst limit of 100 requests per 10 seconds. Exceeding these limits returns a 429 error code.

Are you planning a complex custom integration for your technology stack? Book an outcomes consultation to see how Struto designs, secures, and maps bespoke API integrations on HubSpot.