When integrating your CRM with HubSpot via our API, you should start by identifying the data you’d like to pass between the two systems—we recommend syncing any information used for segmentation, personalization, or reporting purposes. There are several objects where data can be stored within HubSpot:
Once you've identified the data you want to sync, you can begin to map object relationships between HubSpot and your system and identify which data fields need to sync. You should also create any custom properties needed for the objects above.
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.
Note: 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.
The ERD below describes the object relationships to one another:
HubSpot provides a default set of properties for contacts, deals, companies, products, line items, and tickets, 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.
CRM data is at its most useful when we can represent the relationships between various objects. For example, the fact that we can sync opportunities from an external CRM into a HubSpot 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 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, but 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 are 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.