Skip to main content
These endpoints provide a flexible way to ingest and manage external data without the need to map it to standard HubSpot CRM object schemas. Learn more about managing external datasets.

​
Create a data source

To upload a CSV, XLS, XLSX, or TSV file to create a reusable data source, make a POST request to /data-studio/data-source/2026-09-beta. 
curl --request POST \
  --url https://api.hubapi.com/data-studio/data-source/2026-09-beta \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'file=@sample-data.csv' \
  --form 'request={
  "datasourceName": "Sample Data",
  "datasourceType": "FILE",
  "config":{
    "file": {
    	 	"headerRowIndex": 1,
    		"columns": [
      		{
        			"name": "string",
        			"type": "STRING"
      		}
    				],
    	"sheetIndex": 0
  }
}
}'
When creating a data source, the following multipart/form-data parameters must be included in your request:
ParameterTypeRequiredDescription
fileFILEYesRequired for file data source type. The CSV, XLS, XLSX, or TSV file to upload. Maximum size: 512 MB. Only one file per request.
requestJSONYesConfiguration object describing the data source structure.
The request form parameter should be a JSON object that includes the following fields:
FieldTypeRequiredDescription
datasourceNamestringNoA custom name for the data source. It must be unique within the portal. For file data source type, if not provided, it defaults to the filename. If you need to create multiple data sources using the same file, use different datasourceName values in each request. When you delete a data source, its name is immediately released and can be reused.
datasourceTypestringYesThis currently only support FILE data source type.
configJSON objectYesThe configuration object describing the data source structure. Contents vary based on datasourceType.
Below is a description of the request body fields for the FILE data source type:
FieldTypeRequiredDescription
config.fileJSON objectYesThe file configuration details.
config.file.headerRowIndexintegerNoThe 1-based row index containing column headers. This defaults to 1.
config.file.sheetIndexintegerNoFor XLS and XLSX files, the zero-based index of the sheet to ingest. This defaults to 0, which refers to the first sheet in the file.
config.file.columnsarrayYesAn array of column definitions. At least one column is required.
config.file.columns[].namestringYesThe header name of the column. This cannot be blank or duplicated.
config.file.columns[].typestringYesThe data type of the column. Valid values include: STRING, BOOL, DATETIME, DATE, INTEGER, DECIMAL.
A response would look like this: 
{
  "datasourceId": 12354,
  "datasourceName": "Sample Data",
  "previewLink": "https://app.hubspot.com/data-studio-home/{accountId}/external-data-sources/[datasourceID]/preview"
}
Below is a description of the response body fields:
FieldTypeDescription
datasourceIdintegerThe unique identifier for the created data source. Use this ID to retrieve or delete the data source.
datasourceNamestringThe name assigned to the data source.
previewLinkstringA direct link to preview the data source in Data Studio.

​
Retrieve a data source

To get details about a data source, including ingestion status and file structure, make a GET request to /data-studio/data-source/2026-09-beta/{datasourceId}. When retrieving a data source, the following parameter must be met:
ParameterTypeRequiredDescription
datasourceIdstringYesThe unique identifier for the created data source. Use this ID to retrieve or delete the data source.
For example, the following request would retrieve a data source: 
curl --request GET \
  --url https://api.hubapi.com/data-studio/data-source/2026-09-beta/12354 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
A response would look like this: 
{
  "datasourceId": "12354",
  "datasourceName": "Sample Data",
  "lastIngestionStatus": "SUCCESSFUL",
  "createdAt": "2025-09-24T10:50:00.000Z",
  "datasourceType": "FILE",
  "columns": [
      {"name": "first_name", "type": "STRING"},
      {"name": "last_name", "type": "STRING"},
      {"name": "email", "type": "STRING"},
      {"name": "signup_date", "type": "DATE"}
    ]
}
Below is a description of the response body fields:
FieldTypeDescription
datasourceIdstringThe unique identifier for the created data source. Use this ID to retrieve or delete the data source.
datasourceNamestringThe name assigned to the data source.
datasourceTypestringThe type of data source.
lastIngestionStatusstringThe status of the most recent file ingestion. Values can include: SUCCESSFUL, FAILED, IN_PROGRESS.
createdAtstringThe timestamp when the data source was created.
columnsarrayAn array of column definitions matching the uploaded file structure.

​
Delete a data source

To delete a data source, make a DELETE request to /data-studio/data-source/2026-09-beta/{datasourceId}. A data source cannot be deleted if it’s actively used by datasets. When retrieving a data source, the following parameter must be met:
ParameterTypeRequiredDescription
datasourceIdstringYesThe unique identifier of the data source to delete.
You would receive a 204 No Content response on successful deletion with no response body. Status codes you could receive include:
CodeDescription
204The data source deleted successfully.
401Unauthorized. Missing or invalid access token.
403Forbidden. Insufficient permissions (missing required scope).
404The data source was not found.
409There was a conflict. The data source cannot be deleted because it’s in use by one or more datasets. You must remove the data source from all datasets before deleting.

​
Update a data source

To upload a new file to overwrite an existing data source in Data Studio, make a PUT request to /data-studio/data-source/2026-09-beta/{datasourceId}. Currently, only file-based data sources are supported for updates. When providing a new schema, it must include all existing fields in use, otherwise the request will be rejected. Any missing fields in the new schema are dropped. When updating a data source, you can provide the same parameters as when you create a data source. For example, the following request body would update a data source: 
{
 "datasourceName": "new-name",
  "config": {
    "file": {
      "headerRowIndex": 1,
      "columns": [
        {
          "name": "string",
          "type": "STRING"
        }
      ],
      "sheetIndex": 0
    }
  }
}
Below is a description of the request body fields:
FieldTypeRequiredDescription
configJSON objectNoThe configuration object describing the data source structure. If not provided, it defaults to the existing configuration.
Below is a description of the request body fields for the FILE data source type:
FieldTypeRequiredDescription
config.fileJSON objectNoThe file configuration details.
config.file.headerRowIndexintegerNoThe 1-based row index containing column headers. It defaults to 1.
config.file.sheetIndexintegerNoFor XLS and XLSX files, the zero-based index of the sheet to ingest. It defaults to 0, which refers to the first sheet in the file.
config.file.columnsarrayNoAn array of column definitions. At least one column is required.
config.file.columns[].namestringNoThe header name of the column. It cannot be blank or duplicated.
config.file.columns[].typestringNoThe data type of the column. Valid values include: STRING, BOOL, DATETIME, DATE, INTEGER, DECIMAL.
A response would look like this: 
{
  "datasourceId": "12354",
  "datasourceName": "datasourcename",
  "previewLink": "https://app.hubspotqa.com/data-studio-home/891585663/external-data-sources/apps/2147586523/preview"
}
Below is a description of the response body fields:
FieldTypeDescription
datasourceIdStringThe ID of the updated datasource
datasourceNameStringThe name assigned to the data source.
previewLinkStringThe link to the datasource preview.

​
Rate limits

Standard HubSpot API rate limits apply. For more information, see rate limits.
Last modified on March 18, 2026