API利用ガイドライン

HubSpotでは、全てのユーザーに安定した品質をお届けするために、公開APIの利用状況を詳しくモニタリングしています。アプリや連携の全ての開発に際し、HubSpot利用規定とAPIに関する利用条件を順守していただく必要があります。HubSpotはAPIを変更または廃止する権利を有するものとしますが、そのような場合は常に変更ログ（英語）を通じて事前に開発者の皆さまへお知らせします。

認証とセキュリティー

最適なセキュリティーを実現するために、全てのアプリにはHubSpotのOAuthプロトコルを直接お使いいただく必要があります。または、非公開アプリを開発する場合にはアプリのアクセストークンを使用します。アプリには、このプロトコルに準拠したTTL（time-to-live）データの保存とユーザー アクセス トークンのリフレッシュを実装いただく必要があります。アクセストークンの生成時には、リフレッシュまでのAPI呼び出しに使用できる期間を示すexpires_inパラメーターが含まれています。Unauthorized (401)（認証されていない）リクエストは、新しいアクセストークンを取得する必要性を示す指標とはなりません。

API利用状況の確認

非公開アプリとOAuthを使ったアプリ

非公開アプリまたは公開アプリの設定でAPI呼び出しのモニタリングを使用します。

APIキーによる連携

注：2022年11月30日をもってHubSpot APIキーは廃止され、サポートされなくなります。HubSpot APIキーの使用を続けると、アカウントやデータに対するセキュリティー上のリスクが生じます。HubSpotはこの廃止段階中にお客さまのキーを随時無効にする可能性があります。

認証には、代わりに非公開アプリのアクセストークンまたはOAuthを使用する必要があります。この変更の詳細（英語）と、非公開アプリを使用するようにAPIキーを移行する方法をご確認ください。

当日中のAPIリクエスト数や制限のリセット時期を確認するには、GETリクエストを/integrations/v1/limit/daily?hapikey=key_valueに送信します。ここで、key_valueはアカウントのHubSpot APIキーです。接続したアカウントのタイムゾーン設定に基づく深夜0時から深夜0時を「当日」と見なして測定されます。このエンドポイントへのリクエストは、1日のAPI制限に計上されます。

このエンドポイントから返されたデータは、5分間にわたりキャッシュに格納されます。キャッシュされたものかどうかを調べるには、レスポンスの中のfetchStatusフィールドとcollectedAtフィールドを確認します。

レスポンスの例：

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "SUCCESS", "resetsAt": 1560204000000 } ]

resetsAtフィールドは、制限がリセットされる時刻のUnixタイムスタンプ（ミリ秒単位）です。制限は、アカウントのタイムゾーン設定に基づいて深夜0時にリセットされます。

キャッシュレスポンスの例：

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "CACHED", "resetsAt": 1560204000000 } ]

キャッシュからのレスポンスの場合、fetchStatusはCACHEDで、collectedAtはキャッシュ最終更新時を示すUnixタイムスタンプ（ミリ秒単位）です。

レート制限

OAuthを使ったアプリ

OAuthを使ったアプリには、10秒当たり100回のリクエスト制限のみが適用されます（検索APIを除く。下記の「その他の制限」を参照）。API追加オプションに関連する制限は適用されません。

非公開アプリ

各非公開アプリには、HubSpotのAPI利用ガイドラインが適用されます。非公開アプリから実行できる呼び出しの回数は、アカウントのご契約内容とAPI追加オプションのご購入状況に基づきます。

  製品のエディション 10秒当たり 1日当たり
非公開アプリ

（全ての製品の）

無料ツール、Starter

 非公開アプリ1件につき100回 アカウント1件につき250,000回
 

（全ての製品の）

Professional、Enterprise

 非公開アプリ1件につき150回 アカウント1件につき500,000回
非公開アプリ（API追加オプション購入時）

（全ての製品の）

無料ツール、Starter、Professional、Enterprise

 非公開アプリ1件につき200回 アカウント1件につき1,000,000回

 

エラーレスポンス

アプリまたは連携でレート制限を超えると、以降の全てのAPI呼び出しに対し、429のエラーレスポンスを受け取ることになります。エラーレスポンスが返されるリクエストの数が、1日の合計リクエスト数の5％を超えないようにしてください。アプリマーケットプレイスへのアプリの掲載を予定している場合、この5％の制限を守っていただく必要があります。 

429レスポンスの形式を以下に示します。 

//Example { "status": "error", "message": "You have reached your daily limit.", "errorType": "RATE_LIMIT", "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24", "policyName": "DAILY", "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd" }

