CRM API | 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 = "http://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" \
  http://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-46

Apps & Integrations

CMS

References

Community & Support

App Marketplace New

CMS Asset Marketplace

HubSpot API Docs

Imports

Bulk import CRM data