最終更新日: 2025年8月22日
HubSpot内でファイルを管理および保存するには、HubSpotのファイルツールを使用します。HubSpotでホスティングされているファイルは、HubSpotでも外部コンテンツでもアップロードして使用することが可能です。エンゲージメントAPIを使用して、ファイルをレコードに添付することもできます。 HubSpotのCMSを使用してウェブサイトが構築されている場合、ファイルAPIを使用してアセットをHubSpotにアップロードして保存できます。これらのファイルは、HubSpotのCMSを介して提供および共有することができます。 ファイルツールはHubSpot内で、またはファイルAPI経由で利用できます。以下に、ファイルAPIの概要、およびファイルのアップロードと削除の方法について説明します。ファイルAPIエンドポイントの完全なリストについては、 リファレンスドキュメントを確認してください。

​
ファイルをアップロードする

ファイルをアップロードするには、以下のフィールドを指定したmultipart/form-dataPOSTリクエストをfiles/v3/filesに送信します。アップロード時に特定のフォルダーIDは必須ではありませんが、ファイルのアップロード先はルートディレクトリーではなくフォルダーにすることをお勧めします。アップロード時のフォルダーの必要性に関しては、今後変更される可能性がありますのでご留意ください。
フィールド説明
fileアップロードするファイル（必須）。
optionsファイルの公開設定とインデックス登録を制御するJSONオブジェクトで、次の2つのフィールドが含まれています。1つは必須のaccessで、もう1つはファイルが自動的に削除されるまでの期間を指定するttlです。ttlフィールドを使用する場合の条件は、次の通りです。
  • 設定する必要がある最小期間は1日です。
  • 設定できる最大期間は1年です。
  • 設定した期間が経過すると、ファイルは完全に削除されます。削除された後、ファイルを回復または復元することはできません。

folderIdファイルのアップロード先とするフォルダーのID。リクエストには、このフィールドまたはfolderPathのいずれかを指定する必要があります（両方を指定することはできません）。
folderPathファイルのアップロード先とするフォルダーのパス。リクエストには、このフィールド またはfolderIdのいずれかを指定する必要があります（両方を指定することはできません）。
fileNameファイルの名前。名前が指定されていない場合は、ファイルの内容に基づく名前が生成されます。
charsetHunchアップロードするファイルのエンコーディングに使用されている文字セット。指定されていない場合、ファイルから取得されます。
例えば、次の条件を満たすファイルをHubSpotアカウントにアップロードする場合：
  • ファイル名：cat.png
  • HubSpotファイルマネージャー内の移動先フォルダー: /library/cat_archive
  • HubSpotでのファイルのアクセシビリティー: 非公開でアクセス可能
次のヘッダーとリクエスト本文が、リクエストに含まれている必要があります。 
curl --request POST \
  --url 'https://api.hubapi.com/files/v3/files?=' \
  --header 'Authorization: Bearer pat-na1-00000000-0000-0000-0000-000000000000' \
  --header 'Content-type: multipart/form-data' \
  --form file=@/Users/person/Downloads/cat.png \
  --form 'options={"access": "PRIVATE"}' \
  --form folderPath=/library/cat_archive
生成されるレスポンスには、アップロードされたファイルのidとparentFolderIdが含まれます。これを使用して、GETリクエスト経由でファイルを取得できます。 
// 201 Response from successful file upload
{
  "id": "122692044085",
  "createdAt": "2023-06-28T17:56:45.393Z",
  "updatedAt": "2023-06-28T17:56:45.393Z",
  "archived": false,
  "parentFolderId": "122692510820",
  "name": "cat",
  "path": "/library/cat_archive/cat.png",
  "size": 24574,
  "height": 219,
  "width": 225,
  "encoding": "png",
  "type": "IMG",
  "extension": "png",
  "defaultHostingUrl": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "url": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png",
  "isUsableInContent": true,
  "access": "PRIVATE"
}

​
ファイルのアップロードステータスを確認する

files/v3/files/import-from-url/asyncへのPOSTリクエストを使用してファイルをURLからファイルマネージャーにインポートする際には、ファイルのアップロードステータスを確認することができます。 確認を行うには、files/v3/files/import-from-url/async/tasks/{taskId}/statusへGETリクエストを使用します。 このリクエストを送信すると、次のいずれかの返信が送られます。
  • PENDING：ファイルはアップロード待ちのキューにあります。インポート処理はまだ開始されていません。
  • PROCESSING：ファイルはアップロード中です。
  • CANCELED：アップロードはキャンセルされ、ファイルはアップロードされません。ファイルをHubSpotアカウントにインポートするには、ファイルを再度アップロードする必要があります。
  • COMPLETE：ファイルがファイルツールに正常にアップロードされました。アップロードされたファイルがファイルツールに表示されます。

