Imports
Use the imports API to import CRM records and activities into your HubSpot account, such as contacts, companies, and notes. Once imported, you can access and update records and activities through the various CRM API endpoints, including the contacts API, associations API, and engagements APIs. You can also import records and activities using the guided import tool in HubSpot.
Before starting your import, learn more about the objects and activities that can be imported, as well as file and property requirements.
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.
For the request header, add a Content-Type
header with a value of multipart/form-data
.
The screenshot below shows what your request might look like when using an application like Postman:
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 valuefalse
. - 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 ofSPREADSHEET
. - dateFormat: the format for dates included in the file. By default, this is set to
MONTH_DAY_YEAR
, but you can also useDAY_MONTH_YEAR
orYEAR_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 name or ID of the object or type of activity to which the data belongs. For custom objects, you need to use the
objectTypeId
value instead of the object name, which will look similar to2-3453932
. To retrieve this value for your custom objects, make aGET
request to/crm/v3/schemas
. Learn more about using the custom objects API. - columnName: the name in the column header.
- idColumnType: used to specify that a column contains a unique identifier property. Depending on the property, 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 internal name of the HubSpot property that the data will map to.
Below is an example request body for importing contacts:
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/
. To retrieve information for a specific import, make a GET
request to /crm/v3/imports/{importId}
.
Learn more about paging and limiting results in the Endpoints tab at the top of this article.
Cancel an import
To cancel an active import, make a POST
request to /crm/v3/imports/{importId}/cancel
.
View and troubleshoot import errors
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 or 404 text/html is not accepted:
- Ensure that there is a column header for each column in your file, and that the request body contains a
columnMapping
entry for each column. The column order in the request body and import file should match, and every column needs to be mapped. - Ensure that the file's name and the
fileName
field in your request JSON match, and that you've included the file extension in thefileName
field. For example, import_name.csv. - Ensure that your header includes
Content-Type
with a value ofmultipart/form-data
.
Please note: if you receive an error, check if there are any duplicate headers, such as Content-Type
. This may occur if you're using Postman or if it's included in the header of your Python script. Remove the duplicate before completing the request.
When using the imports API, you can import up to 80,000,000 rows per day. However, individual import files 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.
Thank you for your feedback, it means a lot to us.