CMS API | HubDB

HubDB is a relational data store representing data as rows, columns, and cells in a table, much like a spreadsheet.

Data in a HubDB table can be accessed from HubSpot pages using HubL or the JSON REST APIs. Endpoints that support GET also support CORS, so you can access the data in a table client-side using JavaScript and an account ID (often called Hub ID). Note: This only applies to GET methods. Other methods and the GET all tables API require authentication, and will not support CORS.

Modifying HubDB tables

HubDB tables can be modified in HubSpot, making it easy for anyone to add or modify data in those tables. You can also use the API for this.

For more details and information on using data in a HubDB table on a HubSpot site, click here.

Rate limits

HubDB API requests have different rate limits, depending on the type of request:

Any GET requests made that don't require authentication (including client-side JavaScript requests) are limited to 10 requests per second. These requests will not count towards the daily limit.
All other requests using authentication follow the standard limits.

Changes in V3:

Tables should have both name and label. This name cannot be changed once the table is created. Names can only include lowercase letters, digits, and underscores and cannot begin with a number. Both name and label should be unique in the account.
API supports both table id and name in the URL paths.
GET row endpoints return column name instead of id in values field. Also, POST / PUT / PATCH row endpoints require column name instead of id in values field.
Row update PATCH endpoints now accept sparse updates, which means we can specify only the column values that we need to update (whereas we had to specify all the column values in the previous versions). When you update a column with a list of values such as multi-select, you need to specify the list of all the values. In order to delete the value for a column, you need to specify the column with the value as null in the request.
Removed the endpoints to get / update / delete a row cell in favor of the row update PATCH endpoints.
Import endpoint now supports an optional field idSourceColumn along with existing fields in the JSON-formatted options. You can use this field to specify the column in the csv file which contains row ids. To import new rows along with the new values for existing rows, you can simply specify 0 as the row id for the new rows and the valid row ids for the existing columns. See more details in the Import section below. Also you can use column names or ids in the target field of the column mappings in the JSON-formatted options.
Clone endpoint requires a new name and new label.

Draft vs Live Versions

HubDB tables have both draft and live versions and live versions can be published or unpublished. This will allow you to update data in the table, either for page previews or testing or to allow for a manual approval process, without affecting any live pages. Draft data can be reviewed and then pushed live / published by a user working in HubSpot, or via /push-live endpoint of the API. The draft data can also be discarded via /reset endpoint, allowing users to go back to the current live version of the data without disruption.

Creating tables

Tables can have the following fields:

Required fields	How to use	Description
Name	`"name":{name}`	The internal name of the table. This name cannot be changed once the table is created. Names can only include lowercase letters, digits, and underscores and cannot begin with a number.
Label	`"label":{label}`	Label of the table. This is what users will see when editing the table in HubSpot.

Optional fields	How to use	Description
Use for dynamic pages	`"useForPages": false`	Set this to true to use the page for dynamic pages.
Columns	`"columns":[ {list of columns} ]`	A list of column definitions that will be used for the table.
Allow public API access	`"allowPublicApiAccess": false`	Set this to true to allow public API access without any auth.
Allow child tables	`"allowChildTables": false`	Set this to true to allow child tables for each row.
Enable dynamic pages for child tables	`"enableChildTablePages": false`	Set this to true to create dynamic pages for child tables

Column

Each column should include the following fields:

Field	How to use	Description
Name	`"name":{name}`	The internal name of the column. This name cannot be changed once the column is created
Label	`"label":{label}`	Optional - The label for the column. This is what users will see when editing the table in HubSpot.
Type	`"type":{type}`	The data type of the column. Must be one of `TEXT` - A simple text field. `RICHTEXT` - A text field that supports basic HTML. `NUMBER` - a number field `BOOLEAN` - Represented as a checkbox in HubSpot, uses 0 for unchecked and 1 for checked. `DATE` - Stores a specific date as a millisecond timestamp set to midnight UTC for the specified date. `DATETIME` - Stores a date and a time as a millisecond timestamp. `SELECT` - The column can only be set to one of a set of options. `MULTISELECT` - The column can be set to one or more of a set of options. URL - Stores a URL. `LOCATION` - Stores a latitude and longitude location. `IMAGE` - Stores the URL of an image. VIDEO - Stores the player id of the video. FOREIGN_ID - Stores the row id from the referenced table. CURRENCY - Stores the number.
Options	`"name":{name} "options": [ {list of options} ]`	If the column is the `SELECT` type, this will be used as the options for the column. Each option must include a name and a type of `"option": [{"name":"a", "type":"option"}, {"name":"b", "type":"option"}.`

Example request for table creation

JSON

