Imports

OverviewEndpoints

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
          }
        ]
      }
    }
  ]
}
Object Name objectTypeId
Contact 0-1
Company 0-2
Deal 0-3
Ticket 0-5
Note 0-4

 

Limits

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.  

Handling error

Not all imports will go as expected. Errors can range from the format the file itself to invalid values for a specific row. Because importing is asynchronous, we can't always tell you about the error right when you request the import to start. To make sure you understand if an import had any errors, you can use the /crm/v3/imports/{importId}/errors endpoint. This will give you errors that will look familiar to any users who have seen the error reports from the in app importing. 

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.