Imports
Bulk import CRM data
Imports are used to populate a HubSpot account with object (including contacts, companies, deals, and tickets) data that can be used with the sales, marketing, and service tools. Imports need a structured source file, such as an Excel or CSV (comma-separated value) document. A single structured file gives users the power to import tens of thousands of objects into their accounts at once.
Example use case: The import endpoints can be used to create objects in HubSpot from an Excel or CSV (comma-separated value) source file. There is a request value, fileFormat
, that is used to identify the type of import file that will be provided. This fileFormat
request value defaults to CSV
. For Excel spreadsheets, use a value of SPREADSHEET
. There is another request value for dateFormat
used to specify what style of date you are providing. You can use MONTH_DAY_YEAR
(the default), DAY_MONTH_YEAR
, YEAR_MONTH_DAY
depending on if your dates are formatted as MM/DD/YYYY,
DD/MM/YYYY
, or YYYY/MM/DD
respectively.
Please use the columnObjectTypeId
instead of the columnObjectType
to ensure forward compatibility. The objectTypeId
's of the HubSpot native objects are listed in a table below, values for custom objects can be retrieved using the custom objects API.
Note: The"Get information on any import" endpoint documented on the Endpoints tab takes an integer as an argument for the importId
field. Prior to August of 2018, import Ids were alphanumeric. This endpoint is intended for use with imports created August 2018 and later.
Example POST URL:
https://api.hubapi.com/crm/v3/imports?
Example importRequest JSON data:
This example contains 4 columns:
- First name, mapped to the firstname contact property
- Email, mapped to the email contact property
- Company ID, which contains a list of company record IDs
that the contact will be associated with.
- Close date, mapped the closedate contact property
{
"name": "test_import",
"files": [
{
"fileName": "final_emails.csv",
"fileFormat": "CSV",
"dateFormat":"DAY_MONTH_YEAR",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"ignored": false,
"columnName": "First Name",
"idColumnType": null,
"propertyName": "firstname",
"foreignKeyType": null,
"columnObjectTypeId":"0-1"
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": null,
"columnObjectTypeId":"0-1",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Company ID",
"idColumnType": "HUBSPOT_OBJECT_ID",
"propertyName": null,
"columnObjectTypeId":"0-2",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Close date",
"idColumnType": null,
"propertyName": "closedate",
"foreignKeyType": null,
"columnObjectTypeId":"0-1",
"associationIdentifierColumn": false
}
]
}
}
]
}
# 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": "test_import",
"files": [
{
"fileName": "test_import.csv",
"fileFormat": "CSV",
"fileImportPage": {
"hasHeader": True,
"columnMappings": [
{
"ignored": False,
"columnName": "First Name",
"idColumnType": None,
"propertyName": "firstname",
"foreignKeyType": None,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": False
},
{
"ignored": False,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": None,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": False
}
]
}
}
]}
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)
<?php
// This example imports a local file named 'import_file.csv'
$post_url = "https://api.hubapi.com/crm/v3/imports?hapikey=1234...5342";
$csv_file = new CURLFile('import_file.csv','text/csv');
$config_json = '{"name":"test_import","files":[{"fileName":"final_emails.csv","fileFormat":"CSV","fileImportPage":{"hasHeader":true,"columnMappings":[{"ignored":false,"columnName":"First Name","idColumnType":null,"propertyName":"firstname","foreignKeyType":null,"columnObjectType":"CONTACT","associationIdentifierColumn":false},{"ignored":false,"columnName":"Email","idColumnType":"HUBSPOT_ALTERNATE_ID","propertyName":"email","foreignKeyType":null,"columnObjectType":"CONTACT","associationIdentifierColumn":false},{"ignored":false,"columnName":"Company ID","idColumnType":"HUBSPOT_OBJECT_ID","propertyName":null,"columnObjectType":"COMPANY","associationIdentifierColumn":false}]}}]};type=application/json';
$post_data = array(
"files" => $csv_file,
"importRequest" => $config_json
);
$ch = curl_init();
@curl_setopt($ch, CURLOPT_POST, true);
@curl_setopt($ch, CURLOPT_URL, $post_url);
@curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
$response = @curl_exec($ch); //Log the response from HubSpot as needed.
$status_code = @curl_getinfo($ch, CURLINFO_HTTP_CODE); //Log the response status code
@curl_close($ch);
echo $status_code . " " . $response;
?>
# 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": "test_import",
"files": [
{
"fileName": "final_emails.csv",
"fileFormat": "CSV",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"ignored": false,
"columnName": "First Name",
"idColumnType": null,
"propertyName": "firstname",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Company ID",
"idColumnType": "HUBSPOT_OBJECT_ID",
"propertyName": null,
"columnObjectType": "COMPANY",
"associationIdentifierColumn": false
}
]
}
}
]
}
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
Object Name | objectTypeId |
Contact | 0-1 |
Company | 0-2 |
Deal | 0-3 |
Ticket | 0-5 |
Note | 0-4 |
Imports are limited to 500,000 rows or 400 MB, whichever comes first. We recommend you break up your import into multiple requests if your data starts to approach these limits. If your request goes over either the row or size limit, we'll respond with a 429 HTTP response code.