​
ファイルの詳細を表示する

ファイルツールにアップロードされたファイルの詳細を確認するには、GETリクエストをfiles/v3/files/{fileId}に送信します。これにより、名前、高さと幅、エンコード、URLなどの詳細情報と共にファイルが返されます。 ファイルの詳細の例として、以下の方法を参照してください。 ファイルが非公開に設定されている場合、返されるURLは404エラーになります。表示可能なファイルのURLを取得するには、GETリクエストを/files/v3/files/{fileId}/signed-urlに送信します。このリクエストを送信するときに、高さと幅などの特定のプロパティーが返されるようにpropertyパラメーターを含めることができます。

​
ファイルを削除する

ファイルを削除するには、DELETEリクエストをfiles/v3/files/{fileId}に送信します。これにより、ファイルは削除済みになり、ファイルの内容にアクセスできなくなります。 ファイルを完全に削除するには、DELETEリクエストをfiles/v3/files/{fileId}/gdpr-deleteに送信します。これにより、ファイルの内容とメタデータが7日以内に完全に削除されます。 GDPR削除が行われていない場合、ファイルの内容は、誰もアクセスできない非公開の状態でHubSpotのサーバーに残ります。ファイルの内容を完全に削除するには、GDPR削除機能を使用します。

​
フォルダーを作成する

フォルダーを作成するには、POSTリクエストをfiles/v3/foldersに送信します。このリクエストには、以下のフィールドを含めることができます。
フィールド必須説明
nameはい作成するフォルダーの名前。
parentFolderIdいいえ既存のフォルダー内にフォルダーを作成するには、既存フォルダーのIDを指定したこのフィールドを含めます。parentFolderIdとparentFolderPath同時に設定することはできません。
parentFolderPathいいえ既存のフォルダー内にフォルダーを作成するには、既存フォルダーのパスを指定したこのフィールドを含めます。parentFolderIdとparentFolderPathを同時に設定することはできません。
//Example request body of POST request to /files/v3/folders
{
  "name": "myNewFolder",
  "parentFolderId": 12345
}

​
V3における変更点

ファイルAPIの旧バージョンを使用している場合、v3には次の変更点があります。
  • このAPI経由でアップロードした全てのファイルは、ファイルダッシュボードおよびファイル選択時に表示されるようになりました。非表示ファイルを作成することはできません。ただし、非公開ファイルとインデックス登録不可のファイルは引き続き作成できます。
  • ファイルのリストでは、非表示のファイルや削除済みのファイルが返されなくなりました。ただし、適用できるフィルターの種類が大幅に増えました。非表示のファイルは引き続きIDを指定して取得できますが、その場合は新しいスコープfiles_ui_hidden.read.が必要になります。
  • 1回のリクエストで複数のファイルをアップロードすることはできなくなりました。
  • 移動や名前変更などのフォルダー更新アクションは非同期になりました。リクエストごとに、フォルダーの編集ステータスの確認に使用できるトークンが返されます。
  • ファイルを作成または置換するエンドポイントを使用するには、ファイルのアクセスレベルを指定することが必要になりました。アクセスレベルは以下の通りです。
    • PUBLIC_INDEXABLE: ファイルが一般に公開され、URLを知っている全員がアクセスできます。このファイルは、検索エンジンによるインデックス登録が可能です。
    • PUBLIC_NOT_INDEXABLE: ファイルが一般に公開され、URLを知っている全員がアクセスできます。ファイルの取得時には常に「X-Robots-Tag: noindex」ヘッダーが送信され、検索エンジンに対し、ファイルをインデックス登録しないよう通知されます。
    • PRIVATE: ファイルは一般に公開されません。コンテンツを表示するには署名付きURLが必要です。検索エンジンはこのファイルのインデックス登録を行うことができません。
  • ファイルを作成するエンドポイントでは、ファイルのアップロードオプションの一部として、重複検出レベルを指定できます。
    • ENTIRE_PORTAL: アカウント内で重複するファイルを検索します。
    • EXACT_FOLDER: 指定されたフォルダー内で重複するファイルを検索します。
    • NONE: 重複の検証を実行しません。
    • REJECT: 重複が見つかった場合はアップロードを拒否します。
    • RETURN_EXISTING: 重複したファイルが見つかった場合は、新しいファイルをアップロードせずに、見つかった重複ファイルを返します。
    • 重複検出はduplicateValidationScopeを基に機能するため、重複の検索にも影響します。
    • 重複が検出された場合の処理を指示するduplicateValidationStrategyも必要です。