HubSpot’s API gives developers and technical teams programmatic access to all CRM data – contacts, companies, deals, tickets, products, custom objects, and more – enabling custom integrations, data migrations, automated workflows beyond what the visual Workflow builder supports, and synchronisation with internal systems. You don’t need to be a senior developer to get started: the HubSpot API is well-documented, uses standard REST conventions, and the most common use cases (reading and writing contact data) require only basic HTTP request knowledge. This guide covers the fundamentals for non-developers and developers new to HubSpot.
That makes the API an important option for teams that need custom integrations rather than off-the-shelf connections.
HubSpot API access is useful when a business wants to build CRM integrations that go beyond what the built-in tools provide. It gives developers a way to connect HubSpot to other systems and move data in a controlled way.
What the HubSpot API Can Do
The HubSpot API allows you to:
- Create, read, update, and delete (CRUD) records across all CRM objects: contacts, companies, deals, tickets, custom objects.
- Enroll contacts in Workflows, add contacts to lists, and trigger automation programmatically.
- Read and write contact, company, and deal properties.
- Log activities (calls, emails, meetings, notes) on contact and deal records.
- Access marketing data: email campaign metrics, form submissions, landing page views.
- Manage associations between objects (associate a contact with a company, a contact with a deal).
- Use webhooks to receive real-time notifications when specific events happen in HubSpot (contact property changes, deal stage changes, form submissions).
Authentication: API Keys vs Private Apps
HubSpot deprecated API key (hapikey) authentication in 2022. The current authentication method for all new integrations is Private Apps – HubSpot’s OAuth-based token system for single-account API access. To create a private app:
- Go to Settings ? Integrations ? Private Apps ? Create a private app.
- Give the app a name and description.
- Select the scopes (permissions) the app needs – only grant the minimum scopes required for your use case (e.g., crm.objects.contacts.read for reading contacts, crm.objects.contacts.write for creating/updating).
- Click Create app to generate the access token.
- Use the access token in your API requests as a Bearer token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN.
Making Your First API Call: Create a Contact
A basic example using Python’s requests library to create a HubSpot contact via the API:
import requests
access_token = "your_private_app_token"
url = "https://api.hubapi.com/crm/v3/objects/contacts"
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
payload = {
"properties": {
"email": "example@company.com",
"firstname": "Jane",
"lastname": "Smith",
"company": "Acme Corp",
"lifecyclestage": "lead"
}
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.json())
A 201 response indicates the contact was created successfully. The response body includes the new contact’s HubSpot ID.
Reading Contacts: Search API
The HubSpot CRM Search API allows you to query contacts (and other objects) by property values – more flexible than fetching by ID alone. POST to https://api.hubapi.com/crm/v3/objects/contacts/search with a filter group defining your query criteria. For example, retrieve all contacts where lifecycle stage is “lead” and original source is “Organic Search.” The search API supports pagination (limit and after parameters) for large result sets.
Rate Limits
HubSpot API rate limits: the standard limit is 100 API calls per 10 seconds per access token. For bulk operations, HubSpot provides batch endpoints (create up to 100 contacts in a single API call) that are far more efficient than 100 individual calls. Use batch endpoints for data migrations and large imports. Exceeding rate limits returns a 429 (Too Many Requests) response – implement exponential backoff in your code to handle rate limit responses gracefully.
Webhooks: Real-Time Event Notifications
Instead of polling the API repeatedly to check for changes, use HubSpot’s webhooks to receive real-time HTTP POST notifications when specific events occur – contact property changed, deal created, form submitted, contact added to list. Configure webhooks under Settings ? Integrations ? Private Apps ? select app ? Webhooks tab. Point the webhook to an endpoint in your application, and HubSpot will POST event data to that URL whenever the subscribed event fires. Webhooks are available for contact, company, deal, ticket, and custom object events.
Sources
HubSpot, CRM API Documentation (2026)
HubSpot, Private Apps and Authentication (2026)
HubSpot, CRM Search API Reference (2025)
HubSpot, API Rate Limits (2025)
HubSpot, Webhooks Documentation (2025)
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. HubSpot also 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 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.
The best API setup is the one that solves a clear business problem. If the integration is too complex to maintain, the benefit disappears quickly.
Common Challenges with HubSpot API and How to Solve Them
Problem: 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.
Problem: 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.
Problem: 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.