There's a new version of the HubSpot API
We're also working on a new documentation website, you're invited to check it out and give us your feedback.
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.
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.
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.
HubDB API requests have different rate limits, depending on the type of request:
With the release of the HubDB v2 API, tables now support a draft version. This will allow you to update data in the table, either for testing or to allow for a manual approval process, without affecting any live pages. Draft data can be reviewed and then published by a user working in HubSpot, or published via the API. The draft data can also be discarded, allowing users to go back to the current live version of the data without disruption.
Individual tables will have the following data. See creating a table for more details on the data types available for each column. See the documentation for dynamic pages for more details about the useForPages field.
{
"id": 300081,
// Integer, read-only; The unique ID of the table
"name": "Example HubDB Table",
// String; The name of the table
"createdAt": 1479479977286,
// Integer, read-only; A Unix timestamp (in milliseconds) of the time that the table was created.
"publishedAt": 1479480005606,
// Integer, read-only; A Unix timestamp (in milliseconds) of the time that the published.
// A table is considered published if this value is populated with a value representing a time before the current time.
// Only tables that are published can be accessed using unauthenticated GET methods.
"updatedAt": 1483746758882,
// Integer, read-only; A Unix timestamp (in milliseconds) of the time that the table was last updated.
"columns": [
// A list of objects defining the columns in the table.
// It is possible for this list to be empty if there are no user defined columns.
// Columns will have the following format:
{
"name": "number_column",
// String; The internal name of the column
"label": "Number Column",
// String; The human readable label of the column. This is displayed when editing the table in HubSpot
"id": 3,
// Integer, read-only; The unique ID of the column.
// Column IDs are assigned automatically by the incrementing (read-only) columnCount field.
"width": 200,
// Integer; The visual width of the column when editing the table in HubSpot.
// This field will only be populated if a user has resized the column in HubSpot.
"type": "NUMBER"
// String, one of TEXT, RICHTEXT, NUMBER, BOOLEAN, DATE, DATETIME, SELECT, MULTISELECT, URL, LOCATION, IMAGE
// The data type of the column. See creating a table for more details on these data types.
},
// SELECT and MULTISELECT columns have additional data
{
"name": "choices",
// String; The internal name of the column
"label": "Choices",
// String; The human readable label of the column, this is displayed when editing the table in HubSpot
"id": 8,
// Integer, read-only; The unique ID of the column.
"options": [
// A list of valid options for the SELECT or MULTISELECT column.
{
"id": 1,
// Integer; The unique ID of the option
"name": "a",
// String; The internal name of the option
"type": "option"
// String; This field will always be "option"
},
{
"id": 2,
"name": "b",
"type": "option"
},
{
"id": 3,
"name": "c",
"type": "option"
}
],
"type": "SELECT",
// String, one of TEXT, RICHTEXT, NUMBER, BOOLEAN, DATE, DATETIME, SELECT, MULTISELECT, URL, LOCATION, IMAGE
// The data type of the column. See creating a table for more details on these data types.
"optionCount": 3
// Integer, read-only; The number of options set up for the column
}
],
"deleted": false,
// Boolean, read-only; Whether or not the table has been deleted.
// This will effectively be false for all tables, as deleted tables will not appear in the API.
"useForPages": false,
// Boolean; This will be true for tables enabled for dynamic pages.
"rowCount": 6,
// Integer, read-only; The number of rows in the table
"columnCount": 2
// Integer, read-only; The number of columns in the table
}Individual rows will have the following format. See creating a row for more details about the formats for each column type. See the documentation for dynamic pages for more details about the path and name fields.
{
"id": 4682015823,
// Integer, read-only; The unique ID for the row
"createdAt": 1483564738680,
// Integer, read-only; A Unix timestamp (in milliseconds) of the time that the row was created.
"path": "examplepath",
// String or null; If the table is enabled for dynamic pages, this is the path suffix of the page for this row.
"name": "Example page title",
// String or null; When the table is enabled for dynamic pages, this is the HTML title of the page for this row.
"values": {
// An object containing the values for the cells of the row
// Each entry has the format of { column ID : cell value}
// The column ID must be a string matching the ID of a defined column
// The cell value format will depend on the column type. See below for some examples, and creating a row for more details.
// The column ID will match the ID of the column in the table definition
"3": 7,
// A NUMBER value for column ID 3
"4": "Example Text",
// A TEXT value for column ID 4
"5": 1484265600000,
// A DATE value for column ID 5. Both DATE and DATETIME fields must be set as Unix timestamps in milliseconds.
"6": 1485057600000,
// A DATETIME value for column ID 6
"7": "<p>This is some text.</p>",
// A RICHTEXT value containing HTML for column ID 7
"8": [
// This is an array of option values for a MULTISELECT column with ID 8
{
"id": 1,
// Integer; The ID of the option from the column definition in the table definition.
"name": "a",
// String; The name of the option.
"type": "option"
// String; The type of the value. For SELECT or MULTISELECT values, this must "option"
},
{
"id": 2,
"name": "b",
"type": "option"
}
],
"9": {
// This is an option value for a SELECT column with ID 9
"id": 2,
// Integer; The ID of the option from the column definition in the table definition.
"name": "b",
// String; The name of the option.
"type": "option"
// String; The type of the value. For SELECT or MULTISELECT values, this must be "option"
},
"10": {
// This is a LOCATION value for the column with ID 10
"lat": 41.836826,
//Float; The latitude coordinate of the location
"long": -88.461914,
// Float; The longitude coordinate of the location
"type": "location"
// String; for location values, this must be "location"
},
"11": {
// This is an IMAGE value for the column with ID 11
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/97/The_Earth_seen_from_Apollo_17.jpg/240px-The_Earth_seen_from_Apollo_17.jpg",
// String; the URL of the image
"type": "image"
// String, this must be "image" for image values
},
"12": "https://integrate.hubspot.com/"
// A string value for a URL column with ID 12
}
}