よくある質問（FAQ）

HubSpotのAPIについて多く寄せられる質問と回答を紹介します。CMS開発に関する質問については、該当するドキュメントを参照してください。お探しの情報が見つからない場合は、開発者フォーラム（英語）で相談することもできます。

jQueryを使用してフォームを操作する方法を教えてください。

.val()または.prop()を使用してフォームの入力値を操作する場合、change()またはtrigger('change')を使用して変更イベントをトリガーすることにより、変更を適切に登録する必要があります。

HubSpotフォームはDOMの構築後にレンダリングされるため、ウィンドウの読み込み後に操作をトリガーするか、onFormReadyパラメーターを使用するように埋め込みに変更を加える必要があります。

Update fields when page finishes loading: $(window).load(function(){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); }); Modified embed code to update fields when form builds: hbspt.forms.create({ portalId: 'XXXXXX', formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX', onFormReady: function($form, ctx){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); } });

HubSpotのAPIによるタイムスタンプの形式はどのように設定すればよいですか？

HubSpot APIでは、日付と時刻の値に2つの異なる形式を使用できます。

1つは、ISO 8601形式の文字列です。データ型に応じて、次のいずれかの形式になります。

  • 特定の日付を表す値の場合、次のような完全日付形式が使用されます。YYYY-MM-DD（例：2020-02-29）
  • 特定の日時を表す値の場合、完全な日付形式に時、分、秒、および秒小数部分を追加した次の形式が使用されます。YYYY-MM-DDThh:mm:ss.sTZD（例：2020-02-29T03:30:17.000Z）。時刻は常にUTCで表現されるため、値には必ずUTC指定子「Z」が使用される点に注意してください。

もう1つは、UNIX形式のタイムスタンプです（ミリ秒単位）。タイムスタンプ値はUTC時刻を想定して扱われます。例えば、タイムスタンプ値1427997766000は、2015年4月2日の午後2:02:46 EDT（米国東部夏時間）、つまり2015年4月2日の18:02:46 UTCを表します。

レスポンス上の時刻値はISO 8601の値として表記されますが、APIではいずれの形式も受け入れられます。

HubSpot CRMでの日付と日時のプロパティー

HubSpotには、時間を保存するためのCRMオブジェクトプロパティーとして、dateとdatetimeの2種類があります。

Dateのプロパティー（HubSpotで作成されたdate pickerのプロパティーを含む）に格納できるのは日付のみで、時刻は格納できません。日付プロパティー値を設定する際は、ISO 8601の完全な日付形式を使用することをお勧めします。

例：

  • 2015-05-01は、2015年5月1日を表します。ミリ秒単位のタイムスタンプを使用することもできますが、必要な日付のUTCの深夜の値に設定する必要があります。 
  • 1430438400000は、2015年5月1日（2015年5月1日の00:00:00 UTC）を表します。

UTCの深夜以外の値を設定しようとすると、エラーが返されます。HubSpotの日付プロパティーでは、アカウントやユーザーのタイムゾーン設定に関係なく、設定されている特定の日付が常に表示されます。

Datetimeのプロパティーには任意の時刻を格納できるため、有効な日付または日時の値なら、どちらの形式でも使用できます。HubSpotのdatetimeのプロパティーは、レコードを表示するユーザーのタイムゾーンに基づいて表示されるため、値はユーザーのタイムゾーンに変換されます。

HubSpot上に作成したdate pickerプロパティーは常にdateプロパティーになるため、datetimeプロパティーの唯一の作成方法はAPIを使用することです。貴社の連携において特定の時刻を保持する必要がある場合は、連携を行うCRMオブジェクトのプロパティーエンドポイントを使用してカスタム日時プロパティーを作成することをお勧めします。

APIのエラーメッセージに関する留意点はありますか？

特に明記されていない限り、大半のHubSpotエンドポイントでは、正常に完了した場合に200 OKのレスポンスが返されます。他のステータスコードを返すエンドポイントについては、エンドポイントのドキュメントに、どのレスポンスが返されるかが明記されています。

さらに、HubSpotには、複数のAPIに共通する次のようなエラーレスポンスがあります。

  • 401 Unauthorized - APIに渡された認証情報が無効な場合、このエラーレスポンスが返されます。APIリクエストの認証については、認証の概要（英語）を参照してください。
  • 403 Forbidden - APIに渡された認証対象にその特定のURLに対するアクセス権限が付与されていない場合、このエラーレスポンスが返されます。例えば、コンテンツのアクセス権限しか付与されていないOAuthトークンによって取引API（コンタクトアクセス権限が必要）にアクセスしようとすると、403が返されます。
  • 429 Too many requests - アカウントまたはアプリが、該当するAPIレート制限（英語）を超えている場合、このエラーレスポンスが返されます。レート制限を順守するための推奨事項については、こちら（英語）に記載しています。
  • 502／504 timeouts - HubSpotには、単一のクライアントに起因するパフォーマンスの低下を防止するためのプロセス制限が設けられています。このレスポンスは、その制限に達したことを意味します。通常、このようなタイムアウトレスポンスが表示されるのは、長時間にわたり大量のリクエストを送信している場合に限られます。これらのレスポンスのいずれかが表示されたら、数秒間リクエストを一時停止してから再試行してください。

上記の全般的なエラーを除いて、HubSpotのエラーレスポンスは基本的に読みやすく記述されています。ほとんどのエンドポイントから、エラーコードではなく、エラーに関する詳細を記載したJSON形式のレスポンスが返されます。エンドポイント固有のエラーの詳細は、該当するエンドポイントのドキュメントページに記載されています。

注：以下のレスポンスの例に含まれている全てのフィールドは、エラー解析時には任意指定として扱ってください。APIごとに使用する具体的なフィールドは異なるため、エラー解析では、レスポンスに特定のフィールドが欠落していても許容する必要があります。

{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

HubSpot APIではCORS／AJAXリクエストがサポートされますか？

ほとんどの場合、HubSpot APIにおいてクロスオリジン（CORS）AJAXリクエストはサポートされません。クライアントサイドでJavaScriptを使用してリクエストを送信すると、そのリクエストで使用している認証情報が公開されてしまいます。JavaScript／AJAXを使用するには、（認証情報を除く）リクエストを外部サーバーに送信し、必要な認証情報を追加してから、HubSpot APIのサーバーサイドにリクエストを送信する必要があります。

このルールには、次の例外があります。

HubSpotでは、Eメールアドレスはどのように検証されますか？

HubSpotでは、コンタクトレコードの作成または更新のプロセスに使用されるEメールアドレスが検証されます。コンタクトエンドポイントを使用したコンタクトの作成または更新以外に、フォーム送信（英語）やイベント（英語）も同様です。

こうしたプロセスでは、（埋め込みフォームの場合のように）Eメールアドレス自体の有効性がチェックされるのではなく、その形式がチェックされます。RFC 2822に準拠した有効性に加えて、HubSpotではEメールアドレスに関する次の制限も適用されます。

  • ローカルの部分を引用符で囲むことはできません（例："Test Email"@hubspot.comは無効）。
  • https://data.iana.org/TLD/tlds-alpha-by-domain.txtに記載されているように、ドメインの部分は有効なTLDで終わる必要があります（この制限はUnicode TLDの処理後に適用されるため、「user@email.삼성」は有効なEメールアドレスです）。
  • v3のフォームAPI（英語）を使用する場合は、リクエスト本文にskipValidationパラメーターを追加し、値をtrueに設定することにより、検証を無視できます。

チェックボックスのプロパティーに複数の値を設定する方法を教えてください。

チェックボックスのプロパティーに複数の値を設定するには、値をセミコロン（;）で区切る必要があります。
例：'value1;value2;value5'

CRMオブジェクトエンドポイントを介してレコードを更新する場合、プロパティー値は、全てセミコロンで区切られた値から成る単一の文字列にする必要があります。

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

フォームエンドポイントの場合は、セミコロンについてもURLエンコードする必要があります。

...&example_property=value1%3Bvalue2%3Bvalue4

コンタクトレコードに関する制限はありますか？

HubSpotでは、マージされるコンタクトレコードに関して、またコンタクトレコードのフォーム送信に関していくつかの制限が設けられています。

  1. リンクできるIDは、コンタクトあたり最大250個に制限されています。
    • 2つのコンタクトをマージしようとして、その結果、コンタクトあたりのIDが250個を超える場合は、エラーが返されます。
  2. コンタクトのフォーム送信は最大1,000件に制限されています。コンタクトがこの制限を超えることになる送信は、完全に破棄されます。
    • このフォームデータによるコンタクトレコードの更新は行われません。
    • コンタクトエンドポイントからのform-submissionsデータにも、コンタクトのタイムラインにも、コンタクトレコードに関する送信自体が示されません。
    • この送信には、リストメンバーシップまたはワークフローに関する評価が行われません。
    • この送信はHubSpot上でフォームを表示した場合の送信リストに表示されません。

テストが原因で以上のいずれかの上限を超えた場合、テストコンタクトを削除し、新しいテストレコードを作成することをお勧めします。新しいコンタクトに同じEメールアドレスを使用しても、削除済みのコンタクトは復元されません。そのEメールでのフォーム送信は、新しいレコードに関連付けられます。

トランザクションEメールの送信方法を教えてください。

HubSpotではトランザクションEメールの送信方法として、SMTP APIと1回送信APIの2つが用意されています。

SMTP APIの使用

SMTP APIは、Eメールの送信を直接行いませんが、HubSpot SMTPサーバーへのログイン資格情報を取得するためにだけ使用されます。SMTP APIを使用してトークンとパスワードを取得した後、これらの資格情報を使用してHubSpotのSMTPサーバーにログインし、SMTP経由でEメールを送信する必要があります。SMTPサーバーへのログイン詳細（ホスト名とポート）は、ドキュメントページ（英語）で説明します。HubSpotのEメールトラッキングをサポートするためにEメールとリンクはラッピングされますが、それ以外のEメールコンテンツ全体はご自身で作成する必要があります。

1回送信APIの使用

1回送信APIでは、HubSpotのEメールツールで作成したテンプレートEメールとJSON形式のPOST APIを使用して、Eメールが送信されます。まず、HubSpotでEメールを作成し、受信者を選択する際に［1回送信API用に保存］を選択する必要があります。Eメールが作成されたら、APIリクエストの本文で受信者の詳細（Eメールでセットアップしたコンタクトやカスタムプロパティーを含む）を設定した上で、APIを使用してコンタクトにEメールを送信できます。JSONリクエストの形式については、このドキュメントページ（英語）で説明します。

APIに関する最新情報の受信方法を教えてください。

HubSpotのAPIと開発者ツールに関する最新情報は、開発者変更ログ（英語）で提供しています。

左側のフォームを使用して最新情報の受信登録ができます。発表と同時に通知を受けるには、頻度として［Instant］を選択します。他の頻度を選択して、最適な頻度で最新情報の要約を受け取ることもできます。

HubSpotプラットフォームを利用してプライバシーおよび法令順守に対応する方法を教えてください。

HubSpotでのデータ処理の法的根拠のトラッキング

GDPR（EU一般データ保護規則）により、企業が連絡先情報を使用、処理するためには法的根拠が必要となり、情報の提供者による同意と、合法的な処理方法を示す証拠を記録に残すことが義務化されました。

［コンタクトのデータを処理するための法的根拠］というコンタクトプロパティーでは、契約や正当な利害関係、および／または同意に基づくHubSpotのコンタクトに関するデータ処理の法的根拠を収集、追跡、保存することができます。

コンタクトエンドポイントを介してコンタクトデータにアクセスする場合、このプロパティーではhs_legal_basisという名前が使用されます。他のコンタクトのプロパティーと同じように、このプロパティーが設定されたコンタクトにはAPI経由のアクセスが可能です。このプロパティーは、APIを介して、コンタクトレコードに関して更新したり設定したりすることもできます。

ただし、このプロパティーのオプションに対して、API経由で変更を加えることはできません。更新はHubSpot内に限定されますが、このプロパティーに設定されているカスタムオプションをコンタクト プロパティー エンドポイント経由で取得することは可能です。HubSpotアカウントによっては既定とは異なる設定が使用されている場合もあるため、このようなエンドポイントを使用してプロパティーのオプションを取得することをお勧めします。

このプロパティーの詳細とHubSpotでの使い方については、こちらを参照してください：
ナレッジベース記事。

プライバシー規則に準拠したコンタクト削除の処理

HubSpotユーザーは、プライバシーに関する法律に準拠するためにコンタクトレコードを完全に削除することができます。詳細については、こちらのナレッジベース記事を参照してください。

contact.privacyDeletionサブスクリプションタイプの受信を登録することにより、ユーザーがプライバシー順守のためのコンタクト削除を実行したときにWebhook通知を受信できます。Webhookの詳細とWebhook通知を処理する（英語）方法については、Webhookの概要（英語）を参照してください。