HUhubspot
Files

Import File

Changed on

Import a file asynchronously from a specified URL into the HubSpot file manager. This endpoint allows you to specify various parameters such as access level, duplicate validation strategy, and whether to overwrite existing files. The operation is processed asynchronously, and a task locator is returned to check the status of the import.

post/files/2026-09/files/import-from-url/async

Request

  • Base URL
    https://api.hubapi.com
  • URL
    https://api.hubapi.com/files/2026-09/files/import-from-url/async
  • Auth
    OAuth 2
    Authorization code: https://app.hubspot.com/oauth/authorize
    Token URL: https://api.hubapi.com/oauth/v1/token scopes: files.ui_hidden.write

Request body

access'HIDDEN_INDEXABLE' | 'HIDDEN_NOT_INDEXABLE' | 'HIDDEN_PRIVATE' | 'HIDDEN_SENSITIVE' | 'PRIVATE' | 'PUBLIC_INDEXABLE' | 'PUBLIC_NOT_INDEXABLE' | 'SENSITIVE' required

Specifies the access level of the file. Valid values include 'PUBLIC_INDEXABLE', 'PUBLIC_NOT_INDEXABLE', 'HIDDEN_INDEXABLE', 'HIDDEN_NOT_INDEXABLE', 'HIDDEN_PRIVATE', 'PRIVATE', 'HIDDEN_SENSITIVE', and 'SENSITIVE'.

duplicateValidationScope'ENTIRE_PORTAL' | 'EXACT_FOLDER' required

Optional: Specifies the scope for duplicate validation. Valid values include 'ENTIRE_PORTAL' and 'EXACT_FOLDER'.

duplicateValidationStrategy'NONE' | 'REJECT' | 'RETURN_EXISTING' required

Defines the strategy for handling duplicate files. Valid values are 'NONE', 'REJECT', and 'RETURN_EXISTING'.

expiresAtstring date-time

Optional: Epoch time when the file will expire, in ISO 8601 format. Do not set if the file should live indefinitely

folderIdstring

The ID of the folder where the file will be stored. This or folderPath must be set

folderPathstring

The path of the folder where the file will be stored. This or FolderId must be set.

namestring

The name of the file to be imported.

overwriteboolean required

Optional boolean indicating whether to overwrite an existing file at the same location.

ttlstring

Deprecated Do Not use. Optional: String representing the time-to-live for the file, same a expiresAt but takes a Period String.

urlstring

The URL from which the file will be imported.

Example request

{
  "folderPath": "\"/destinationPath/folder\""
}

Response

accepted

idstring required

The ID of the import task.

linksobject

A map of link names to associated URIs related to the import task. Each entry in the map is a string.

Changes

  • 2026-09551d24894509Revision changes
    • info

      api tag Files added

    • info

      api tag Advanced removed

  • 2026-096e0d1e97cb30Revision changes
    • info

      the security scope files.ui_hidden.write was added to the endpoint's security scheme oauth2

    • info

      the security scope files.write was removed from the endpoint's security scheme oauth2