フォームのデータを送信する（認証のサポート）

Overview

このエンドポイントは、認証を使用してフォーム送信データをHubSpotに送信するために使用されます。このAPIは認証済みであるため、事前に送信対象のフォームフィールドを定義で網羅する必要はありません。ただし、使用されるプロパティーは、フォームで使用できる互換性を持つ必要があります。

登録済みの任意のHubSpotフォームに対して、外部ソースからのフォーム送信を行うことができます。アカウントのフォームのリストを表示するには、［マーケティング］＞［リード情報の収集］＞［フォーム］に移動します。このエンドポイントは、HubSpot以外のフォームでは使用しないでください。フォームを確認する際、HubSpot以外のフォームには「HubSpot以外のフォーム」というラベルが表示されます。 

カスタム ウェブサイト フォームと同等の独自のフォームをHubSpotで作成することをお勧めします。そうすれば、今後は特定のカスタムフォームの送信内容を簡単にトラッキングできるようになります。

従来のx-www-form-urlencodedエンドポイントが必要な場合は、こちらからエンドポイントの詳細をご確認ください。

このエンドポイントには以下のレート制限があります。

  • 無料／Starterアカウント：10秒あたり100リクエスト
  • Professional／Enterpriseアカウント：10秒あたり150リクエスト
  • API追加オプションを使用できるアカウント：10秒あたり200リクエスト 

注： 
  • フォーム内のフィールドは、HubSpotアカウントで設定されたコンタクトプロパティーに対応します。詳細については、コンタクトAPIとコンタクトプロパティーAPIを参照してください。
  • このエンドポイントでは、認証されていないv3フォーム送信エンドポイントよりも高いレート制限が設定されていますが、CORSはサポートされていません。CORSリクエストを送信する場合は、代わりに認証されていないv3フォーム送信エンドポイントを使用してください。 
  • フォーム送信の「submittedAt」タイムスタンプ値を過去の日付に設定すると、コンタクトの最初のページビューが「submittedAt」タイムスタンプ値より後である場合、コンタクトのオリジナルソース値が影響を受ける可能性があります。
  • このエンドポイントを使用してカスタムフォームをHubSpotに組み込んだ場合、使用可能なエンドポイントはAPI呼び出しをログに記録しないことにご注意ください。ユーザーは自分でログを保存する必要があります。
