Imports

OverviewEndpoints

Use the imports API to import CRM records into your HubSpot account, such as contacts or companies. Once imported, you can access and update records through the various CRM API endpoints, including the contacts API and associations API. You can also import records using the guided import tool in HubSpot.

Start an import

You can start an import by making a POST request to /crm/v3/imports with a request body that specifies how to map the columns of your import file to the associated CRM properties in HubSpot.

API imports are sent as form-data type requests, with the request body containing following fields:

  • importRequest: a text field that contains the request JSON.
  • files: a file field that contains the import file.

The screenshot below shows what your request might look like when using an application like Postman: postman-import-request-no-response0

For the request header, add a Content-Type header with a value of multipart/form-data. 

Please note: if you're using Postman and receive an error, check if there are any duplicate headers, such as Content-Type. If there are duplicates, remove them before you click Send. 

Format the importRequest data

In the request JSON, define the import file details, including mapping the spreadsheet's columns to HubSpot data. Your request JSON should include the following fields:

  • name: the name of the import. In HubSpot, this is the name displayed in the imports tool, as well as the name that you can reference in other tools, such as lists.
  • marketableContactImport: the marketing status of contacts in your import file. This is used only when importing contacts into accounts that have access to marketing contacts. To set the contacts in the file as marketing, use the value true. To set the contacts in the file as non-marketing, use the value false. 
  • files: an array that contains your import file information.
    • fileName: the name of the import file.
    • fileFormat: the import file's format. For CSV files, use a value of CSV. For Excel files, use a value of SPREADSHEET.
    • dateFormat: the format for dates included in the file. By default, this is set to MONTH_DAY_YEAR, but you can also use DAY_MONTH_YEAR or YEAR_MONTH_DAY.
    • fileImportPage: contains the columnMappings array required to map data from your import file to HubSpot data. Learn more about column mapping below.

Map file columns to HubSpot properties

Within the columnMappings array, include an entry for each column in your import file, matching the order of your spreadsheet. For each column, include the following fields:

  • columnObjectTypeId: the ID of the type of object that the data lives on. You can retrieve values for custom objects using the custom objects API. For standard objects, use the following values:
    • Contact: 0-1
    • Company: 0-2
    • Deals: 0-3
    • Tickets: 0-5
    • Notes: 0-4
  • columnName: the name in the column header.
  • idColumnType: for columns that contain property data, use a value of null. For columns that contain unique identifiers, use one of the following values:
    • HUBSPOT_OBJECT_ID: the ID of a record. For example, your contact import file might contain a Company ID column that stores the ID of the company you want to associate the contacts with. 
    • HUBSPOT_ALTERNATE_ID: a unique identifier other than the record ID. For example, your contact import file might contain an Email column that stores the contacts' email addresses.
  • propertyName: the HubSpot property that the data maps to.

Below is an example request body for importing contacts:

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } # This example a local file named 'test_import.csv' # This file contains a list of contact records to import. import requests import json import os # insert your api key here url = "https://api.hubapi.com/crm/v3/imports?hapikey={{}}" data = { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } datastring = json.dumps(data) payload = {"importRequest": datastring} current_dir = os.path.dirname(__file__) relative_path = "./test_import.csv" absolute_file_path = os.path.join(current_dir, relative_path) files = [ ('files', open(absolute_file_path, 'r')) ] print(files) response = requests.request("POST", url, data=payload, files=files) print(response.text.encode('utf8')) print(response.status_code) # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat <<EOF { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } EOF ) curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ https://api.hubapi.com/crm/v3/imports?hapikey=4123...4321

On a successful request, the response will include an importId which you can use to retrieve or cancel the import. 

Get previous imports

To retrieve all imports from your HubSpot account, make a GET request to /crm/v3/imports/. Learn more about paging and limiting results in the Endpoints tab at the top of this article.

To retrieve information for a specific import, make a GET request to /crm/v3/imports/{importId}.

Cancel an import

To cancel an import, make a POST request to /crm/v3/imports/{importId}/cancel. 

Troubleshoot imports

To view errors for a specific import, make a GET request to /crm/v3/imports/{importId}/errors. Learn more about common import errors and how to resolve them.

For more general errors, such as Unable to parse JSON:

  • Ensure that the request body contains a columnMapping entry for each column in your import file. The column order in the request body and import file should match.
  • Ensure that the file's name and the fileName field in your request JSON match, and that you've included the file extension in the fileName field. For example, import_name.csv.
  • Ensure that your header includes Content-Type with a value of multipart/form-data.

Limits

Imports are limited to 1,048,576 rows or 512 MB, whichever is reached first. If your request exceeds either the row or size limit, HubSpot will respond with a 429 HTTP error. When approaching these limits, it's recommended to split your import into multiple requests.  

Was this article helpful? *
This form is used for documentation feedback only. Learn how to get help with HubSpot...