Data source ingestion API

Scope requirements

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 create a data source, follow the instructions in the sections below based on whether you’re uploading JSON or another file format (including CSV, XLS, XLSX, or TSV).

Upload JSON data

To upload JSON as a data source, ensure you’ve authorized the data_integration.data_source.json.write scope for your app, then make a POST request to /data-studio/data-source/2026-09-beta/json. The code block below demonstrates an example cURL request:

curl --request POST \
  --url https://api.hubapi.com/data-studio/data-source/2026-09-beta/json \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "datasourceName": "Sample Data",
  "config": {
    "json": {
      "columns": [
        {"name": "id", "type": "INTEGER"},
        {"name": "first_name", "type": "STRING"},
        {"name": "signup_date", "type": "DATE"}
      ],
      "recordId": "id",
      "data": [
        {"id": 1, "first_name": "Alice", "signup_date": "2025-01-01"},
        {"id": 2, "first_name": "Bob", "signup_date": "2025-01-02"}
      ]
    }
  }
}'

When creating a data source from JSON data, the following parameters must be included in your request:

Parameter	Type	Description
`datasourceName`	String	A custom name for the data source, which must be unique in your HubSpot account. When you delete a data source, its name can be reused.
`config`	JSON object	A configuration object describing the structure of the data source, detailed in the table below.

The properties of the config parameter are detailed below:

Property	Type	Description
`config.json`	JSON object	The top-level container property of your JSON data source.
`config.json.columns`	Array	An array of column definitions. A minimum of one column definition is required, with a maximum of 200 columns. Each definition must include the following two fields: `name`: The column name. This name cannot be blank and must be unique. `type`: The data type of the column. Valid values are: `STRING`, `BOOL`, `DATETIME`, `DATE`, `INTEGER`, or `DECIMAL`.
`config.json.recordId`	String	The name of the column to use as a unique record identifier. Must be either `STRING` or `INTEGER`. If specified, this field must be present on every record.
`config.json.data`	Array	An array of records to load into the updated data source. A maximum of 100,000 records is allowed. Each record must be a flat object: nested objects or arrays are not supported.

A successful response resembles the following:

{
  "datasourceId": "12354",
  "datasourceName": "Sample Data",
  "previewLink": "https://app.hubspot.com/data-studio-home/891585663/external-data-sources/12354/preview"
}

The table below provides more details on each of the response fields:

Field	Type	Description
`datasourceId`	String	The ID of the new data source.
`datasourceName`	String	The name assigned to the new data source.
`previewLink`	String	A URL link to a preview of the data source in your HubSpot account.

Upload a CSV, XLS, XLSX, or TSV file

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:

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:

{
  "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:

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:

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.

Push JSON data to an existing data source

To add records to an existing JSON data source without replacing its schema, make a POST request to /data-studio/data-source/2026-09-beta/{datasourceId}/data-push, providing the ID of the data source as the datasourceId path parameter. If a recordId was specified when creating or updating the data source, records with a matching ID will be updated. Records with no matching ID will be appended. If no recordId is configured, all records are appended. The code block below demonstrates an example cURL request to append two new records to an existing JSON-based data source:

curl --request POST \
  --url https://api.hubapi.com/data-studio/data-source/2026-09-beta/12354/data-push \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": [
    {"id": 3, "first_name": "Carol", "signup_date": "2025-01-03"},
    {"id": 4, "first_name": "Dave", "signup_date": "2025-01-04"}
  ]
}'

The one required request body field, data, is detailed below:

Field	Type	Description
`data`	Array	An array of records to load into the updated data source. A maximum of 100,000 records is allowed. Each record must be a flat object: nested objects or arrays are not supported.

Update the schema for an existing data source

To update the schema or upload additional data to an existing data source, consult the sections below based on the format of the data source you created (i.e., JSON data or an uploaded file).

Update an existing JSON-based data source

To replace the schema and optionally load new data into an existing JSON data source, make a PUT request to /data-studio/data-source/2026-09-beta/{datasourceId}/json, providing the ID of the data source as the datasourceId path parameter. When providing a new schema, it must include all existing columns in use, otherwise the request will be rejected. Any columns not included in the new schema are dropped. The code block below demonstrates an example request body to update a JSON-based data source:

{
  "datasourceName": "updated-name",
  "config": {
    "json": {
      "columns": [
        {"name": "id", "type": "INTEGER"},
        {"name": "first_name", "type": "STRING"},
        {"name": "signup_date", "type": "DATE"},
        {"name": "country", "type": "STRING"}
      ],
      "recordId": "id",
      "data": [
        {"id": 1, "first_name": "Alice", "signup_date": "2025-01-01", "country": "US"}
      ]
    }
  }
}

The request body should include the following parameters:

Parameter	Type	Description
`datasourceName`	String	A new name for the existing data source. If this parameter isn’t provided, the existing name will be used.
`config`	JSON object	A configuration object describing the updated structure of the data source. The available properties are detailed in the table above.

Update an existing file-based data source

To upload a new file to overwrite an existing file-based 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. 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:

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:

{
  "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.

Rename an existing data source

To rename a data source, make a PATCH request to /data-studio/data-source/2026-09-beta/{datasourceId}, providing the ID of the data source as the datasourceId path parameter, and the datasourceName field in the request body with the new name for the data source. The new data source name cannot be blank and must be unique. This endpoint is supported for both JSON and file based data sources, but you’ll need to ensure you’ve authorized the corresponding data_integration.data_source.json.write scope or data_integration.data_source.file.write scope based on the format of the existing data source. The code block below demonstrates an example cURL request to rename an existing data source with an ID of 12354:

curl --request PATCH \
  --url https://api.hubapi.com/data-studio/data-source/2026-09-beta/12354 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "datasourceName": "new-name"
}'

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.

Rate limits

Standard HubSpot API rate limits apply. Learn more about rate limits.

​Create a data source

​Upload JSON data

​Upload a CSV, XLS, XLSX, or TSV file

​Retrieve a data source

​Push JSON data to an existing data source

​Update the schema for an existing data source

​Update an existing JSON-based data source

​Update an existing file-based data source

​Rename an existing data source

​Delete a data source

​Rate limits

Create a data source

Upload JSON data

Upload a CSV, XLS, XLSX, or TSV file

Retrieve a data source

Push JSON data to an existing data source

Update the schema for an existing data source

Update an existing JSON-based data source

Update an existing file-based data source

Rename an existing data source

Delete a data source

Rate limits