Import a CSV

Last updated July 16, 2021

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

Method Details

HTTP Methods:

POST

Content Type:

multipart/form-data

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

hubdb

There is a new version of this API available.

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

You can import the CSV into the draft version of the table (allowing a user to examine the table in HubSpot before making the updates live) by including /draft at the end of the request path. See the examples for details.

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 API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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.
Optional Parameters How to use Description
Update Draft details /draft
Used in the request URL
Include /draft at the end of the request path to update the draft version of the table.

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.