There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Import a CSV to the draft version of a table

Last updated January 7, 2025

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.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example POST URL: https://api.hubapi.com/hubdb/api/v1/tables/123456/import Any JSON, including the example below, must be placed in the config field of the request. Example JSON config data: This example columnMappings maps the first column of the CSV to the HubDB column with id 2, and the second column in the CSV to the HubDB column with id 3: { "resetTable": false, "skipRows": 1, "format": "csv", "columnMappings": [ { "source": 1, "target": 2 }, { "source": 2, "target": 3 } ] } Example JSON config data when using `idSourceColumn`: { "skipRows":1, "format":"csv", "separator":",", "columnMappings":[ { "target":1, "source":6 }, { "target":2, "source":7 } ], "idSourceColumn":1, "pathSourceColumn":2, "nameSourceColumn":4, "childTableSourceColumn":5, "resetTable":true } Returns a 404 response if the table or import data is not found. Returns a 400 if a non-csv file is sent Otherwise, returns a 200 with the following data: { "errors": [], // A list of any errors encountered during the import "rowsImported": 1, // The number of rows imported to the table "duplicateRows": 0 // The number of duplicate rows found, if using primaryKeyColumn }
# This example a local file named 'hubdbimport.csv' # into the HubDB table with ID 300081 import requests post_url = 'https://api.hubapi.com/hubdb/api/v1/tables/300081/import?hapikey=demo' import_config = '{"resetTable":false,"skipRows":0,"format":"csv","columnMappings":[{"source":1,"target":4},{"source":2,"target":3},{"source":3,"target":5},{"source":4,"target":6}]}' files= { 'config': (None, import_config, 'application/json'), 'file': (None, open('hubdbimport.csv', 'rb'), 'text/csv') } r = requests.post(post_url, files = files) print r print r.content
// This example uploads a local file named 'hubdbimport.csv' // to the HubDB table with ID 300081 <?php $post_url = "https://api.hubapi.com/hubdb/api/v1/tables/300081/import?hapikey=demo"; $csv_file = new CURLFile('hubdbimport.csv','text/csv'); $config_json = '{"resetTable":false,"skipRows":0,"format":"csv","columnMappings":[{"source":1,"target":4},{"source":2,"target":3},{"source":3,"target":5},{"source":4,"target":6}]};type=application/json'; $post_data = array( "file" => $csv_file, "config" => $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; ?>
# Example curl request, # uploading a file named hubdbimport.csv, # to the table with ID 300081: curl -v \ -F "file=@hubdbimport.csv;type=text/csv" \ -F "config={\"resetTable\":false,\"skipRows\":0,\"format\":\"csv\",\"columnMappings\":[{\"source\":1,\"target\":4},{\"source\":2,\"target\":3},{\"source\":3,\"target\":5},{\"source\":4,\"target\":6}]};type=application/json" \ https://api.hubapi.com/hubdb/api/v1/tables/300081/import?hapikey=demo # > {"errors":[],"rowsImported":1,"duplicateRows":0}