messageとpolicyNameは、どちらの上限に達したかを示します（日次制限または2次制限）。

1日当たりの制限は、タイムゾーン設定に基づいて深夜0時にリセットされます。

各APIリクエストのレスポンスには、以下のレート制限ヘッダーが含まれます。注：OAuthで認証されたリクエストには、DailyおよびDaily-Remainingヘッダーは含まれません。

ヘッダー 説明
X-HubSpot-RateLimit-Daily 1日当たりに実行可能なAPIリクエストの数。
X-HubSpot-RateLimit-Daily-Remaining 当日に実行可能な残りのAPIリクエストの数。
X-HubSpot-RateLimit-Interval-Milliseconds X-HubSpot-RateLimit-MaxヘッダーとX-HubSpot-RateLimit-Remainingヘッダーが適用される時間。

例えば、値が10000なら10秒間を表します。
X-HubSpot-RateLimit-Max X-HubSpot-RateLimit-Interval-Millisecondsで指定された時間内で実行可能なリクエストの数。

例えば、このヘッダー値が100で、X-HubSpot-RateLimit-Interval-Millisecondsヘッダーが10000の場合、リクエストの回数は10秒当たり100回に制限されます。
X-HubSpot-RateLimit-Remaining  X-HubSpot-RateLimit-Interval-Millisecondsで指定された時間内で実行可能な残りのAPIリクエストの数。

注：X-HubSpot-RateLimit-SecondlyヘッダーとX-HubSpot-RateLimit-Secondly-Remainingヘッダーはまだ含まれています。データ自体は正確ですが、この2つのヘッダーで参照されている制限は既に適用されているため、これらのヘッダーも廃止されたものとお考えください。

こちらのエンドポイントを使って、当日中に使用された呼び出し数を確認することもできます。

TEN_SECONDLY_ROLLINGの制限に到達した場合は、アプリで発行するリクエストをスロットリングして制限内に収めてください。リクエストのスロットリングと組み合わせる対策、または1日当たりの制限に達する場合の対策について、以下を参照してください。

これらの方法を検討しても呼び出し制限に到達する場合は、開発者フォーラム（英語）でお知らせください。その際には、ご使用のAPIや、その利用状況、到達した制限など、できるだけ詳しい情報をご提供いただきますようお願いいたします。

繰り返し呼び出すデータをキャッシュする

サイトまたはアプリの各ページの読み込み時にHubSpotからのデータを使用する場合は、HubSpot APIで毎回リクエストするのではなく、データのキャッシュ処理によってキャッシュからデータを読み込むようにしてください。一括処理のためにアカウント設定を取得する呼び出しを繰り返し行う場合（オブジェクトのプロパティー、担当者、またはフォーム設定を取得するなど）、こうした設定情報についても可能な限りキャッシュ処理を行ってください。

可能な限り一括APIを使用する

時間の影響を受けにくいデータを扱う場合は、データを1つずつ処理するよりも、複数の更新処理を定期的な一括処理としてまとめるほうが効果的です。 

CRMオブジェクト（コンタクト、会社、取引など）を扱う場合、さまざまな一括処理のメソッドを利用できます。

Webhookを使用してHubSpotから最新データを取得する

HubSpotのMarketing Hub Enterpriseをご契約されている場合、ワークフロー内でWebhookアクションを使用してコンタクトレコードのデータを貴社のシステムに送信できます。Webhookは、どのワークフローのアクションとしてもトリガーできるため、コンタクトデータを貴社のシステムに送信するための条件として、どのようなワークフローの開始条件でも使用できます。Webhookの詳しい使い方については、こちらを参照してください。また、Webhookデータの例についてはこちら（英語）をご覧ください。ワークフローを介して行われたWebhook呼び出しは、APIレート制限には計上されません。

 

サービスの制限

HubSpotのサービスの制限と価格については、こちらをご覧ください。

その他の制限

  • 開発者アカウント1件につき最大100件のアプリを作成可能
  • HubSpotアカウント1件につき最大20件の非公開アプリを作成可能
  • アプリ1件につき1,000件までのWebhookサブスクリプションを作成可能
  • アプリ1件につき最大25個のCRM拡張機能を作成可能
  • アプリ1件につき最大750個のタイムライン イベント タイプを作成可能
  • タイムライン イベント タイプ1個につき最大500個のプロパティーを作成可能
  • 検索APIエンドポイントのレート制限：認証トークン1つにつき1秒当たり最大4件のリクエスト

関連ドキュメント

アプリ内でのAPI利用状況の確認