HubSpot2026.07.27
監修者株式会社UniteX 代表取締役
井元 裕樹
大手IT企業で3年半にわたり大手企業向け営業に従事した後、Sansan株式会社にて営業・カスタマーサクセスを経験。その後HubSpot Japanに入社し、提案営業として数百社のHubSpot導入を推進。2024年に株式会社UniteXを創業。夫婦ともにHubSpot出身で、家族でHubSpotにフルコミットする体制のもと、九州エリア初のHubSpot Gold Solutions Partner認定を経て、西日本エリア初のPlatinum Solutions Partnerに認定。AI×CRMで企業の事業変革を支援している。
この記事を読んでほしい人
- 既存フォームのデザインを変えずにHubSpotと連携したい方
HubSpotのデフォルトフォームを使わなくても、既存のフォームをそのまま活かして連携できます - Claude Codeを使ってフォーム連携を効率的に進めたい方
Claude Codeを活用した4ステップの連携手順がわかります - フォームからHubSpot CRMにリードを自動登録したい方
Forms APIの仕組みと、実際の接続・テスト・最適化の流れが把握できます
外部フォーム×HubSpot連携とは？
自社サイトやアプリ上に独自実装したフォームから、HubSpot CRMへ直接データを送信・登録する仕組みです。既存フォームのデザインを一切変えることなく、HubSpotのリード管理・ワークフロー自動化をフル活用できます。
HubSpotには標準のフォームビルダーがありますが、「既に使っているフォームのデザインを変えたくない」「WordPressやNext.jsの独自フォームをそのまま使いたい」というケースは非常に多いです。
そんなときに使うのが HubSpot Forms API です。そして Claude Code を使えば、この連携をエンジニアに頼まずに、自分で完了できます。
以下の4ステップで、スムーズに連携が完了します。
ステップ1. HubSpotとClaude Codeの接続
最初に行うのは、Claude Codeを使って既存のフォームとHubSpotのフォームを連携させることです。
事前に準備するもの
連携に必要な情報
Portal IDHubSpotの設定 → アカウントと請求 → アカウントのデフォルトで確認できる数字
Form GUIDHubSpot上で作成したフォームのUUID（マーケティング → リード情報の収集 → フォームから確認）
既存フォームのURL連携させたい自社サイトのフォームがあるページのURL
HubSpot側ではまず「受け皿」となるフォームを作成します。このフォームは実際にサイトに埋め込むものではなく、データを受け取るための箱です。必要なフィールド（メールアドレス、氏名、会社名など）を追加してください。
準備ができたら、Claude Codeに以下のように指示します：
Claude Codeへの指示例：「既存のお問い合わせフォーム（URL: https://example.com/contact）からHubSpot Forms APIにデータを送信するコードを書いて。Portal IDはXXXXXX、Form GUIDはYYYYYY」
これだけで、Claude Codeが既存フォームの構造を読み取り、HubSpotへの送信処理を含む連携コードを自動生成します。
ステップ2. 項目のマッピング
次に、HubSpot上で作成したフォームと、現在使用している既存フォームの項目を合わせます。ここが連携の成否を分ける最も重要なポイントです。
マッピングの鉄則：内部値（Internal Value）を必ず一致させる
HubSpotのフォームフィールドには「内部値」と呼ばれるデータベース上の識別名があります。既存フォームのname属性と、HubSpotの内部値が完全に一致していないと、データが正しく登録されません。
内部値の確認方法
A
HubSpot側の内部値を確認する
HubSpotの 設定 → プロパティ で、各フィールドの「内部名」を確認します。例：email、firstname、lastname、company など。
B
既存フォームの内部値を確認する
既存サイトのフォームHTMLを確認し、各入力フィールドのname属性を確認します。内部値が不明な場合は、既存サイトの情報をClaude Codeに読み込ませることで、使用されている値を特定し、それを反映させます。
Claude Codeへの指示例：「https://example.com/contact のフォームを読み取って、各フィールドのname属性とHubSpotの内部名の対応表を作って」
Claude Codeが既存フォームのHTMLを解析し、各フィールドのname属性を自動で抽出します。HubSpot側の内部名とのマッピング表を作成してくれるので、不一致があればこの段階で修正します。
| 既存フォームの name 属性 | HubSpotの内部名 | 一致状況 |
|---|---|---|
email | email | ✅ 一致 |
name | firstname | ❌ 不一致 → 変換が必要 |
tel | phone | ❌ 不一致 → 変換が必要 |
company | company | ✅ 一致 |
不一致があった場合も、Claude Codeが送信時にフィールド名を変換するコードを自動で生成してくれるため、既存フォームのHTMLを変更する必要はありません。
ステップ3. 接続確認とテスト
HubSpotのフォームと既存フォームの接続が確認できたら、実際に送信テストを行います。
テストの手順
1
テストデータを送信する
既存フォームからテスト用のデータを実際に送信します。メールアドレスは自分のものを使い、各フィールドにテスト値を入力してください。
2
HubSpot CRM上で確認する
HubSpotの コンタクト 画面を開き、テスト送信したデータが正しく登録されているか確認します。各フィールドの値が正しいか、一つずつチェックしてください。
3
ワークフローの動作を確認する
フォーム送信をトリガーにしたワークフロー（自動返信メール、Slack通知など）が正常に動作しているか確認します。
確認ポイント：テスト送信後、HubSpotのコンタクトレコードで以下を確認してください。
- 全フィールドの値が正しく入っているか
- フォーム送信のアクティビティが記録されているか
- 訪問履歴（ページビュー）がコンタクトに紐付いているか
ステップ4. 動作の最適化
テストの結果、もし誤りや不具合があれば、再度Claude Codeに修正案を確認します。問題なく稼働するまでこのプロセスを繰り返してください。
よくある問題と対処法
| 問題 | 原因 | 対処法 |
|---|---|---|
| データがHubSpotに届かない | Portal IDまたはForm GUIDの入力ミス | Claude Codeに「送信が失敗する。エラーを確認して」と伝える |
| フィールドの値が空になる | 内部値（name属性）の不一致 | ステップ2に戻り、マッピングを再確認する |
| 訪問履歴が紐付かない | hutkの送信漏れ | Claude Codeに「hutkを送信するコードを追加して」と指示 |
| ワークフローが発火しない | HubSpot側のトリガー設定ミス | ワークフローのトリガー条件を確認・修正する |
Claude Codeへの指示例：「フォーム送信後にHubSpotで400エラーが返ってくる。エラー内容を確認して修正コードを出して」
Claude Codeはエラーレスポンスの内容を解析し、原因の特定と修正コードの提案を即座に行います。修正 → テスト → 確認のサイクルを繰り返すことで、確実に稼働する連携が完成します。
よくある質問（FAQ）
Forms APIを使う場合、HubSpotのフォームを作成する必要はありますか？
はい、必要です。Forms APIはHubSpot上のフォーム定義を「受け皿」として使用します。実際のフォームUIは自社サイト側のものをそのまま使いますが、Portal IDとForm GUIDの取得のためにHubSpot側でフォームを作成する必要があります。
既存のフォームのデザインを変える必要はありますか？
いいえ、変える必要はありません。Forms APIはバックエンドでデータを送信する仕組みなので、見た目はそのままで連携できます。
Claude Codeを使わなくても連携できますか？
はい、手動でも可能です。ただし、Forms APIの仕様理解・コーディング・フィールドマッピング・エラー対応をすべて自分で行う必要があります。Claude Codeを使えば、これらを日本語の指示だけで完了できます。
1つのHubSpotフォームに複数の外部フォームからデータを送れますか？
はい。同じPortal IDとForm GUIDを指定すれば、複数のWebページから送信可能です。送信元を区別したい場合は、フォームを分けるか context.pageUri で識別します。
無料プランでもForms APIは使えますか？
はい、HubSpotの無料プランから利用可能です。
まとめ
- ステップ1：Claude Codeを使って、既存フォームとHubSpotのForms APIを接続する
- ステップ2：内部値（Internal Value）を一致させ、項目のマッピングを行う
- ステップ3：テスト送信を行い、CRM上でデータが正しく登録されているか確認する
- ステップ4：不具合があればClaude Codeで修正し、問題なく稼働するまで繰り返す
