Getting started

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:

• Contacts: Contacts store information about an individual person. From marketing automation to smart site content, the lead-specific data found in contact records helps users leverage much of HubSpot's functionality. View Contacts API Overview
• Companies: Company records store information about an individual business or organization. Multiple contacts can be associated with a company to represent its organizational makeup. View Companies API Overview
• Deals: Deals represent revenue opportunities with a contact or company. They’re tracked through pipeline stages, eventually resulting in the deal being won or lost. View Deals API Overview
• Tickets: Tickets represent customer requests for help or support. View Tickets API Overview
• Products: Products represent goods or services you sell. Building a product library allows you to quickly add products to deals, generate quotes, and report on product performance. View Products API Overview
• Line items: Line items can be thought of as a subset of products. When a product is attached to a deal, it becomes a line item. You can create line items that are unique to an individual quote, but they will not be added to your product library. View Line Items API Overview
• Quotes: Quotes are used to share pricing information with potential buyers. 
• Engagements: Engagements store task and activity-type information.
• Timeline Events: Timeline events are custom-defined type objects that can "happen" to their associated object.

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.

Object relationships

The ERD below describes the object relationships to one another:

Authentication

The API allows for two means of authentication, OAuth and via private app access tokens:

• 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 a private app access token. 

Managing object properties

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.

• Create a new contact property
• Create a new company property
• Create a new deal property
• Create a new ticket, product, or line item property
• Define timeline event types

Associations 

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.

Engagements 

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.