HubSpot’s API gives developers programmatic access to all CRM data – contacts, companies, deals, tickets, custom objects, and associations between them. It’s a REST API with OAuth 2.0 authentication, predictable JSON responses, and comprehensive documentation. This guide covers how the API is structured, authentication options, rate limits, and the common use cases that drive most HubSpot API implementations.
That makes the API more of an infrastructure tool than a standalone feature.
HubSpot API access is useful when a business needs to connect HubSpot to other systems or build custom workflows around it. Authentication, rate limits, and the common use cases all matter because the API only helps if the integration is reliable and manageable.
API Architecture Overview
HubSpot’s API is organised around its CRM objects:
- CRM Objects API: CRUD operations on contacts, companies, deals, tickets, products, line items, and custom objects. The most commonly used endpoints.
- Associations API: Create and manage relationships between objects (associate a contact with a company, link a deal to contacts and a company).
- Properties API: Read and manage object properties – list all properties, create custom properties, update property definitions.
- Engagements/Activities API: Log notes, calls, meetings, and emails to object records programmatically.
- Marketing APIs: Email campaigns, forms, landing pages, and marketing events.
- Webhooks API: Subscribe to real-time events – receive an HTTP POST to your endpoint when a contact property changes, a deal stage changes, or a new contact is created.
Authentication: Private Apps vs OAuth
HubSpot has two authentication methods:
Private Apps (recommended for internal tools): Generate a private app access token in HubSpot settings. Include the token in API requests as a bearer token header: Authorization: Bearer YOUR_ACCESS_TOKEN. Tokens have configurable scopes (define exactly which API endpoints the app can access). Private apps are simpler to set up and appropriate when you control both the HubSpot portal and the application consuming the API.
OAuth 2.0 (required for public apps/marketplace apps): Use when building an application that other HubSpot customers will install. The standard OAuth flow: redirect the user to HubSpot’s authorization URL, receive an auth code, exchange it for access and refresh tokens. Access tokens expire every 6 hours; use the refresh token to get new access tokens without requiring re-authorization.
HubSpot deprecated API Keys (hapi_key) in 2022. If you’re still using an API key, migrate to private apps – API key endpoints are no longer supported.
Rate Limits
HubSpot enforces API rate limits per portal:
- Free/Starter: 100 requests per 10 seconds (burst), 250,000 requests per day.
- Professional/Enterprise: 150 requests per 10 seconds (burst), no daily limit.
When you exceed the rate limit, the API returns HTTP 429 with a Retry-After header. Implement exponential backoff in your API client: on receiving a 429, wait the Retry-After period plus a small random jitter before retrying. For high-volume operations (syncing thousands of records), use batch API endpoints – HubSpot’s batch endpoints accept up to 100 records per request, which dramatically reduces request count.
The best API setup is the one that balances usefulness with maintainability. If requests are poorly planned, rate limits and auth problems become the bottleneck.
Common API Use Cases
Syncing contact data from an external system
Use the Contacts batch upsert endpoint: POST /crm/v3/objects/contacts/batch/upsert. Send up to 100 contact records per request with email as the deduplication key. HubSpot will create new contacts or update existing ones based on email match. This is the most efficient pattern for bulk contact synchronisation.
Creating deals when a customer converts
When a customer purchases from your e-commerce platform or signs a contract, create a deal in HubSpot via the API: POST /crm/v3/objects/deals. Include deal amount, close date, and stage. Then associate the deal with the relevant contact and company using the Associations API: PUT /crm/v4/objects/deals/{dealId}/associations/default/contacts/{contactId}.
Logging custom activity to contact records
Log notes or custom activities: POST /crm/v3/objects/notes with the note body and an association to the target contact. This creates an activity log entry on the contact’s timeline – useful for logging events from external systems (support ticket opened, payment received, contract signed).
Listening to real-time events via webhooks
Set up webhook subscriptions: Settings ? Integrations ? Private Apps ? [Your App] ? Webhooks. Subscribe to specific events: contact.propertyChange (for a specific property), deal.stageChange, contact.creation. HubSpot sends an HTTP POST to your registered endpoint within seconds of the event. Use webhooks to trigger downstream actions in other systems – no polling required.
Batch APIs: Reducing Request Volume
For bulk operations, always use batch endpoints instead of individual object endpoints:
POST /crm/v3/objects/contacts/batch/create– create up to 100 contacts in one requestPOST /crm/v3/objects/contacts/batch/update– update up to 100 contactsPOST /crm/v3/objects/contacts/batch/upsert– create or update based on deduplication keyPOST /crm/v3/objects/contacts/batch/read– retrieve up to 100 contacts by ID in one request
API Best Practices
- Use the narrowest scope possible when creating private app tokens – don’t request write access to everything if your app only reads data.
- Implement retry logic with exponential backoff for all API calls – transient failures and rate limit responses are normal.
- Cache frequently read but rarely changed data (property definitions, pipeline stages) locally – avoid fetching these on every request.
- Use the
propertiesquery parameter to fetch only the properties you need – reduces response payload size and processing time. - Test with the HubSpot sandbox portal before running API operations against your production portal.
Getting your team to consistently use HubSpot
Adoption gaps occur when teams revert to old habits after initial training. Fix: Identify the 2-3 daily workflows where HubSpot adds the most value for your specific role. Focus training on those workflows first. Use HubSpot in-app guidance to provide contextual help at the moment of need rather than relying solely on one-time classroom training.
CRM data quality degrading over time
CRM data decays at approximately 30% per year as contacts change roles and companies. Fix: Schedule a quarterly data quality audit. Use HubSpot deduplication tools to merge duplicate records. Establish data entry standards enforced through validation rules. Consider a data enrichment tool like Clearbit or ZoomInfo to update stale records automatically.
HubSpot reports not matching actual business results
Reports are only as accurate as the data entered. Discrepancies between CRM reports and actual revenue indicate data entry gaps. Fix: Audit closed-won records against actual invoices monthly. Make CRM data the source of truth for commission calculations so reps have a direct incentive to enter accurate data.
Is HubSpot easy to learn for beginners?
HubSpot has a learning curve, but its official free training platform HubSpot Academy provides structured paths from beginner to advanced. Most users handle day-to-day tasks within 2-4 weeks. Admin and developer skills take 3-6 months to develop proficiently.
What are the biggest HubSpot mistakes to avoid?
Top mistakes include: over-customizing before understanding your process, skipping user training, importing dirty data without cleansing, and not establishing naming conventions. Avoid these four and your implementation will be significantly more successful.
How often does HubSpot release new features?
HubSpot releases major updates quarterly and ships smaller updates continuously to all tiers.
Does HubSpot offer customer support?
Yes. Support is available via chat, email, and phone depending on your plan tier. Enterprise plans include dedicated customer success managers. HubSpot Academy and the HubSpot Community are also excellent free support resources.
Can HubSpot integrate with other business tools?
Yes. HubSpot App Marketplace has 1,500+ integrations including Gmail, Slack, Zoom, Shopify, and WordPress.