# How to Develop Integrations with the HubSpot API: Complete Guide for Developers in 2026 ## Table of Contents - [Introduction](#introduction) - [Types of HubSpot APIs](#types-of-hubspot-apis) - [Authentication: OAuth 2.0 and Private Apps](#authentication-oauth-20-and-private-apps) - [CRM Objects API: Contacts, Companies and Deals](#crm-objects-api-contacts-companies-and-deals) - [Marketing API: Emails, Forms and Landing Pages](#marketing-api-emails-forms-and-landing-pages) - [HubSpot Webhooks](#hubspot-webhooks) - [CMS API: Pages, Blogs and Files](#cms-api-pages-blogs-and-files) - [API Limits and Rate Limiting Management](#api-limits-and-rate-limiting-management) - [Integration Development Best Practices](#integration-development-best-practices) - [Publishing an Integration on the HubSpot Marketplace](#publishing-an-integration-on-the-hubspot-marketplace) - [Frequently Asked Questions](#frequently-asked-questions) - [Conclusion](#conclusion) - [References](#references) --- ## Introduction The HubSpot API is one of the most complete and well-documented CRM APIs on the market. In 2026, HubSpot offers more than 100 endpoints organised into specific APIs for each hub (CRM, Marketing, Sales, Service, CMS, Operations). This guide is aimed at developers who need to integrate external systems with HubSpot, whether to synchronise data, automate processes or create applications to publish on the HubSpot Marketplace. --- ## Types of HubSpot APIs HubSpot offers several types of APIs depending on the use case: | API | Description | Use Cases | |---|---|---| | CRM API | Management of contacts, companies, deals, tickets, custom objects | Data synchronisation, CRM integrations | | Marketing API | Emails, forms, landing pages, lists, campaigns | Marketing automation, reporting | | Sales API | Deals, pipelines, meetings, quotes | Sales integrations, sales automation | | Service API | Tickets, feedback surveys | Customer support integrations | | CMS API | Pages, blog posts, files, domains | Programmatic content management | | Operations API | Data sync, automation, datasets | Operations integrations | | Analytics API | Web traffic, events, conversions | Reporting and data analysis | --- ## Authentication: OAuth 2.0 and Private Apps HubSpot supports two main authentication methods: ### Private Apps (recommended for internal integrations) Private Apps are the simplest way to authenticate with the HubSpot API for internal integrations that only need to access one HubSpot account. ```javascript // Authentication with Private App Token const client = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN }); ``` To create a Private App: 1. Go to **Settings > Integrations > Private Apps**. 2. Click **Create a Private App**. 3. Assign a name and select the required scopes. 4. Copy the generated access token. ### OAuth 2.0 (recommended for Marketplace applications) OAuth 2.0 is the standard authentication method for applications that need to access multiple HubSpot accounts (Marketplace applications). ```javascript // OAuth 2.0 authorisation flow const authUrl = `https://app.hubspot.com/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=${SCOPES}`; // Exchange the authorisation code for an access token const tokenResponse = await fetch('https://api.hubapi.com/oauth/v1/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'authorization_code', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, code: authorizationCode }) }); const { access_token, refresh_token, expires_in } = await tokenResponse.json(); ``` --- ## CRM Objects API: Contacts, Companies and Deals The CRM Objects API is the most widely used HubSpot API. It allows contacts, companies, deals, tickets and custom objects to be created, read, updated and deleted. ### Create a Contact ```javascript const hubspot = require('@hubspot/api-client'); const client = new hubspot.Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN }); // Create a contact const contactResponse = await client.crm.contacts.basicApi.create({ properties: { email: '[email protected]', firstname: 'John', lastname: 'Doe', phone: '+44 7700 900000', company: 'Acme Corp', jobtitle: 'Marketing Director' } }); console.log('Contact created:', contactResponse.id); ``` ### Search Contacts ```javascript // Search contacts by email const searchResponse = await client.crm.contacts.searchApi.doSearch({ filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: '[email protected]' }] }], properties: ['email', 'firstname', 'lastname', 'phone'], limit: 10 }); const contacts = searchResponse.results; ``` ### Update a Contact ```javascript // Update contact properties await client.crm.contacts.basicApi.update(contactId, { properties: { lifecyclestage: 'customer', hs_lead_status: 'IN_PROGRESS' } }); ``` ### Create an Association Between Objects ```javascript // Associate a contact with a company await client.crm.associations.v4.basicApi.create( 'contacts', contactId, 'companies', companyId, [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }] ); ``` --- ## Marketing API: Emails, Forms and Landing Pages ### Send a Marketing Email ```javascript // Send a transactional email const emailResponse = await client.marketing.transactional.singleSendApi.sendEmail({ emailId: 12345, message: { to: '[email protected]', from: '[email protected]', replyTo: '[email protected]' }, customProperties: { first_name: 'John', company_name: 'Acme Corp' } }); ``` ### Get Form Submissions ```javascript // Get submissions for a specific form const submissionsResponse = await client.marketing.forms.formsApi.getPage(); const forms = submissionsResponse.results; // Get submissions for a specific form const formSubmissions = await fetch( `https://api.hubapi.com/form-integrations/v1/submissions/forms/${formId}`, { headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } } ); ``` --- ## HubSpot Webhooks HubSpot webhooks allow real-time notifications to be received when events occur in HubSpot (contact creation, property changes, form submissions, etc.). ### Configure a Webhook ```javascript // Create a webhook subscription const webhookResponse = await client.webhooks.subscriptionsApi.create({ eventType: 'contact.creation', propertyName: 'email', active: true }); ``` ### Process Webhook Events ```javascript // Express.js endpoint to receive HubSpot webhooks app.post('/webhooks/hubspot', express.json(), (req, res) => { const events = req.body; for (const event of events) { console.log('Event type:', event.subscriptionType); console.log('Object ID:', event.objectId); console.log('Property:', event.propertyName); console.log('New value:', event.propertyValue); // Process the event according to its type switch (event.subscriptionType) { case 'contact.creation': handleNewContact(event.objectId); break; case 'deal.propertyChange': handleDealChange(event.objectId, event.propertyName, event.propertyValue); break; } } res.status(200).send('OK'); }); ``` --- ## CMS API: Pages, Blogs and Files ### Create a Blog Post ```javascript // Create a blog post in HubSpot CMS const blogPostResponse = await client.cms.blogPosts.blogPostsApi.create({ contentGroupId: BLOG_ID, name: 'Article Title', slug: 'article-title', htmlTitle: 'Article Title - Emovere Blog', metaDescription: 'Article description for SEO', postBody: '

