HubSpot CRM: Data Model, Sync & API Integration

HubSpot

HubSpot is a CRM platform with marketing, sales, service, content, and operations tools built on one shared database of contacts, companies, deals, and tickets. Marketing teams use it for forms, email, and automation; sales teams for pipelines and sequences; support teams for tickets. Engineering teams usually meet it through integrations: syncing product users and accounts into the CRM, sending product events and subscription data, receiving updates through webhooks, and honoring privacy requests.

Integrations go wrong in predictable ways — duplicate contacts, fields overwritten by whichever system wrote last, rate-limit errors during bulk syncs, over-privileged tokens, and deletion requests that remove data from one system but not the other. Designing the data model and sync rules first prevents most of them.

TL;DR

Core objects: contacts, companies, deals, and tickets, plus custom objects on higher tiers; records connect through associations.
Data lives in properties; deals and tickets move through pipelines and stages.
Decide the system of record per property and use stable unique identifiers (email, domain, or a custom unique ID).
Sync with batch upserts and incremental changes; receive changes with webhooks.
Authenticate with static app tokens for your own account or OAuth for multi-account apps, with minimal scopes; handle rate limits with backoff.
Keep consent and subscription status accurate and use GDPR deletion endpoints for erasure requests.

Quick Example

Upserting product users as contacts by email in a batch, with a private app token and rate-limit handling:

Erasing a contact permanently when a privacy deletion request arrives:

app_user_id and plan are custom properties you define in HubSpot before syncing.

Core Concepts

Objects, Properties, and Associations

Every object has properties — default ones and custom ones you create with defined types and options. Associations link records (a contact to a company, a deal to contacts), optionally with labels such as "billing contact". Pipelines define stages for deals and tickets, and lifecycle stages track a contact's progression from subscriber to customer.

System of Record and Identifiers

Before syncing, decide which system owns each property: the product database usually owns plan, usage, and account status; HubSpot owns marketing and sales fields such as lead status. Sync product-owned properties into HubSpot and do not overwrite them from HubSpot, and vice versa. Use stable identifiers: email for contacts (with care, since emails change), domain for companies, and a custom unique-value property (such as app_user_id) for reliable upserts and lookups.

Integration Patterns

Make syncs idempotent — repeated runs must not create duplicates — and log every write with the source system for debugging. See Webhooks and Enterprise Integration.

Authentication and Rate Limits

Legacy API keys are retired. For an integration with your own account, use an app with a scoped static access token — a private app (now listed as a legacy app) or a project-based app with static auth on HubSpot's newer developer platform. For integrations installed in many accounts, use an app with OAuth. Grant only the scopes needed, store tokens in a secrets manager, and rotate them; HubSpot recommends rotating static tokens about every six months. Webhook subscriptions are configured per app, in the app's settings for private apps. API usage is limited both in short bursts and per day depending on subscription; batch endpoints, incremental syncs, and exponential backoff on 429 responses keep integrations within limits.

Workflows and Automation

Workflows automate actions on records — assign owners, send emails, update properties, create tasks, call webhooks — based on enrollment criteria. Coordinate them with integrations: a workflow that overwrites a property your sync also writes will cause flapping values. See Marketing Automation.

Privacy and Compliance

Consent and subscriptions: record legal basis and communication subscription types; never email contacts who have unsubscribed. See Consent Management and Email Marketing.
Erasure: archiving a record is reversible for a period; GDPR delete removes it permanently. Delete in every connected system, not only HubSpot.
Minimize data: sync only properties the CRM needs; avoid sensitive personal data in free-text fields.
Access: use teams, permission sets, and field-level restrictions to limit who sees and edits what.

Best Practices

Design the Data Model First

Agree on objects, properties, associations, and ownership with sales, marketing, and engineering before building the integration.

Use Unique Identifiers Everywhere

Upsert by a unique property and store HubSpot record IDs in your database so updates target the right records.

Batch and Throttle

Use batch endpoints, queue writes, and back off on rate limits; avoid one API call per user action at scale.

Monitor Sync Health

Track sync lag, error rates, duplicate rates, and records that fail validation, with alerts for sustained failures.

Common Mistakes

Two Systems Writing the Same Field

Creating Instead of Upserting

Over-Scoped Tokens

FAQ

What is HubSpot used for?

Customer relationship management plus marketing, sales, service, and content tools on a shared CRM database of contacts, companies, deals, and tickets.

How do I sync product users into HubSpot?

Define the properties to sync and which system owns each, then upsert contacts and companies in batches by unique identifiers on a schedule or from change events, storing HubSpot IDs in your database.

What is the difference between a private app and a public app?

A private app provides a static access token for one HubSpot account, for your own integrations; on HubSpot's newer developer platform the equivalent is an app with static auth and private distribution. A public app uses OAuth so it can be installed in many HubSpot accounts, typically for products and marketplace integrations. Both legacy app types remain supported.

How do I handle HubSpot API rate limits?

Use batch endpoints, sync only changed records, queue requests, and retry with exponential backoff when you receive 429 responses.

How do I permanently delete a contact?

Use the GDPR delete endpoint for contacts, which permanently removes the record, and delete the person's data from every other connected system as well.