HubSpot API Guide: What Developers Need to Know

Building on HubSpot: API Fundamentals

HubSpot’s API enables custom integrations, data synchronization, and application development that extend the platform beyond its native capabilities. Whether you are syncing data with an ERP, building a custom reporting dashboard, or creating an internal tool that reads CRM data, the API is your interface. This guide covers what developers need to know to work effectively with HubSpot’s API.

Authentication Options

For most internal integrations, private app access tokens are sufficient and simpler to implement. OAuth is required for apps that will be installed by multiple HubSpot accounts.

Key API Endpoints

CRM Objects API: Create, read, update, and delete contacts, companies, deals, tickets, and custom objects. Supports batch operations for high-volume data processing (up to 100 records per batch request).

Associations API: Manage relationships between objects. Associate contacts with companies, deals with contacts, or any object-to-object relationship. Supports association labels for typed relationships.

Search API: Query CRM objects with filters, sorting, and pagination. More efficient than listing all objects when you need specific records matching criteria.

Workflows API: Trigger workflows via API, useful for event-driven automation from external systems.

Webhooks: Subscribe to CRM events (contact created, deal stage changed, etc.) and receive real-time notifications at your endpoint. Essential for keeping external systems synchronized.

Rate Limits and Best Practices

Rate limits: 100 requests per 10 seconds for private apps, 200 requests per 10 seconds for OAuth apps. Burst limits and daily limits also apply. Use batch endpoints to reduce request count.

Pagination: List endpoints return paginated results (default 10, max 100 per page). Always implement pagination handling – do not assume all results are returned in a single request.

Error handling: Implement exponential backoff for rate limit errors (429). Handle 500 errors with retries. Log all API errors for debugging.

Data sync pattern: For ongoing sync, use webhooks for real-time updates and periodic full sync (daily) as a safety net. This combination ensures data consistency without excessive API calls.

Example Integration Architectures

Conclusion

HubSpot’s API is well-documented, RESTful, and capable of supporting complex integrations. Start with private app tokens for internal projects, use batch endpoints to stay within rate limits, implement webhooks for real-time sync, and always handle pagination and errors properly. For most business integration needs, the API provides everything required to connect HubSpot with your broader tech stack.

Need custom HubSpot integration development? Talk to Widelly about API integration, custom development, and tech stack architecture.

HubSpot API Fundamentals: What Developers Need to Know

HubSpot’s REST API provides programmatic access to all CRM objects, marketing tools, and automation functions. The API uses OAuth 2.0 for authentication (recommended for apps accessed by multiple HubSpot portals) and Private App tokens for server-to-server integrations within a single portal. All API endpoints return JSON. Rate limits: the standard rate limit is 100 requests per 10 seconds for most endpoints. Batch endpoints allow updating or creating multiple records in a single request (up to 100 records per batch call), which is essential for high-volume data sync operations. The HubSpot API documentation at developers.hubspot.com is comprehensive, with interactive endpoint testing tools that allow developers to test API calls directly in the browser against a sandbox account.

Key HubSpot API Endpoints for CRM Integration

The most commonly used HubSpot API endpoints for CRM integration: Contacts API (create, read, update, and delete contact records and properties), Companies API (same for company records), Deals API (manage deal records, pipeline stage changes, and deal associations), Engagements API (log calls, emails, meetings, and notes programmatically to contact timelines), Associations API (create and manage associations between any two HubSpot objects), Properties API (create and manage custom properties programmatically), and Workflows API (enrol contacts in workflows programmatically – useful for triggering HubSpot automation from external events). The Timeline Events API is valuable for logging custom events from external applications to the HubSpot contact timeline, creating a unified activity history that includes non-HubSpot interactions.

Frequently Asked Questions

HubSpot API for Sales Tools: The Most Common Integration Patterns

