Import HubSpot Deals, Contacts and Companies while maintaining their associations via the HubSpot API

By Ralph Vugts on May 11, 2018
Narrate this article

You're probably reading this article because you have made the wise choice to ditch whatever painful-to-use CRM and migrate your data over to HubSpot. Happy days are ahead for you once you get up and running!

Getting your data in to HubSpot is pretty easy. Out-of-the box HubSpot comes with an excellent and easy-to-use import tool to load your data. But unfortunately there is no way to easily link Contacts to Deals or Companies via this process. There are a few other 3rd party import tools out there as well that you can check out... But if you have a slightly more complex import you will need to use the HubSpot API to get the desired results.

By using the API you can tap into pretty much any object and check / dedupe data as you go. It also makes it much easier to associate objects together. Say you know a deal belongs to a certain contact / company etc.

Top reasons to use the HubSpot API for data import

  • Object association. You want to link Deals, Contacts & companies together based off some identifier in your existing data.
  • Custom data validation rules. When creating your import script you can define pretty much any rule you like on how to handle data. Eg. to check if a user already exists, look up and assign an owner, etc.
  • Converting data. Your existing data is probably in a completely different format. You can convert dates, dropdown values or manipulate data anyway you like before inserting it into HubSpot.
  • Other Objects. You need to import into other HubSpot objects like the Timeline API, HubDB etc.

Creating your own HubSpot Import Script

We would love to do this for you of course because, well, money... and we're kinda good at it! Get in touch if you need some help. BUT if you're feeling in a 'codey' mood and want to give it a go yourself keep reading...

Step 1: Getting setup

If you've already been using HubSpot and have some data in there, I would recommend using a demo or a testing account to run some test imports with, just in case you mess something up. Otherwise you can't go too wrong, if something doesn't import as expected just delete the offending data and start again.

First you will need to grab your API key so you can access HubSpot. Instructions here. If you want to get super fancy, you can look at using OAuth... but probably a bit overkill for a one-off import.

Next, you will need to decide which API library you want to use. This will greatly speed up your development process. If you prefer PHP I highly recommend this HubSpot PHP library.

Step 2: Write your HubSpot Import Script

Now the tricky bit begins. You will need to start coding the logic on how your import will process your data. I won't go into too much detail here as it will vary greatly based on what you want to achieve. But I have added some key concepts below on how to overcome a few issues.

Import progress!
If your data is in spreadsheets or something similar, I highly recommend setting local database to keep track of what has already been processed. This means if you hit an error or issue you can resolve it and then simply resume where you left off. I would also recommend storing the internal HubSpot ID's (Contact ID, Deal ID, Company ID etc) in your local database. This can be handy if you need to reprocess or update any existing records in HubSpot as many of the HubSpot API endpoints require these ID's.

Associating / linking Contacts, Deals and Companies together
You can do this while creating many of these objects... But it's much easier to add the associations after these have been created:

Batch API calls
You can only make 40,000 api calls per day which can easily be exceeded if you have a large data set. Use Batch calls as much as possible. It's also much faster to run!

Also ensure you don't place any unnecessary API calls into loops. For example if you need to get the HubSpot user / owner data do this outside of your loop instead of retrieving it for every record you are trying to process.

Filtering / Testing data
Your data will most likely be in a different format. Create functions to filter and convert before inserting into HubSpot. I have few common ones and code examples below:

Dates! These can come in so many different formats. If you want to be able use these in your workflows they will need to be converted. More info here.

function date_convert($date='01/01/2001')
//Convert dates from d/m/y to Hubspot time stamp
$date = trim($date);
$date1 = DateTime::createFromFormat('d/m/y', $date); // change to single y for only 2 digit year double y for 2003
$date1->format( "Y-m-d 00:00:00");
return $create_date = strtotime( $date1->format( "Y-m-d h:m:s") ) * 1000;

Email validation & filtering: If the email field contains additional text you will need to strip this, spaces, notes their name etc. Below is a handy filter for doing so. It can also do multiple email addresses.

$emails = array_filter(filter_var_array(filter_var_array(preg_split('/\s/', $dirty_email_string), FILTER_SANITIZE_EMAIL), FILTER_VALIDATE_EMAIL));
//Should only be 1 email so grab first from array
$HS_Owner_email = reset($emails);

Converting values to their HubSpot equivalent: If you are using select lists that require a specific value you will need to convert these. If there isn't a huge number of options, a quick way to do this is to create a function that converts the value from one to the other. You could also extend your function to pull data and convert data from HubSpot Eg. Owner email address to HubSpot owner's ID.

function dealstage_conversion($excel_dealstage_name)
// Excel name -> HS name
$deal_stages = array(
'Lost' => 'closedlost',
'Won' => 'closedwon',
'Develop' => 'qualifiedtobuy',
'Follow Up' => 'decisionmakerboughtin',
return $deal_stages[$excel_dealstage_name];
return false;

Hopefully that's enough to get you started. Again if you need someone to do this for you please get in touch here


Ralph has been developing websites and systems for nearly 20 years. Passionate and curious, he’s an a-typical developer who understands how users interact with the systems he builds. He understands that systems need to be human-friendly. Ralph loves working in an industry that is constantly changing and disrupting itself.

Get in touch, We love to talk