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:
ParameterTypeDescription
file FileRequired for file data source type. The CSV, XLS, XLSX, or TSV file to upload. Maximum size: 512 MB. Only one file per request.
request JSON objectConfiguration object describing the data source structure.
The request form parameter should be a JSON object that includes the following fields:
FieldTypeDescription
datasourceNameStringA 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.
datasourceType StringThis currently only support FILE data source type.
config JSON objectThe 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:
FieldTypeDescription
config.file JSON objectThe file configuration details.
config.file.headerRowIndexIntegerThe 1-based row index containing column headers. This defaults to 1.
config.file.sheetIndexIntegerFor 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.columns ArrayAn array of column definitions. At least one column is required.
config.file.columns[].name StringThe header name of the column. This cannot be blank or duplicated.
config.file.columns[].type StringThe 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/12345678/external-data-sources/[datasourceID]/preview"
}
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.
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}, providing the ID of the data source as the datasourceId path parameter. 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}, providing the ID of the data source as the datasourceId path parameter. A data source cannot be deleted if it’s actively used by datasets. You’ll 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}, providing the ID of the data source as the datasourceId path parameter. 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:
FieldTypeDescription
configJSON objectThe 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 config object when updating a FILE data source type, which is the only currently supported type:
FieldTypeDescription
config.fileJSON objectThe file configuration details.
config.file.headerRowIndexIntegerThe 1-based row index containing column headers. It defaults to 1.
config.file.sheetIndexIntegerFor 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.columnsArrayAn array of column definitions. At least one column is required.
config.file.columns[].nameStringThe header name of the column. It cannot be blank or duplicated.
config.file.columns[].typeStringThe data type of the column. Valid values include: STRING, BOOL, DATETIME, DATE, INTEGER, DECIMAL.
A successful response will resemble the following: 
{
  "datasourceId": "12354",
  "datasourceName": "datasourcename",
  "previewLink": "https://app.hubspot.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. Learn more about rate limits.
Last modified on March 30, 2026