API利用ガイドライン
HubSpotでは、全てのユーザーに安定した品質をお届けするために、公開APIの利用状況を詳しくモニタリングしています。アプリや連携の全ての開発に際し、HubSpot利用規定とAPIに関する利用条件(英語)に従っていただく必要があります。HubSpotはAPIの変更や廃止の権利を有するものとしますが、そのような場合は常に変更ログ(英語)を通じて事前に開発者の皆さまへお知らせします。
認証とセキュリティー
最適なセキュリティーを実現するために、全てのアプリにはHubSpotのOAuthプロトコルを直接お使いいただく必要があります。または、非公開アプリを開発する場合にはアプリのアクセストークンを使用します。このプロトコルに準拠したTTL(time-to-live)データの保存と、ユーザー アクセス トークンのリフレッシュは、アプリ側で責任を持って実装いただくことになります。アクセストークンの生成時には、リフレッシュまでのAPI呼び出しに使用できる期間を示すexpires_in
パラメーターが含まれています。Unauthorized (401)
(認証されていない)リクエストは、新しいアクセストークンを取得する必要性を示す指標とはなりません。
非公開アプリとOAuthを使ったアプリ
アプリの設定でAPI呼び出しのモニタリングを使用します。
APIキーによる連携
※2022年11月30日以降、HubSpot APIキーをHubSpot APIにアクセスするための認証方法として使用することはできなくなります。また、2022年7月15日以降、HubSpot APIキーが未生成のアカウントでAPIキーを作成することはできなくなります。
その代わりとして、非公開アプリのアクセストークンまたはOAuthを使用して、API呼び出しの認証を行っていただく必要があります。詳しくは、この変更(英語)の詳細、および非公開アプリを使用するためにAPIキーを移行する方法をご確認ください。
GET /integrations/v1/limit/daily
*により、現在日のAPI呼び出し数や制限リセット時期を確認します。「現在日」は、接続したアカウントのタイムゾーン設定に基づく深夜0時から深夜0時を1日として測定されます。
*1日のAPI制限に対する、このエンドポイントへの呼び出しのカウント。
必須パラメーター | 説明 | 使い方 |
HubSpot APIキー | API利用状況の確認対象とするHubSpotアカウントのAPIキー。 | URLでhapikey= を使用 |
GET
URLの例:
https://api.hubapi.com/integrations/v1/limit/daily?hapikey=demo
このエンドポイントから返されたデータは、5分間キャッシュに格納されます。キャッシュされたものかどうかを調べるには、レスポンスの中のfetchStatus
フィールドとcollectedAt
フィールドを確認します。
レスポンスの例:
resetsAt
フィールドは、制限がリセットされる時刻のUnixタイムスタンプ(ミリ秒単位)です。制限は、アカウントのタイムゾーン設定に基づいて深夜0時にリセットされます。
キャッシュレスポンスの例:
キャッシュからのレスポンスの場合、fetchStatus
はCACHED
で、collectedAt
はキャッシュ最終更新時を示すUnixタイムスタンプ(ミリ秒単位)です。
OAuthを使ったアプリ
OAuthを使ったアプリに対して適用できる制限は、10秒あたり100回のリクエストのみです(検索APIを除く。下記の「その他の制限」を参照)。API追加オプションに関連する制限は適用されません。
非公開アプリ
非公開アプリごとに、HubSpotのAPI利用ガイドラインが適用されます。非公開アプリから実行できる呼び出しの数は、ご契約のアカウントと、API追加オプションのご購入状況に基づきます。
製品のエディション | 10秒あたり | 1日あたり | |
非公開アプリ |
(全てのHub) 無料ツール、Starter |
1つの非公開アプリにつき100 | 1つのアカウントにつき250,000 |
(全てのHub) Professional、Enterprise |
1つの非公開アプリにつき150 | 1つのアカウントにつき500,000 | |
API追加オプションと非公開アプリ |
(全てのHub) 無料ツール、Starter、Professional、Enterprise |
1つの非公開アプリにつき200 | 1つのアカウントにつき1,000,000 |
APIキーによる連携
APIキーによる連携には、下記の1日あたりの制限が適用されます(検索APIを除く。下記の「その他の制限」を参照)。1日あたりの制限は、接続したアカウントのタイムゾーン設定に基づいて深夜0時にリセットされます。
製品のエディション |
制限 |
無料ツール、Starter |
瞬間(バースト):10秒あたり100 1日あたり:250,000 |
Professional、Enterprise |
瞬間(バースト):10秒あたり150 1日あたり:500,000 |
API追加オプション(全てのエディション) |
瞬間(バースト):10秒あたり200 1日あたり:1,000,000 |
レート制限を超えたアプリまたは連携は、その後の全てのAPI呼び出しに対し、429
のエラーレスポンスを受け取ることになります。エラーレスポンスが返されるリクエストの数が、1日の合計リクエスト数の5%を超えないようにしてください。アプリマーケットプレイスへのアプリの掲載を予定している場合、この5%の制限を守っていただく必要があります。
429レスポンスの形式を次に示します。
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 Enterprise契約をご利用の場合、ワークフロー内でWebhookアクションを使用してコンタクトレコードのデータを貴社のシステムに送信できます。Webhookは、どのワークフローのアクションとしてもトリガー可能なため、コンタクトデータを貴社のシステムに送信するための条件として、どのようなワークフロー開始条件でも使用できます。Webhookの詳しい使い方については、こちらを参照してください。また、Webhookデータの例についてはこちら(英語)をご覧ください。
HubSpotのサービスの制限と価格については、こちらをご覧ください。
その他の制限
- 1つの開発者アカウントにつきアプリ100個まで作成可能
- 1つのHubSpotアカウントにつき非公開アプリ20個まで作成可能
- 1つのアプリあたり1,000件までのWebhookサブスクリプションを作成可能
- 1つのアプリあたり最大25個のCRM拡張機能を作成可能
- 1つのアプリあたり最大750個のタイムライン イベント タイプを作成可能
- 1つのタイムライン イベント タイプにつき最大500個のプロパティーを作成可能
- 検索APIエンドポイントのレート制限:認証トークン1つにつき1秒あたり4つのリクエストまで