Integrating Your CRM With The HubSpot API

Getting Started

When integrating your CRM-type system with HubSpot via our REST API, we recommend that you start by identifying the data you’d like to pass between the two systems. Typically we recommend that information for segmentation, personalization or reporting purposes is synced to HubSpot. There are several objects where data can be stored against within HubSpot:

  • Contacts (Contact / Lead type objects)
  • Companies (Account type objects)
  • Deals (Opportunity type objects)
  • Tickets (Support Ticket type objects)
  • Engagements (Task and Activity type objects)
  • Products (Library of SKUs type objects)
  • Line Items (Specific product variation associated with a purchase or sales process type objects)
  • Timeline Events (Custom defined type objects that can "happen" to their associated Object)

Once data to be synchronized has been identified, you can then begin to map out the different object relationships between HubSpot and your system, and map the relevant data fields to be synchronized between the two systems. You'll need to create any custom properties on the available objects above as needed, selecting the most appropriate data type.

The next step in the process is to plan out the development of your integration utilizing the information contained within this document, developing the required use cases, and then beginning implementation. 

Of important note is that while there exists an internal unique identifier of any given contact record, it’s not possible to create two contact records with the same email address. Email address across contact records must always be unique, however they do not always need to be present.

Object Relationships

The ERD below describes the object relationships to one another:



The API allows for two means of authentication, OAuth and via API keys:

  • OAuth is the recommended authentication method.  During the OAuth process you can request access to the specific scopes you need. To access everything in the diagram above you would need contacts, tickets and timeline.  To get started with OAuth, check out this quick start guide
  • For an integration that only you / your company will use, you may wish to use your HubSpot API key. To get your HubSpot API key, please follow the instructions outlined here. Please note that this method of authentication is considered less secure than implementing Oauth.

Managing Metadata of HubSpot Objects

HubSpot provides a default set of properties for the Contacts, Deals, Companies Products, Line Items, and Tickets Objects which can be be appended with your own custom properties.  Timeline Events are entirely customizable except for a default "occurred" property.  Engagements are limited to the HubSpot defined metadata. See the links below on how to change the metadata of CRM objects were applicable.


CRM data is at it's most useful when we can represent the relationships between various objects.  For example the fact that we can sync Opportunities from a CRM into a Deal is nice, but it's really only useful when we know what Company and/or Contacts are involved with that Deal. This opens up all kinds of possibilities within HubSpot ranging from being able target a list of Contacts who have been associated with Closed Lost Deals for win back campaigns to reporting how the acquisition source of a lead affects how many Tickets and of what type they submit as a customer.  For all objects except for the Timeline API you can use the CRM Associations API. For the Timeline API, the association is defined as the Timeline Event is sent in as described here in the identity parameters section


While when looking at the ERD above, one might assume that they are critical to a CRM integration, however in most cases they aren't necessary to sync. Engagements represent the 1:1 interactions someone would have with a prospect/customer, such as sales calls or emails, or notes left on the contact record and don't have many uses in automation or reporting. Generally it's easier to sync properties like date last contacted or number of calls/emails rather than the underlying Engagement. In addition, it's important to keep API Limits in mind when choosing whether to sync Engagements or not, and since there generally a lot of them, it can be an easy object to exclude. There are two exceptions to this, first in the case where a business development team or similar is working out of HubSpot CRM then handing the Deals off to an inside sales rep working out of another CRM you will want to have that activity synced so the sales teams can be on the same page. This extends to other scenarios where different users are working out of different systems, however for the purpose of this document, we'll stick to CRM use cases.  The other general exception is in the case where the CRM integration is a precursor to a migration, in this case we'll want to sync Engagements across the systems to ensure people have full context regardless of what CRM they are in during a transition period.