Files


 

Just as the name says, HubSpot’s files tool is a system for managing and storing files. Whether you’re here to learn how the HubSpot files tool works or getting ready to integrate it with another system, you’re in the right place. The files API allows you to create files and folders programmatically. Keep reading for a breakdown of what you can do with the files API.

Example use case: Your organization is building their website on the HubSpot CMS. Your developers can use the files api to upload content into hubspot and serve it using the Hubspot CMS. 

Example use case with contact attachments: You organization wants to audit or delete contact attachments. You can use the contacts API to gather any attached file ids and use the files API to retrieve the file metadata and file contents. Note that attachments may be hidden and will require the “files.ui_hidden.read” scope to access.

Changes in V3

If you’ve been using the previous version of this API, v3 has a few changes.

  • You can’t create hidden files. All files uploaded through the API will be visible in the files dashboard and the files picker. Private files and non-indexable files can still be created. 
  • Endpoints that create or replace files require you to provide access levels for the files. These access levels are as follows:
    • 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 see content. Search engines can't index the file.
  • Endpoints that create files will allow for a level of duplicate detections as part of the file’s upload options. 
    • ENTIRE_PORTAL: Look for a duplicate file in the entire account.
    • EXACT_FOLDER: Look 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.
    • It also takes a duplicateValidationStrategy, which dictates what happens if a duplicate is found.
  • Listing files will no longer 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 can no longer 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.

     


Uploading a file:

Files can be uploaded using a multipart/form-data POST request to “files/v3/files” with the following fields. We recommend uploading files into a folder and not the root directory. While a folder is not currently required, this is subject to change in the future. 

Field

Required?

How to use

Description 

file

yes


file”: {binary data}


The file

folderId


no


“folderId”: 1234


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

folderPath no

“folderPath”: “/folder”



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

fileName no “fileName”: “myImage”

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


charsetHunch
no
“charsetHunch”: “UTF-8”

Character set encoding for the uploaded file. If not provided, it will be derived from the file.
options yes
“options”: “{
  "access":  "PRIVATE",
"ttl": "P2W",
"overwrite": false,
"duplicateValidationStrategy": "NONE",
"duplicateValidationScope": "EXACT_FOLDER"
}


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



Deleting 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, it’s contents will remain on our servers in a private state. No one will be able to access them. To ensure file contents are fully deleted, use the gdpr delete functionality. 

 

Creating a folder

To create a folder, make a POST request to “files/v3/folders”.

Fields

Required

How to use 

Description

name

yes



“name”: “myFolder”


Name of the folder you want to create.

parentFolderId

no


“parentFolderId”: 1234


The ID of the parent folder for the new folder you’re creating. parentFolderId and parentFolderPath cannot be set at the same time.

parnetFolderPath

no


“parentFolderPath”: “/folder/otherFolder”


The path of the parent folder for the folder you’re creating. parentFolderId and parentFolderPath cannot be set at the same time.

 

 

 

 


Example request

JSON
//example request
{
"name": "myNewFolder",
"parentFolderId": 12345
}

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.