There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Import a CSV to the draft version of a table

Last updated January 31, 2024

POST /hubdb/api/v2/tables/:tableId/import

Please note: as of January 31, 2024, the HubDB v2 API has been sunsetted. The associated endpoints will not be fully turned off until a future date in 2024, but if you're using this API, please migrate to the HubDB v3 API, which includes many performance, usability, and API consistency improvements over the previous two versions. Learn more about this sunset on the HubSpot Developer Changelog.

Import the contents of a CSV file into the draft version of an existing HubDB table.

Importing a CSV will always update the draft version of the table. You will need to publish the draft via API or via the publish tools in HubSpot before the import would affect the live, public version of the table.

This endpoint takes a multipart POST request. The first part will be a set of JSON formatted options for the import.  The second part will be the CSV file you want to import.

Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Table ID :tableId
Used in the request URL
The ID of the table you want to import the data into.
resetTable Used in the request JSON Defaults to false. If false, the rows will be inserted / updated without removing anything from the table. If true, the rows from csv file will be inserted / updated from the table and rows that exists in the table but not in the csv file will be deleted. See the Reset options section below more detailed information.
skipRows Used in the request JSON The number of header rows in the CSV file that should be skipped over. Defaults to 1 (skiping the first row in the CSV and treating it as a header row), set this to 0 if all of the rows in the CSV are data rows you want imported.
format Used in the request JSON Must be "csv", as only CSV files are currently supported.
columnMappings Used in the request JSON A list of mappings for the columns in the CSV to the columns in the HubDB table.

Each mapping will have the following format:
{"source":1,"target”:2}
"source" refers the column in the CSV, starting with 1.
"target" refers to the id of the table column. You can get the IDs for the columns by getting the details for the table.
primaryKeyColumn Optional, Used in the request JSON The Name of a column to deduplicate against existing rows in the database. You can get the names for the columns by getting the details for the table.
nameSourceColumn Optional, Used in the request JSON The number of the column in the CS file (starting with 1) that should be imported into the name column.
pathSourceColumn Optional, Used in the request JSON The number of the column in the CSV (starting with 1) that should be imported into the path column.
idSourceColumn Optional, Used in the request JSON The index of the column in the source file containing the row’s ID(hs_id). If this column is specified, the import process updates the existing rows in the table for the matching row ids from csv. This is optional and you can ignore this during the first time you insert data into a table. See the Reset options section below more detailed information.

Reset Options:

We have two options while importing the data into the table: Add Rows and Reset.

  • With reset table option (can be specified as "resetTable":true in the  JSON-formatted options)
    • if the rows in the csv file does not have a row id column(hs_id) or row id is specified as 0, those rows will be inserted with the new row ids generated.
    • if the row ids in the csv file already exists in the target table, the existing rows in the table will be updated with the new values from the input file.
    • if the table has rows but the input csv file does not have those row ids, those rows will be deleted from the target table.
    • if the row ids in the input csv file do not exist in the target table, those rows will be inserted with the new row ids generated and the row ids given in the input file will be ignored.
    • if the input csv file does not contain the row id column at all, all the rows will be deleted from the target table and the rows from the input file will be inserted with the new row ids generated.
  • With add rows option (can be specified as "resetTable":false in the  JSON-formatted options)
    • if the row ids in the csv file already exists in the target table, the existing rows in the table will be updated with the new values from the input file.
    • if the table has rows but the input csv file does not have those row ids, those rows will not be deleted from the target table and those rows will remain unchanged.
    • if the row ids in the input csv file do not exist in the target table, those rows will be inserted with the new row ids generated and the row ids given in the input file will be ignored.
    • if the rows in the csv file does not have a row id column or row id is specified as 0, those rows will be inserted with the new row ids generated.