Overview
HubSpot is one of the most widely deployed CRM and marketing automation platforms, used by businesses across sales, marketing, customer service, and operations to manage contacts, deals, companies, tickets, and the automated workflows that connect these objects across the customer lifecycle. For organisations that run HubSpot as their CRM and marketing platform, integration between HubSpot and the other systems the organisation uses is a common and often critical requirement — data that lives in HubSpot needs to flow to operational systems, and data generated by operational systems needs to flow back into HubSpot to keep it as the accurate record of customer activity.
The HubSpot API provides comprehensive programmatic access to HubSpot's data model and automation capabilities. The CRM API covers contacts, companies, deals, tickets, and custom objects — the core CRM records and their associations. The Marketing API covers email campaigns, forms, landing pages, and marketing analytics. The Sales API covers deals, pipelines, and sales activity. The CMS API covers website content managed through HubSpot's CMS. And the Automation API covers workflows that can be triggered programmatically.
For custom software that needs to interact with HubSpot, the most common integration scenarios involve reading CRM data for customer-facing applications, writing lead and customer data from custom forms and applications into HubSpot, synchronising contact and deal data between HubSpot and other systems (ERP, e-commerce platform, support system), and using HubSpot's automation capabilities triggered by events from external systems.
We build HubSpot integrations for sales-driven businesses, marketing agencies, e-commerce operations, and SaaS companies that need to connect their custom software and operational systems to HubSpot's CRM and marketing automation platform.
What HubSpot Integration Covers
Authentication and API access. HubSpot's API supports two primary authentication mechanisms — private app tokens for internal integrations and OAuth 2.0 for applications that access multiple HubSpot portals.
Private app tokens: the simplest authentication mechanism for integrations that access a single HubSpot portal. A private app is created in HubSpot's developer settings, and a token is issued that grants access to the specific scopes selected during creation. The Authorization: Bearer {token} header for all authenticated API requests. Private app tokens do not expire but can be rotated in HubSpot's settings.
OAuth 2.0 for multi-portal apps: the OAuth flow for applications that need to access multiple HubSpot portals — the typical approach for HubSpot marketplace apps or agency tools that manage multiple client portals. The authorisation URL with the client ID, redirect URI, and requested scopes. The authorisation code flow where the HubSpot account user grants the application access to their portal, the code exchange for access and refresh tokens, and the refresh token logic that obtains new access tokens before expiry (access tokens expire after 30 minutes).
Scope configuration: HubSpot API scopes that control what data the integration can access — crm.objects.contacts.read and crm.objects.contacts.write for contact access, crm.objects.deals.read and crm.objects.deals.write for deal access, crm.schemas.custom.read and crm.schemas.custom.write for custom object schemas. Scopes are requested during private app creation or in the OAuth flow and cannot be changed without creating new credentials.
CRM API — contacts. The most commonly integrated HubSpot object — the contact record that represents a person in HubSpot's CRM.
Contact creation: the POST /crm/v3/objects/contacts endpoint for creating new contacts. The contact properties object with the standard HubSpot contact properties — firstname, lastname, email, phone, company, jobtitle, website, address, city, state, zip, country — and any custom contact properties configured in the HubSpot portal. The email address as the primary deduplication identifier — HubSpot automatically deduplicates contacts by email address and will merge a new contact with an existing contact with the same email.
Contact retrieval: the GET /crm/v3/objects/contacts/{contactId} endpoint for fetching a specific contact by ID. The properties query parameter that specifies which contact properties to return — requesting only the needed properties reduces response size. The associations parameter for including associated objects (companies, deals) in the response.
Contact search: the POST /crm/v3/objects/contacts/search endpoint for searching contacts with filter criteria. The search request with filterGroups (OR-combined groups of AND-combined filters), sorts (sort by property), properties (which properties to return), limit (page size), and after (pagination cursor). Filter operators: EQ (equals), NEQ (not equal), CONTAINS_TOKEN (contains), GT (greater than), LT (less than), BETWEEN, IN (one of a list), HAS_PROPERTY, NOT_HAS_PROPERTY.
Contact update: the PATCH /crm/v3/objects/contacts/{contactId} endpoint for updating specific contact properties without replacing the entire contact record. The PATCH semantics that update only the properties specified in the request.
Batch operations: the POST /crm/v3/objects/contacts/batch/create and POST /crm/v3/objects/contacts/batch/upsert endpoints for creating or updating multiple contacts in a single API call — reducing API call volume for bulk synchronisation operations. The batch upsert that creates new contacts and updates existing ones by email address, the standard approach for synchronising contact data from external systems. Batch limits: up to 100 objects per batch request.
CRM API — companies. Company records that represent organisations in HubSpot.
Company creation and update: the POST /crm/v3/objects/companies and PATCH /crm/v3/objects/companies/{companyId} endpoints for creating and updating company records. The standard company properties — name, domain, industry, numberofemployees, annualrevenue, city, country, phone. HubSpot deduplicates companies by domain name.
Company search: the POST /crm/v3/objects/companies/search endpoint for finding companies by name, domain, or custom properties.
CRM API — deals. The deal records that represent sales opportunities in HubSpot's pipeline.
Deal creation: the POST /crm/v3/objects/deals endpoint for creating deal records. The deal properties — dealname, amount, dealstage (the pipeline stage ID), pipeline (the pipeline ID), closedate, hubspot_owner_id (the HubSpot user responsible for the deal). The deal stage and pipeline IDs that must be retrieved from the HubSpot portal configuration before creating deals — the stage IDs that are portal-specific and cannot be hardcoded.
Deal pipeline stages: the GET /crm/v3/pipelines/deals endpoint for retrieving the configured deal pipelines and their stages. The pipeline ID and stage IDs used in deal creation and update.
Deal associations: associating deals with contacts and companies through the associations API — the POST /crm/v4/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} endpoint that links a deal to a contact or company.
CRM API — custom objects. HubSpot's custom objects for data that does not fit the standard contact, company, deal, or ticket models.
Schema retrieval: the GET /crm/v3/schemas endpoint for listing the custom object schemas configured in the portal — the custom object names, their properties, and their association definitions.
Custom object CRUD: the same /crm/v3/objects/{objectType} endpoint pattern used for standard objects applies to custom objects — create, read, update, batch operations, and search all follow the same API conventions with the custom object type name as the objectType parameter.
Associations API. The relationships between HubSpot CRM objects — the link between a contact and their company, between a deal and the contacts involved, between a ticket and the company it relates to.
Association creation: the POST /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} endpoint for creating associations. The association type IDs for standard relationships — contact-to-company (1), deal-to-contact (3), deal-to-company (5) — and the custom association types for non-standard relationships.
Batch association creation: the POST /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create endpoint for creating multiple associations simultaneously — the efficient approach for associating many contacts to a company or many contacts to a deal.
Properties API. Managing the HubSpot contact, company, deal, and custom object properties.
Property retrieval: the GET /crm/v3/properties/{objectType} endpoint for listing all properties of a specific object type — the property names, labels, types, and field types. The property discovery that integration code uses to verify that required custom properties exist in the target portal before attempting to write to them.
Custom property creation: the POST /crm/v3/properties/{objectType} endpoint for creating new custom properties programmatically — the integration setup step that creates the custom properties the integration needs before beginning data synchronisation.
Property groups: the property group structure that organises related properties in HubSpot's UI — the group creation endpoint for organising the integration's custom properties in a named group.
Marketing API — forms. HubSpot forms as the lead capture mechanism for websites that use HubSpot's native forms.
Form submission API: the POST https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formId} endpoint for submitting form data to HubSpot from custom forms — the API that creates or updates a contact in HubSpot from form submission data collected by a custom form rather than a HubSpot-native form. The submission payload with the fields array (name-value pairs for each form field) and the context object (page URI, page name, hutk cookie value for cookie-based contact identification).
Form retrieval: the GET /marketing/v3/forms/{formId} endpoint for reading form configuration — the form fields and their validation rules, used by custom form implementations that render HubSpot form fields in a custom UI.
Marketing API — email campaigns. HubSpot marketing email data for campaign performance reporting.
Email statistics: the GET /marketing/v3/emails/statistics/list endpoint for email campaign performance — sends, opens, clicks, bounces, and unsubscribes for each email campaign. The campaign performance data that reporting dashboards use for marketing analytics.
Contact subscription status: the GET /email/public/v1/subscriptions/{email} endpoint for checking and updating a contact's email subscription preferences — the GDPR-compliant subscription management that allows contacts to manage their communication preferences.
Webhooks — real-time event delivery. HubSpot webhooks for receiving real-time notifications when CRM objects are created, updated, or deleted.
Webhook subscription configuration: the HubSpot app webhook settings that configure which object events the integration should receive — contact.creation, contact.propertyChange, deal.stageChange, company.creation. The target URL that HubSpot sends webhook payloads to.
Webhook payload processing: the webhook event payload with the objectId (the HubSpot object ID), the objectType (contact, deal, company), the eventType (object creation, property change, deletion), the propertyName and propertyValue for property change events, and the portalId. The webhook receiver that processes incoming events, validates the signature, and triggers the appropriate integration action.
Signature validation: the X-HubSpot-Signature header that HubSpot includes in webhook requests — the HMAC-SHA256 hash of the client secret concatenated with the request body. The signature validation that verifies the webhook originated from HubSpot before processing.
Rate limiting on webhooks: HubSpot delivers webhooks with a maximum of 10,000 events per 10-second window. The webhook receiver that processes events idempotently — handling the case where the same event is delivered more than once.
HubSpot API rate limits. HubSpot enforces rate limits on API calls that must be managed to avoid disruption.
Standard rate limits: HubSpot's default rate limit is 110 requests per 10 seconds per portal. The X-HubSpot-RateLimit-Remaining and X-HubSpot-RateLimit-Interval-Milliseconds response headers that indicate the remaining request budget and the interval. The 429 response with the Retry-After header when the rate limit is exceeded.
Daily limits: HubSpot also enforces daily API call limits — 250,000 calls per day for standard portals, higher for Professional and Enterprise tiers. The daily limit tracking that prevents hitting the day's ceiling during large synchronisation operations.
Batch operations for rate efficiency: using HubSpot's batch endpoints to update 100 contacts in a single API call rather than 100 individual calls — the approach that reduces API call volume by two orders of magnitude for bulk synchronisation.
Integration Patterns
Lead capture synchronisation. The custom form or application that captures lead data writes it to HubSpot via the Forms Submissions API or the Contacts API — creating or updating the contact record in HubSpot with the submitted lead data, triggering HubSpot's native workflows for lead nurturing.
CRM to operational system synchronisation. The sales process in HubSpot generates deal records that downstream systems need to act on — the ERP system that creates a customer account when a deal reaches Closed Won, the project management system that creates a project when a deal is signed. The webhook that fires on deal stage change triggers the downstream system action.
Operational system to CRM synchronisation. Customer activity in operational systems that should be reflected in HubSpot — the e-commerce orders that create or update deal records in HubSpot, the support tickets that create HubSpot ticket objects, the product usage events that update custom contact properties with engagement data.
Bidirectional contact synchronisation. Keeping contact data consistent between HubSpot and another system when contacts can be created and updated in both. The synchronisation logic that merges updates from both systems, handles conflicts, and prevents synchronisation loops where a change in one system triggers an update in the other that triggers another update back.
Technologies Used
- C# / ASP.NET Core — HubSpot integration for .NET applications, using the HubSpot .NET client library where available and direct HTTP calls for endpoints not covered by the library
- TypeScript / Node.js — HubSpot integration for Node.js backends and serverless functions, using the
@hubspot/api-clientnpm package - Python — HubSpot integration for data pipelines and analytics workflows using the
hubspot-api-clientPython package - Rust / Axum — high-performance HubSpot data processing for integrations with high contact volumes
- OAuth 2.0 / Private App Tokens — HubSpot API authentication
- REST / HTTP — HubSpot API communication
- Webhooks — real-time HubSpot event delivery
- SQL (PostgreSQL / MySQL) — synchronisation state, contact mapping, delta tracking
- Redis — API rate limit management, token caching, synchronisation job coordination
- Hangfire / scheduled jobs — scheduled contact and deal synchronisation
- Docker — containerised integration service deployment
- GitHub Actions — CI/CD pipeline for integration service deployment
HubSpot as the CRM Source of Truth
For organisations where HubSpot is the system of record for customer and prospect data, integrations that keep HubSpot current with activity from operational systems — and that propagate HubSpot's customer data to the operational systems that need it — are the connective tissue of the organisation's customer data infrastructure. The sales team that works in HubSpot should see the complete customer picture, including data that was generated in operational systems they do not use directly. The operational systems that need to know whether a prospect has become a customer should read that status from HubSpot rather than maintaining their own duplicate record.
HubSpot Connected to Your Customer Operations
HubSpot integrations built to production standards — correct OAuth token management or private app token handling, batch operations for rate-efficient bulk synchronisation, webhook processing with signature validation for real-time event handling, and the monitoring that surfaces integration issues before they cause CRM data gaps.