Article content in HTML

', featuredImage: 'https://cdn.example.com/image.jpg', state: 'PUBLISHED', publishDate: new Date().toISOString() }); ``` ### Upload a File ```javascript // Upload a file to the HubSpot File Manager const formData = new FormData(); formData.append('file', fileBuffer, { filename: 'image.jpg', contentType: 'image/jpeg' }); formData.append('folderPath', '/blog-images'); formData.append('options', JSON.stringify({ access: 'PUBLIC_INDEXABLE' })); const fileResponse = await fetch('https://api.hubapi.com/files/v3/files', { method: 'POST', headers: { Authorization: `Bearer ${ACCESS_TOKEN}` }, body: formData }); ``` --- ## API Limits and Rate Limiting Management HubSpot imposes API usage limits depending on the plan: | Plan | Daily Limit | Per 10 Seconds Limit | |---|---|---| | Free | 250,000 calls/day | 100 calls/10s | | Starter | 500,000 calls/day | 150 calls/10s | | Professional | 1,000,000 calls/day | 200 calls/10s | | Enterprise | 2,000,000 calls/day | 300 calls/10s | ### Rate Limiting Management ```javascript // Implement retry with exponential backoff async function apiCallWithRetry(apiCall, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await apiCall(); } catch (error) { if (error.code === 429) { // Rate limit exceeded - wait and retry const retryAfter = error.response?.headers?.['retry-after'] || Math.pow(2, attempt); console.log(`Rate limited. Retrying in ${retryAfter} seconds...`); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); } else { throw error; } } } throw new Error('Max retries exceeded'); } ``` --- ## Integration Development Best Practices **1. Use the official HubSpot SDK.** The official HubSpot SDK for Node.js (`@hubspot/api-client`) simplifies authentication, error handling and rate limiting. **2. Implement idempotency.** Integrations must be idempotent: processing the same event multiple times must not create duplicates or side effects. **3. Handle errors correctly.** Implement retry with exponential backoff for 429 (rate limit) and 5xx (server error) errors. **4. Use webhooks instead of polling.** Webhooks are more efficient than polling for receiving real-time updates. **5. Store tokens securely.** Never store access tokens in source code. Use environment variables or a secrets manager. **6. Implement logging and monitoring.** Log all API calls and errors to facilitate debugging. --- ## Publishing an Integration on the HubSpot Marketplace The HubSpot Marketplace has more than 1,500 integrations and is an excellent source of leads for developers and agencies. To publish an integration: 1. **Create a developer account** at developers.hubspot.com. 2. **Create an application** and configure the OAuth 2.0 flow. 3. **Develop and test** the integration in a sandbox account. 4. **Submit the integration** for review by the HubSpot team. 5. **Publish the integration** on the Marketplace. --- ## Frequently Asked Questions **What is the difference between the HubSpot v1 and v3 APIs?** HubSpot has gradually migrated from the v1 API (based on specific endpoints per object type) to the v3 API (based on CRM Objects with generic endpoints). In 2026, the v3 API is recommended for new integrations. **Can I use the HubSpot API for free?** Yes, the HubSpot API is available for all plans, including the free one. Usage limits vary depending on the plan. **Does HubSpot have a GraphQL API?** No, HubSpot does not offer a GraphQL API. All HubSpot APIs are REST. **Can I create custom objects with the HubSpot API?** Yes, the HubSpot Custom Objects API allows custom objects to be created, read, updated and deleted programmatically. Custom objects require HubSpot Enterprise. **How can I test the HubSpot API without affecting real data?** HubSpot offers sandbox accounts (available in Enterprise) and free developer accounts to test integrations without affecting real data. --- ## Conclusion The HubSpot API is a powerful tool for integrating external systems, automating processes and creating applications to publish on the HubSpot Marketplace. With more than 100 well-documented endpoints and an official SDK for Node.js, developing integrations with HubSpot is more accessible than ever in 2026. At Emovere we specialise in developing integrations with the HubSpot API. If you need to integrate HubSpot with your systems, contact our team. --- ## References [1] HubSpot — API Documentation. https://developers.hubspot.com/docs/api/overview [2] HubSpot — Node.js SDK. https://github.com/HubSpot/hubspot-api-nodejs [3] HubSpot — Webhooks Documentation. https://developers.hubspot.com/docs/api/webhooks [4] HubSpot — OAuth 2.0 Documentation. https://developers.hubspot.com/docs/api/oauth-quickstart-guide [5] HubSpot — API Rate Limits. https://developers.hubspot.com/docs/api/usage-details