Deep dive

    How to upload HubSpot data in bulk

    deep dive
    hubspot api
    bulk upload
    Ryan Chen

    Ryan Chen

    Content Marketing Associate

    Learn how to bulk import contacts, properties, and records into HubSpot. We’ll review how to use the File Upload tool and share common mass upload use cases.


    Managing massive volumes of customer data in CRMs such as HubSpot can be tedious and time-consuming. Whether you need to import contacts in bulk, refresh outdated records, or migrate data between multiple CRMs, manual batch data jobs are slow, inefficient, and can prevent your sales team from closing new business.

    Sales operations professionals often spend hours updating obsolete contact properties, mass uploading contacts to a list, manually adjusting lead scores, and working on any number of other data projects. Meanwhile, your sales team has to spend more time on manual updates and admin work, distracting them from selling—or worse, slow and inefficient data jobs can negatively impact follow-up times, which will dramatically cut your conversion rates.

    The average time it takes for companies to respond to leads

    The average time it takes for companies to respond to leads. Image courtesy of HBR.

    If you only had a small handful of records at any given time, manual updates might be manageable. But what if you’re regularly working with thousands or millions of records? Clearly, manual mass upload projects are not efficient, scalable, or a good use of your revenue team’s constrained resources. 

    Luckily, there’s a better way to execute bulk uploads. In this guide, we’ll share a list of essential record types, common mass upload use cases, how to perform bulk imports in HubSpot, and how you can manage your CRM data at scale to maximize sales productivity. Let’s get started.

    Hubspot import

    Importing data into HubSpot.

    Essential objects and records in HubSpot

    Before you start mass updating data in HubSpot CRM, here are a few terms you need to know so you can set up your import files correctly. Import files are HubSpot's term for formatted flat files or spreadsheets that are ready for upload.

    An object describes the type of relationship you have with a specific organization. There are two categories of objects:

    • Standard CRM objects

      • Contacts - An individual who provided you with their personal information. For example, you can create a contact when someone engages with a marketing offer, they sign up for a demo, or a visitor on your website submits a form.

      • Companies - An organization that has interacted with your company

      • Deals - A potential customer who has committed an action that indicates buying interest, such as booking a meeting or speaking with your sales team.

      • Tickets - Tickets include customer inquiries, notes, emails, and conversations.

      • Custom objects - You can also create custom objects personalized to match your team’s unique needs. For example, if you are a real estate company, you can define objects as “listings.”

    • HubSpot-defined objects are similar to standard objects and give you the flexibility to customize an object's name and relationship relative to other file types. HubSpot-defined objects include calls, conversations, products, and quotes.

    Record is a single instance of an object (i.e. "John Adams" is a contact record). You can associate different record types to better organize and track information. Consider associating a record when, for example, you are corresponding with multiple stakeholders at one company, and you want to ensure your team doesn't reach out to the same contact twice.

    property is a field that you can use to store information about a record. In the custom object "listing" example, the properties attached to each "listing" record might include information such as price, location, number of bedrooms, and any other features.

    unique identifier is a property field that marks a record as one of one. Unique identifiers are important because they differentiate records from one another and reduce the chance of duplicating efforts. You need three unique identifiers to set up a proper import file: email address (or contact ID), company domain name (i.e. company website or company ID), and object ID.

    HubSpot generates an object ID when you create an object. An object ID is a record's fingerprint and helps distinguish records with similar properties (such as identical names) from one another. On top of importing contacts, the object ID is also key to identifying duplicate records since HubSpot uses a record's unique object ID to compare with existing records. Here's an example of what an object ID looks like in HubSpot: 285943

    An example of a file properly formatted and ready for upload.

    An example of a file properly formatted and ready for upload.

    Using HubSpot’s File Upload tool 

    Once you’ve formatted your record list according to the above data types, you’re ready to begin the importing process. Whether you’re moving one object or thousands across your CRM, you might consider using Hubspot’s File Upload tool

    HubSpot’s File Upload tool

    HubSpot’s File Upload tool.

    The file upload tool is free, fairly non-technical, and requires that your files meet several criteria. Here are a few criteria your files must meet to begin the import process:

    • You must configure your data according to the proper HubSpot-recognized format (object, property, unique identifier, object ID)

    • HubSpot supports only .csv (i.e. spreadsheets), .xlsx, and .xls files

    • The file must be smaller than 150 MB

    • The file must contain less than 250,000 rows and 1,000 columns

    • If you’re looking to deduplicate identical files, HubSpot will display up to 2,000 duplicates

    Note: If your import file exceeds the limits specified above, the import will fail. To successfully upload your data, you’ll need to break apart the large file into several smaller files that meet import requirements, and then re-import.

    To start importing multiple objects, upload your file of choice (in this case, our spreadsheet) into HubSpot. Make sure your spreadsheet file is not only formatted correctly but also mapped correctly. HubSpot automatically matches the column headers in your file with your designated properties. If your columns don’t match or are left blank, your file will fail to import. You can change incorrectly matched columns by selecting the correct property in the dropdown menu beside it. 

    Mapping columns to the right property

    Mapping columns to the right property.

    It’s also important to give your import a name. Especially when you’re performing multiple batch imports at once, a best practice is to have a logical and consistent naming convention (incorporating account details, dates, and so on) to keep your mass upload jobs efficient and organized. Once you’ve properly formatted your file, confirmed that your columns are mapped, and named your import, click Finish import, and you’ll be ready to go.

    Advanced use cases for bulk uploading data into HubSpot

    Here are a few examples of advanced bulk upload use cases your sales operations team might encounter:

    Migrating to another CRM or syncing data across multiple CRMs

    Low sales productivity can cost companies $1 trillion every year, so finding a CRM that fits your needs, or migrating to one that does, is critical to the success of your organization. And if you’ve recently experienced a merger or acquisition, you might even find yourself with a sales organization that uses two entirely different solutions to manage customer data, which can easily lead to duplicate work and more delays that could cost your sales organization deals and make data governance an enormous headache. 

    CRM migrations are massive undertakings that require planning, modeling, and adaptation. Whether you’re syncing multiple CRMs due to an acquisition, moving away from a legacy system, or transitioning from another CRM vendor, your revenue team can streamline the migration process by working with CRM data in bulk. By managing data in bulk, you can focus on the strategic elements of migration and efficiently transition to your new CRM.

    Maintaining good data hygiene

    While your data is sitting inside your CRM, people may change jobs, move to new addresses, or get new emails. Your data might also be incorrect, improperly formatted, or missing important fields, especially as your sales organization evolves to split sales teams across different product lines or territories. As a result, your database naturally “decays” by about 22.5% every year, meaning that a significant percentage of your contact and account records are likely outdated. To keep your data up-to-date, you need to deliberately maintain your database. Instead of jumping into your CRM and manually cleansing data, you can execute data hygiene jobs in bulk and save hours of manual work.

    Deduplicating data

    As you add new records to your CRM, it’s easy for duplicates to sneak into your database and create headaches for your sales team. Duplicate data can also be expensive—when you account for storage and productivity costs, research suggests that the average duplicate record costs as much as $96 per record. In HubSpot, you can deduplicate data by using a record’s unique identifier to hone in on identical records. HubSpot will look at a contact’s email, company domain name, or object ID to merge or delete existing records. 

    However, if you need to manage duplicate records for any other application, you won’t have HubSpot’s deduplication functionality at hand to streamline the time-consuming, manual work. To handle mission-critical processes at scale, you’ll need the power of a General Automation Platform.

    Executing bulk uploads with General Automation Platforms

    HubSpot’s File Upload tool is adequate for small and infrequent batch upload jobs. But the conditions you must meet to complete a successful import make it much harder to use HubSpot’s File Upload tool when regularly processing high volumes of data. 

    The File Upload tool simply doesn’t support larger-sized upload jobs. Your data won’t import if file size exceeds the critical limit that HubSpot can handle. Moreover, if you’re looking to perform bulk processes after the data import (such as mass creating net new records, editing object names in bulk, associating or unassociating records in bulk, updating deal stages of multiple records at once, and more), HubSpot won’t be able to support that, either.

    HubSpot’s File Upload tool also won’t suffice for use cases that require kicking off dynamic, multi-step operations. What if you collect thousands of customer records from webinars every week and need to dynamically add these contacts to your email list? What if you need to manually enrich missing contact details for millions of sales records? What if you need to automate data hygiene processes by purging dummy records at scale? Unfortunately, HubSpot’s File Upload tool is insufficient in handling more sophisticated processes that go beyond bulk uploads.

    A general automation platform

    A General Automation Platform.

    Alternatively, you can use a General Automation Platform (GAP) to streamline bulk uploads and take full control of your CRM data. GAPs are low-code platforms that empower business users to stand up API-level integrations between any application. In addition, you can orchestrate dynamic, multi-step automated workflows to minimize manual work, instantly execute large-scale, mission-critical tasks such as bulk uploads error-free, and drive revenue. Using GAPs, you can automate CRM data projects such as bulk imports, lead enrichment, data hygiene projects, scheduled list uploads, and more.

    If you’d like to learn more about a General Automation Platform, consider joining our next weekly group demo. For more reading on how a GAP can help you manage HubSpot CRM data, check out these resources:

    Subscribe to our blog

    Related Posts

    master-lead-management-lead-lifecycle blog post cover image

    The ultimate guide to automating the entire lead lifecycle

    Read more

    Sales metrics: The practical guide for sales operations

    Read more
    automate-lead-list-uploads blog post cover image

    Automating lead list uploads: Mission-critical, and much easier than you think

    Read more

    How to automate lead enrichment

    Read more