> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: b4888d64-a1dd-44cc-8c35-ee4b82026701
---
# File Ingestion API
> Upload tabular files directly into HubSpot Data Studio as independent datasets.
export const BetaDisclaimerBanner = () =>
This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.
;
export const RequiredIndicator = () => {
return
required
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
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](https://knowledge.hubspot.com/data-management/build-and-activate-datasets-in-data-studio-management/build-and-activate-datasets-in-data-studio).
## 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`.
```shell theme={null}
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:
| Parameter | Type | Description |
| ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `file` | File | Required 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 object | Configuration object describing the data source structure. |
The `request` form parameter should be a JSON object that includes the following fields:
| Field | Type | Description |
| -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datasourceName` | String | A 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` | String | This currently only support `FILE` data source type. |
| `config` | JSON object | The 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:
| Field | Type | Description |
| -------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `config.file` | JSON object | The file configuration details. |
| `config.file.headerRowIndex` | Integer | The 1-based row index containing column headers. This defaults to 1. |
| `config.file.sheetIndex` | Integer | For 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` | Array | An array of column definitions. At least one column is required. |
| `config.file.columns[].name` | String | The header name of the column. This cannot be blank or duplicated. |
| `config.file.columns[].type` | String | The data type of the column. Valid values include: `STRING`, `BOOL`, `DATETIME`, `DATE`, `INTEGER`, `DECIMAL`. |
A response would look like this:
```json theme={null}
{
"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:
| Field | Type | Description |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `datasourceId` | String | The unique identifier for the created data source. Use this ID to retrieve or delete the data source. |
| `datasourceName` | String | The name assigned to the data source. |
| `previewLink` | String | A 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:
```shell theme={null}
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:
```json theme={null}
{
"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:
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `datasourceId` | String | The unique identifier for the created data source. Use this ID to retrieve or delete the data source. |
| `datasourceName` | String | The name assigned to the data source. |
| `datasourceType` | String | The type of data source. |
| `lastIngestionStatus` | String | The status of the most recent file ingestion. Values can include: `SUCCESSFUL`, `FAILED`, `IN_PROGRESS`. |
| `createdAt` | String | The timestamp when the data source was created. |
| `columns` | Array | An 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:
| Code | Description |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `204` | The data source deleted successfully. |
| `401` | Unauthorized. Missing or invalid access token. |
| `403` | Forbidden. Insufficient permissions (missing required scope). |
| `404` | The data source was not found. |
| `409` | There 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](#create-a-data-source) as when you create a data source.
For example, the following request body would update a data source:
```json theme={null}
{
"datasourceName": "new-name",
"config": {
"file": {
"headerRowIndex": 1,
"columns": [
{
"name": "string",
"type": "STRING"
}
],
"sheetIndex": 0
}
}
}
```
Below is a description of the request body fields:
| Field | Type | Description |
| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `config` | JSON object | The 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:
| Field | Type | Description |
| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `config.file` | JSON object | The file configuration details. |
| `config.file.headerRowIndex` | Integer | The 1-based row index containing column headers. It defaults to 1. |
| `config.file.sheetIndex` | Integer | For 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.columns` | Array | An array of column definitions. At least one column is required. |
| `config.file.columns[].name` | String | The header name of the column. It cannot be blank or duplicated. |
| `config.file.columns[].type` | String | The data type of the column. Valid values include: `STRING`, `BOOL`, `DATETIME`, `DATE`, `INTEGER`, `DECIMAL`. |
A successful response will resemble the following:
```JSON theme={null}
{
"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:
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------- |
| `datasourceId` | String | The ID of the updated datasource. |
| `datasourceName` | String | The name assigned to the data source. |
| `previewLink` | String | The link to the datasource preview. |
## Rate limits
Standard HubSpot API rate limits apply. Learn more about [rate limits](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#rate-limits).