Files

 

OverviewEndpoints

Use HubSpot’s files tool to manage and store files in HubSpot. Files hosted in HubSpot can be uploaded and used in both HubSpot and external content. They can also be attached to records using the engagements API.

If your company is building their website using HubSpot CMS, you can use the files API to upload and store assets in HubSpot, then serve it through the HubSpot CMS.

You can access the files tool from within HubSpot or by using the files API. Below, learn about the files API and how to upload and delete files. For a full list of files API endpoints, click the Endpoints tab above.

Changes in v3

If you’ve been using the previous version of this API, v3 has the following changes:

  • All files uploaded through the API will be visible in the files dashboard and the files picker. Hidden files cannot be created. However, private files and non-indexable files can still be created. 
  • Listing files will not return hidden or deleted files. However, a much broader range of filters can be applied. Hidden files can still be fetched by ID, but require a new scope: files_ui_hidden.read.
  • Multiple files cannot be uploaded with a single request. 
  • Folder update actions like moving and renaming are now asynchronous. Each request will return a token that can be used to check the status of the folder edit.
  • Endpoints that create or replace files require you to provide access levels for the files. These access levels are:
    • PUBLIC_INDEXABLE: file is publicly accessible by anyone who has the URL. Search engines can index the file.
    • PUBLIC_NOT_INDEXABLE: file is publicly accessible by anyone who has the URL. The X-Robots-Tag: noindex header will be sent whenever the file is retrieved, instructing search engines not to index the file.
    • PRIVATE: file is not publicly accessible. Requires a signed URL to display content. Search engines cannot index the file.
  • Endpoints that create files allow for a level of duplicate detections as part of the file’s upload options. 
    • ENTIRE_PORTAL: search for a duplicate file in the account.
    • EXACT_FOLDER: search for a duplicate file in the provided folder.
    • NONE: do not run any duplicate validation.
    • REJECT: reject the upload if a duplicate is found.
    • RETURN_EXISTING: if a duplicate file is found, do not upload a new file and return the found duplicate instead.
    • Duplicate detection works on a duplicateValidationScope, which affects how we search for a duplicate.
    • This also requires a duplicateValidationStrategy, which dictates what happens if a duplicate is found.

Upload a file

Files can be uploaded using a multipart/form-data POST request to files/v3/files with the following fields. While a specific folder ID is not required at upload, it's recommend to upload files into a folder and not the root directory. Folder requirements at upload are subject to change in the future. 

Use this table to describe parameters / fields
FieldRequiredDescription Example
file
Yes

The file to upload.

 "file": {binary data}
options
Yes

The file upload options. The only required field is the access field, which controls the file’s privacy and indexability.

If you're using the ttl field:

  • The minimum period that must be set is 1 day. 
  • The maximum period that can be set is 1 year. 
  • After the set period,  the file will be permanently deleted. After deletion, the file cannot be recovered or restored.

 "options": "{ "access":  "PRIVATE", "ttl": "P2W", "overwrite": false, "duplicateValidationStrategy": "NONE", "duplicateValidationScope": "EXACT_FOLDER" }"
folderId
No

The ID of the folder that the file will be uploaded to. folderId and folderPath cannot be set at the same time.

 "folderId": 1234
folderPath
No

The path of the folder that the file will be uploaded to. folderId and folderPath cannot be set at the same time.

 "folderPath": "/folder"
fileName
No

The name of the file. If no name is specified, a name will be generated from the file's content.

 "fileName": "myImage"
charsetHunch
No

Character set encoding for the uploaded file. If not provided, it will be derived from the file.

 "charsetHunch": "UTF-8"

Delete a file

To delete a file, make a DELETE request to files/v3/files/{fileId}. This will mark the file as deleted and make the content of the file inaccessible.

To permanently delete a file, make a DELETE request to files/v3/files/{fileId}/gdpr-delete. This will permanently delete the file’s content and metadata within 7 days. 

If a file is not GDPR deleted, its contents will remain on HubSpot's servers in a private state where no one can access it. To ensure file contents are fully deleted, use the GDPR delete functionality. 

View a file's details

To view the details of a file that's been uploaded to the files tool, make a GET request to files/v3/files/{fileId}. This will return the file with details such as name, height and width, encoding, the URL, and more.

If a file is set to private, the returned URL will result in a 404 error. To get a viewable URL of the file, you can make a GET request to /files/v3/files/{fileId}/signed-url. When making this request, you can include property parameters to return specific properties such as height and width.

Create a folder

To create a folder, make a POST request to files/v3/folders. When making the request, you can include the below fields. 

Use this table to describe parameters / fields
FieldRequiredDescription Example
name
Yes

Name of the folder you want to create.

 "name": "myFolder"
parentFolderId
No

To create the folder within an existing folder, include this field with the existing folder's ID. parentFolderId and parentFolderPath cannot be set at the same time.

 "parentFolderId": 1234
parentFolderPath
No

To create the folder within an existing folder, include this field with the existing folder's path. parentFolderId and parentFolderPath cannot be set at the same time.

 "folderId": 1234

Example request

JSON 
//example request
{
"name": "myNewFolder",
"parentFolderId": 12345
}
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.