Sales technology integrations with HubSpot follow five common patterns. Pattern 1 – Conversation intelligence sync: Gong or Chorus records a sales call, generates a summary, and writes the call recording URL and summary to the HubSpot contact timeline via the Engagements API. Pattern 2 – Meeting intelligence: video conferencing tools (Zoom, Microsoft Teams, Google Meet) write meeting participant lists and attendee status to HubSpot contact records via the Timeline Events API. Pattern 3 – Document tracking: document tools (PandaDoc, DocuSign) write document open events and signature status to HubSpot deal records via the Deals API or Webhooks. Pattern 4 – E-signature completion trigger: when a contract is signed in DocuSign, a webhook to HubSpot triggers a workflow that moves the deal to “Closed Won” automatically. Pattern 5 – Calendar intelligence: scheduling tools beyond HubSpot Meetings (Calendly, Chili Piper) write meeting booking data to HubSpot contact records and can trigger workflows based on meeting type or outcome.

HubSpot API Authentication: Private Apps vs OAuth

HubSpot Private Apps are the recommended authentication method for single-portal server-to-server integrations. A Private App generates a static token that provides access to specific HubSpot scopes defined at creation. Private App tokens do not expire by default (unlike the legacy API keys they replaced), but should be rotated annually as a security best practice. OAuth 2.0 is required for apps that need to connect to multiple HubSpot portals (a SaaS application that integrates with HubSpot and is sold to multiple customers, each with their own HubSpot portal). OAuth provides per-portal authorisation – each customer grants your application access to their specific portal through HubSpot’s OAuth consent flow. The application stores a refresh token per portal and exchanges it for access tokens automatically. If you are building a single integration for your own company’s HubSpot portal, use a Private App. If you are building an integration to sell to multiple HubSpot customers, use OAuth.

HubSpot API: The 10 Endpoints Every Integration Developer Should Know

• POST /crm/v3/objects/contacts – Create a new contact
• PATCH /crm/v3/objects/contacts/{contactId} – Update an existing contact’s properties
• POST /crm/v3/objects/contacts/batch/upsert – Bulk create or update contacts by email (most efficient for batch syncs)
• GET /crm/v3/objects/deals/search – Search deals by property filters with pagination
• POST /crm/v3/objects/engagements – Create an engagement (call, email, meeting note) on a contact timeline
• PUT /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} – Associate two objects
• GET /crm/v3/properties/{objectType} – List all properties for an object type (useful for discovery)
• POST /automation/v4/actions – Create a custom coded workflow action trigger
• POST /events/v3/send – Send a custom timeline event to a contact timeline
• GET /oauth/v1/access-tokens/{token} – Validate an OAuth token and retrieve portal information

HubSpot Webhooks: The Fastest Way to Connect External Systems

HubSpot webhooks send real-time HTTP notifications to external systems when specific events occur in HubSpot – without requiring polling, manual exports, or scheduled sync jobs. Common webhook use cases: when a deal is marked Closed Won, send a webhook to the accounting system to create an invoice. When a contact submits a specific form, send a webhook to a Slack channel with the contact details. When a contact’s lifecycle stage changes to Customer, send a webhook to the provisioning system to create their account. Configuring a webhook in HubSpot: go to Settings > Integrations > Private Apps, create a Private App with the appropriate scopes, and add a webhook subscription specifying the object type and event type that should trigger the notification. HubSpot webhooks deliver events in near real-time with a maximum delay of a few seconds under normal conditions.

HubSpot Webhook Best Practices for Reliable Integrations

• Configure a receiving endpoint that returns HTTP 200 within 5 seconds – slow endpoints cause HubSpot to retry delivery.
• Build idempotent handlers: the same webhook may be delivered more than once in edge cases – your handler should produce the same result whether it processes the event once or three times.
• Implement a dead letter queue for failed deliveries: any webhook that cannot be processed should be queued for retry rather than silently dropped.
• Log all received webhook payloads for debugging: webhook payloads are not stored by HubSpot and cannot be resent on demand.
• Test with HubSpot’s webhook testing tool (available in the Private App configuration) before activating in production.