//example request
{
 "label": "Test Table",
 "name": "test_table",
 "columns": [
 {
   "name": "text_column",
   "label": "Text Column",
   "archived": false,
   "type": "TEXT"
 },
 {
   "name": "number_column",
   "label": "Number Column",
   "archived": false,
   "type": "NUMBER"
 },
 {
   "name": "multiselect",
   "label": "Multi Select Column",
   "archived": false,
   "options": [
   {
     "id": "1",
     "name": "Option 1",
     "type": "option"
   },
   {
     "id": "2",
     "name": "Option 2",
     "type": "option"
   }
   ],
   "type": "MULTISELECT"
 }
 ],
 "useForPages": true,
 "allowChildTables": true,
 "enableChildTablePages": false,
 "dynamicMetaTags": {
 },
 "allowPublicApiAccess": false
}

While updating existing tables or columns, include the "id " field as well.

Creating table rows

Rows should include the following fields:

Optional fields	How to use	Description
Path	`"path": “example path”`	If the table is enabled for dynamic pages, this is the path suffix used for the page for this row.
Page title	`"name": “example title”`	If the table is enabled for dynamic pages, this is the HTML title used for the page for this row.
Child table id	`"childTableId: 1902373`	Specify the child table id for multi-level dynamic pages.
Values	`"values": [ {list of cell values} ]`	A list of values for the cells in the row. Each entry requires a column name you’d get when pulling the table details and the value being set for that column. For example, when setting a column test and type `TEXT` to use the value `'test value’`, use `"test": "test value"`. See below for more details for the values used by specific column types.

While updating existing rows, include "id " field in the input object.

Example request for row creation

JSON

//example request

{
 "values": {
   "text_column": "sample text value",
   "number_column": 76,
   "rich_text_column": "<strong>This is a styled paragraph.</strong>",
   "date_column": 1591228800000,
   "date_time_column": 1604450520000,
   "boolean_column": 1,
   "select_column": {
      "id": "1",
      "name": "option 1",
      "type": "option"
    },
   "multiselect_column": [
   {
     "id": "1",
     "name": "Option 1",
     "type": "option"
   },
   {
     "id": "2",
     "name": "Option 2",
     "type": "option"
   }
   ],
   "url_column": "https://www.hubspot.com/marketing",
   "video_column": 3392210008,
   "image_column": {
      "url": "https://f.hubspotusercontentqa00.net/hubfs/99992002/image3%20(1).jpg",
      "width": 1600,
      "height": 900,
      "type": "image"
    },
    "foreign_id_column": [
      {
        "id": "4364402239",
        "type": "foreignid"
      },
      {
        "id": "4364402240",
        "type": "foreignid"
      }
    ]
 },
 "path": "test_path",
 "name": "test_title",
 "childTableId": "1902373"
}

Filtering & sorting table rows

Filters are applied as query parameters, by adding the column name, followed by two underscores (_), and then the operator. For example, if you have a number column named 'bar', you can filter the results to only include rows where the 'bar' column is greater than 10 using this parameter: &bar__gt=10. Any number of filters can be included as query parameters in the request URL. All filters are ANDed together. ORing filters are not currently supported.

Operators can only be applied to specific column types. When passing values for MULTISELECT columns, the ids or names should be separated by commas (e.g. multiselect_column__contains=1,2) For the purposes of these filters, the built in column `hs_id`is a NUMBER column, the `hs_created_at` column is a DATETIME, and the `hs_path` and `hs_name` columns is a TEXT column.

For DATETIME filters, you can use relative dates in place of timestamps in order to specify a value relative to the current time. For example, -3h would correspond to the timestamp 3 hours before now, whereas 10s would correspond to 10 seconds in the future. Supported timeunits are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days). Current time can be used by specifying a zero value: 0s

Field name	Operator	Description
Equals	`eq (or none)`	All column types This filter is applied if no operator is used &example_column=value When used with MULTISELECT columns, returns rows that exactly match supplied values
Not equal	`ne`	All column types
Contains	`contains`	TEXT, RICHTEXT, MULTISELECT When used with MULTISELECT columns, returns rows that contain all of the supplied values.
Less than	`lt`	NUMBER, DATE, DATETIME
Less than or equal	`lte`	NUMBER, DATE, DATETIME
Greater than	`lte`	NUMBER, DATE, DATETIME
Greater than or equal	`gte`	NUMBER, DATE, DATETIME
Null	`is_null`	All column types, except BOOLEAN This filter does not require a value (&example_column__is_null=)
Not null	`not_null`	All column types, except BOOLEAN This filter does not require a value (&example_column__not_null=)
Like	`like`	TEXT, RICHTEXT
Not like	`not_like`	TEXT, RICHTEXT
Contains (case insensitive)	`icontains`	TEXT, RICHTEXT
Starts with	`startswith`	TEXT, RICHTEXT
In	`in`	NUMBER, SELECT, MULTISELECT Returns rows where the column includes at least one of the passed options. When there is no other Order By in the query parameter, the results will be sorted in the order in which values are specified in the 'in' operator.