JSON本文の例： { " submittedAt ": " 1517927174000 ", // このミリ秒単位のタイムスタンプの指定は任意です。INVALID_TIMESTAMPエラーを回避するには、"1517927174000"を別の値に更新します。 "context": { "hutk": "hutk", // このパラメーターを含めて「hubspotutk」Cookie値に設定すると、送信時にCookieのトラッキングを有効にできます。 "pageName": "Example page", "pageUri": "www.example.com/page" }, "fields": [ { "name": "email", "objectTypeId": "0-1", "value": "example@example.com" }, { "name": "firstname", "objectTypeId": "0-1", "value": "Jeff" } ], "legalConsentOptions": { "consent": { // GDPRオプションが有効になっている場合は、このオブジェクトを含めます。 "communications": [ { "subscriptionTypeId": 999, "text": "I agree to receive marketing communications from Example Company.", "value": true } ], "consentToProcess": true, "text": "I agree to allow Example Company to store and process my personal data." } } }formv3 エンドポイントを使用した呼び出しの例： function formv3(){ // 新しいリクエストを作成する var xhr = new XMLHttpRequest(); var url = 'https://api.hsforms.com/submissions/v3/integration/secure/submit/62515/fcc69886-915b-4fef-b35f-27850ef461e1' // リクエストJSONの例: var data = { "submittedAt": "1517927174000", "fields": [ { "objectTypeId": "0-1", "name": "email", "value": "example@example.com" }, { "objectTypeId": "0-1", "name": "firstname", "value": "Jeff" } ], "context": { "hutk": ':hutk', // このパラメーターを含めて「hubspotutk」Cookie値に設定すると、送信時にCookieのトラッキングを有効にできます。 "pageUri": "www.example.com/page", "pageName": "Example page" }, "legalConsentOptions":{ // GDPRオプションが有効になっている場合は、このオブジェクトを含めます。 "consent":{ "consentToProcess":true, "text":"I agree to allow Example Company to store and process my personal data.", "communications":[ { "value":true, "subscriptionTypeId":999, "text":"I agree to receive marketing communications from Example Company." } ] } } } var final_data = JSON.stringify(data) xhr.open('POST', url); // HTTPリクエストヘッダーの'Content-Type'の値を'application/json'に設定します xhr.setRequestHeader('Content-Type', 'application/json'); xhr.onreadystatechange = function() { if(xhr.readyState == 4 && xhr.status == 200) { alert(xhr.responseText); // 送信が成功した場合は、200レスポンスを返します。 } else if (xhr.readyState == 4 && xhr.status == 400){ alert(xhr.responseText); // 送信が拒否された場合は、400エラーを返します。 } else if (xhr.readyState == 4 && xhr.status == 403){ alert(xhr.responseText); // ポータルが送信のPOSTを許可されていない場合は、403エラーを返します。 } else if (xhr.readyState == 4 && xhr.status == 404){ alert(xhr.responseText); // formGuid が見つからない場合は、404エラーを返します。 } } // リクエストを送信する xhr.send(final_data) }

Required Parameters

必須パラメーター 使い方 説明
ポータルID :portalId
リクエストURLで使用		 フォームが属するHubSpotポータル。
フォームID :formGuid
リクエストURLで使用		 データの送信先のフォームのID。
OAuthアクセストークンまたは非公開アプリのアクセストークン Authorization: Bearer {token} header

 リクエストの認証に使用されます。認証の詳細については、こちらのページをご覧ください。
フィールド値 "fields":[...]
リクエスト本文で使用

フォームフィールドの名前と値のリスト。各リストエントリーは、"objectTypeId":{field object}、"name":{field name}、"value":{field value}の組み合わせを含むオブジェクトになります。

このAPIでは、コンタクト、会社、カスタムプロパティーのみを使用できます。objectTypeId値とカスタムオブジェクトについて詳細をご確認ください。各フィールドのnameは、［オブジェクト］プロパティーAPIに含まれるプロパティーのnameと一致する必要があります。フィールド値の形式は、同じAPIで使用されている形式と一致する必要があります。詳細については、リクエストデータの例をご覧ください。

注：最大1,000のフィールドを含めることができます。 
従来の同意オプション legalConsentOptions: {...}
リクエスト本文で使用		 このフィールドは、フォームを送信した訪問者がコミュニケーションと処理に同意したことを示すために使用されます。このフィールドに含まれる詳細については、以下で説明します。
注：GDPR機能が有効になっているポータルでフォームが作成され、同意に関する通知の情報がフォームに追加された場合、このフィールドは必須です。

Optional Parameters

任意指定のパラメーター 使い方 説明
コンテキストデータ "context":{...}
リクエスト本文で使用		 送信のコンテキスト情報を含むデータのセット。含まれるデータの説明については、以下のエントリーをご覧ください。
HubSpotユーザートークン "hutk": {string}
コンテキストで使用		 HubSpotのリードのアクティビティーのトラッキングに使用されるトラッキングCookieトークンの値。この値は、HubSpotのJavaScriptトラッキングコードによってユーザーのブラウザーに配置された「hubspotutk」Cookieから取得できます。トラッキングコードは、フォームを含むページにインストールする必要があります。
注：hutk値がなくても送信は承認されますが、このトークンは分析データをコンタクトレコードに関連付けるために使用されるので、このトークンがないと、コンタクトレコードのページビューまたは分析ソースのデータが表示されなくなります。
IPアドレス "ipAddress":{string}
コンテキストで使用		 フォームに記入した訪問者のIPアドレス。
ページ名

"pageName":{string}
コンテキストで使用

送信が発生したページの名前またはタイトル。
ページURI "pageUri":{string}
コンテキストで使用

送信が発生したページのURI。
ページID "pageId":{string}
コンテキストで使用		 HubSpot CMSで作成されたページのID。pageIdを含めると、送信は特定のHubSpotページに関連付けられるので、ページのパフォーマンスの詳細に記録されます。

CMSページAPIを使用して、フォームでトラッキングするページのIDを取得します。
SFDCキャンペーンID "sfdcCampaignId":{string}
コンテキストで使用

HubSpotとSalesforceの連携を使用しているアカウント用のフォームでは、SalesforceキャンペーンのIDを含めると、指定したキャンペーンにコンタクトを追加することができます。
GoToWebinarキー／ID "goToWebinarWebinarKey":{string}
コンテキストで使用

HubSpotとGoToWebinarの連携を使用しているアカウント用のフォームでは、ウェビナーのIDを含めると、フォームの送信時にコンタクトをそのウェビナーに登録することができます。

詳細については、こちらのページをご覧ください。
送信タイムスタンプ "submittedAt":{timestamp}
リクエスト本文で使用

フォームの送信時刻を表すミリ秒単位のタイムスタンプ。このパラメーターを使用して送信日に過去の日付を設定することができますが、1か月より前の時刻を使用するとエラーになります。

注：このフィールドは、送信日に過去の日付を設定する目的でのみ使用できます。また、過去1か月以内の日付のみ設定できます。送信に現在の時刻を使用する場合は、リクエストからこのフィールドを除去する必要があります。
検証のスキップ
［非推奨］		 "skipValidation": {boolean}
リクエスト本文で使用

注：この任意指定のパラメーターは非推奨です。
フォーム設定に基づいて検証をスキップするかどうかを指定します。既定値はfalseです。

Legal Consent Options

従来の同意オプション

GDPRに関する通知が有効になっている場合にフォームが作成されたときは、それらの通知の詳細をフォーム送信データに含める必要があります。使用するオプションに応じて、次のいずれかのフィールドを含めてください。

  • consent - フォームで同意チェックボックスのいずれかのオプションが使用されている場合に使用します。
  • legitimateInterest - ［正当な利害関係］オプションが使用されている場合に使用されます。

各フィールドでは、以下で説明するデータが必要になります。テキストフィールドには、訪問者に表示されるテキストを含める必要があることにご注意ください。Eメール配信カテゴリーIDは、EメールAPIで取得できます。

{ "fields":[...], "legalConsentOptions":{ "consent":{ "consentToProcess":true, // Boolean; 訪問者が［処理することに同意］チェックボックスをオンにしたかどうか "text":"Text that gives consent to process", // String; ［処理することに同意］チェックボックスで訪問者に表示されるテキスト "communications":[ // フォームに含まれる配信カテゴリーごとのコミュニケーションへの同意の詳細のリスト { "value":true, // Boolean; 訪問者がこの配信カテゴリーのチェックボックスをオンにしたかどうか "subscriptionTypeId":999, // Integer; 特定の配信カテゴリーのID "text":"Consent to communicate text for subscription type ID 999" // String; この特定の配信カテゴリーのチェックボックスで訪問者に表示されるテキスト }, { "value":true, "subscriptionTypeId":777, "text":"Consent to communicate text for subscription type ID 777" } ] } } }
{ "fields": [], "legalConsentOptions": { "legitimateInterest": { "value": true, // この値は、フォームの送信時に訪問者が表明した同意を反映するので、［正当な利害関係］オプションを使用する場合にtrueになる必要があります "subscriptionTypeId": 999, // Integer; このフォームで利害関係が表明されている特定の配信カテゴリーのID "legalBasis": "CUSTOMER", // String; CUSTOMERまたはLEADのいずれか。このフォームでプロスペクト／リードまたはクライアントからの正当な利害関係が表明されているかどうかを示します "text": "Legitimate interest consent text" // String; 訪問者に表示されるプライバシーテキスト } } }

レスポンスの詳細

レスポンスには以下のフィールドがあります。

フィールド 説明
redirectUri 送信が承認され、フォームの設定でリダイレクトURIが指定されている場合は、これがそのリダイレクトURIになります。
inlineMessage 送信が承認され、フォームの設定でインラインのサンキューメッセージが指定されている場合は、これがそのメッセージのHTMLになります。
errors

送信データのエラーのリスト。各エントリーには、特定のエラーの詳細を説明するmessage値と、コード化されたerrorTypeが含まれます。

errorTypeは次のいずれかになります。

  • MAX_NUMBER_OF_SUBMITTED_VALUES_EXCEEDED：レスポンスに含まれるフィールドが1,000を超えていた。
  • BLOCKED_EMAIL：Eメールフィールドで、フォームのブロックされたEメールリストによってEメールがブロックされていた。
  • REQUIRED_FIELD：必須としてマークされているフィールドが送信に含まれていなかった。
  • INVALID_DOMAIN：会社のドメインを参照しているフィールドの値が無効だった。 
  • INVALID_LEGAL_CONSENT_OPTIONS：legalConsentOptionsが空だったか、使用された値がHubSpotアカウントに存在しない。
  • INVALID_TIMESTAMP：送信タイムスタンププロパティーの入力値が無効だった。有効なタイムスタンプは、「現在 - 30日」から「現在 + 1分」までの範囲でなければなりません。
  • INPUT_TOO_LARGE：フィールドの値がフィールドのタイプに対して大きすぎた。
  • FIELD_NOT_IN_FORM_DEFINITION：フォーム送信に含まれているフィールドがフォーム定義に含まれていなかった。
  • PORTAL_NOT_OBJECT_TYPE_OWNER：フォームフィールドのCRMオブジェクトタイプがHubSpotポータルに存在しない。

上記以外に、次のエラーが返される場合があります。 

  • 401：指定された認証資格情報が正しくない場合。
  • 403：指定された認証資格情報は正しいが、フォームを送信する権限がアカウントにない場合。
  • 429：アカウントがレート制限に達した場合。

 
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。