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, personalisation or reporting purposes is synced to HubSpot. There are three object types of which data can be stored against within HubSpot:

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 three available objects above as needed, selecting the most appropriate data type from the list below.

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. We highly recommend the use of an agile or test driven development methodology such as Scrum.

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.

Object Relationships

The three HubSpot objects have varying relationships to each other. These relationships are as follows:

  • Contacts
    • A contact can be associated with a single company object.
    • A contact can be associated with multiple deal objects.
  • Companies
    • A company can be associated with multiple contacts.
    • A company can be associated with multiple deals.
  • Deals
    • A deal can be associated with multiple contact objects and multiple company objects.



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

  • API keys are great for rapid prototyping, but for security and commercial use, all integrations should ideally use OAuth. HubSpot currently offers three editions of our marketing product: Basic, Professional, and Enterprise. API access utilising an API key is limited to Professional and Enterprise users only.
  • 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.

What Data Types Does HubSpot Support?

HubSpot includes provision for up to 1000 custom property fields across the three object types, in addition to preconfigured standard property fields (First Name, Last Name, Email Address, and so on). Contact properties and Company properties can be organized into logical groups either programmatically through the API or through the HubSpot interface. To create new properties programmatically, there are three different endpoints, depending on which object you’d like to create the property for:

Standard data types and their expected ‘type’ and ‘fieldType’ values when creating properties programmatically are listed below. These represent the data type within the backend database and also dictate how a field is represented within a form:

  • Single Line Text - Single line text properties can contain a string of any alphanumeric characters, such as a word, a phrase, or a sentence.
    • "type": "string"
    • "fieldType": "text"
  • Multi-Line Text – Multi-Line text properties can contain several strings of alphanumeric characters, such as a paragraph or list of items.
    • "type": "string"
    • "fieldType": "textarea"
  • Drop-down select – Drop-down selects contain several specific options and the visitor is limited to selecting only one of the options.
    • "type": "enumeration"
    • "fieldType": "select"
  • Radio Select (Select a single option) – Radio selects act the same way as drop-down selects, but appear differently in forms. They also contain several concrete options and the visitor can select only one of the options.
    • "type": "enumeration"
    • "fieldType": "radio"
  • Checkboxes (Select multiple options) – Checkboxes contain several specific options that are usually related. You might be used to seeing these fields with the help text "Check all that apply."
    • "type": "enumeration"
    • "fieldType": "checkbox"
  • Single On/Off Checkbox – Single On/Off Checkboxes only have two options on or off. They are typically used if you are integrated with Salesforce and need a field that is either checked or unchecked.
    • "type": "enumeration"
    • "fieldType": "booleancheckbox"
  • Number Field – Number fields can contain any string of numerals or numbers written in decimal or scientific notation.
    • "type": "number"
    • "fieldType": "number"
  • File Upload - File upload fields are used to allow visitors to upload files and provide you with a link through a form submission. The uploaded file's link is available from the individual's contact record.
    • "type": "string"
    • "fieldType": "file"
  • Date Picker – Date picker fields are used to allow visitors to input a specific date in a standard format that can be segmented on.
    • "type": "date"
    • "fieldType": "date”

Docs for this section or API