Sorting can also be applied as query parameters. You can specify the column name as value to the query parameter `sort` and it returns the rows in the natural order of the specified column. You can reverse the sort by adding a - to the column name: sort=-bar. You can include this parameter multiple times to sort by multiple columns.

In addition to sorting by a column, there are three functions that can be used:

geo_distance(location_column_name, latitude, longitude): Takes the name of a location column and coordinates, returns the rows ordered by how far away the values of the specified location column are from the provided coordinates.

length(column_name): Takes the name of a column, returns the rows ordered by the length of the column value (calculated as a string)

random(): Returns the rows in random order.

These functions also support reverse ordering: sort=-geo_distance(location_column,42.37,-71.07) returns the items that are the farthest away first.

Importing tables

Import endpoint takes a multi-part POST request. The first part will be a set of JSON-formatted options for the import and you can specify this with the name as " config ". The second part will be the CSV file you want to import and you can specify this with the name as " file ".

Include the following fields as a JSON string in the JSON-formatted options.

Field name	How to use	Description
skipRows	`"skipRows":{skipRows}`	The number of header rows that should be skipped over. Defaults to `1` (skipping the first row and treating it as a header). Set this to `0` if all of the rows are valid data.
separator	`"separator":{separator}`	Column delimiter in the CSV file. Default is `,`
idSourceColumn*	`"idSourceColumn":{idSourceColumn}`	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.
resetTable	`"resetTable":{resetTable}`	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.
nameSourceColumn	`"nameSourceColumn":{nameSourceColumn}`	The index of the column in the source file containing the row’s `name`.
pathSourceColumn	`"pathSourceColumn":{pathSourceColumn}`	The index of the column in the source file containing the row’s `path`.
childTableSourceColumn	`"childTableSourceColumn":{childTableSourceColumn}`	The index of the column in the source file containing the row’s `childTableId`.
columnMappings	`"columnMappings":{list of columnMappings}`	A list of mappings for the columns in the source file to the columns in the destination HubDB table. Each mapping must have the following format: `{"source":1,"target”:"column_name"}` where `source` refers to the column index in the source file and `target` refers to the name of the HubDB table column. You can get the name of the columns by getting the details for the table.
primaryKeyColumn	`"primaryKeyColumn":{primaryKeyColumn}`	The name of a column in the target HubDB table to use for row deduplication.
encoding	`"encoding":{encoding}`	Encoding type. (utf-8, ascii, iso-8859-2, iso-8859-5, iso-2022-jp, windows-1252)
format	`"format":{format}`	Unused. Only CSV is supported.

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)
With add rows option (can be specified as "resetTable":false in the JSON-formatted options)

Example JSON config

JSON

//example config
{
"skipRows":1,
"format":"csv",
"separator":",",
"encoding":"utf-8",
"columnMappings": [
  {"target":1,"source":"text_column"}, 
  {"target":2,"source":"number_column"},
  {"target":3,"source":"multiselect"}
],
"idSourceColumn":1,
"pathSourceColumn":2,
"nameSourceColumn":4,
"childTableSourceColumn":5,
"resetTable":true
}

Shell script

curl -L -X POST 'https://api.hubspotqa.com/hubdb/api/v2/tables/xxxxxx/import?portalId=xxxxxxx&hapikey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
-H 'Content-Type: multipart/form-data' \
-F 'config="{\"skipRows\":1,\"format\":\"csv\",\"separator\":\",\",\"encoding\":\"iso-8859-1\",\"columnMappings\":[{\"target\":1,\"source\":7},{\"target\":3,\"source\":8}],\"idSourceColumn\":1,\"pathSourceColumn\":null,\"nameSourceColumn\":null,\"childTableSourceColumn\":null,\"resetTable\":true}"' \
-F 'file=@"/Users/xxxxxxxxxxxxx/Downloads/filename.csv"'

Share your feedback

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.

HubSpot API Docs

HubDB

Access and test APIs in beta.

Modifying HubDB tables

Rate limits

Changes in V3:

Draft vs Live Versions

Creating tables

Column

Example request for table creation

Creating table rows

Example request for row creation

Filtering & sorting table rows

Importing tables

Reset Options

Example JSON config

Example curl command for the import endpoint:

Share your feedback

Apps & Integrations

CMS

References

Community & Support

App Marketplace New

CMS Asset Marketplace

HubSpot API Docs

HubDB

Access and test APIs in beta.

Modifying HubDB tables

Rate limits

Changes in V3:

Draft vs Live Versions

Creating tables

Column

Example request for table creation

Creating table rows

Example request for row creation

Filtering & sorting table rows

Importing tables

Reset Options

Example JSON config

Example curl command for the import endpoint:

Share your feedback