Hubspot Forms にAPIを利用してお問い合わせを登録する方法

# はじめに
サイトのお問い合わせフォームからのお問い合わせの内容を、サイト管理者に対してメール通知する運用はよく用いられますが、通知されたお問い合わせをひとつひとつ保存し、タスク化することは手間がかかります。

Hubspotが提供するフォーム機能には、お問い合わせの保存とタスク化を自動化する仕組みがあり、この仕組みを利用するためのAPIも公開されています。

このAPIを利用して、既に公開されているサイトのお問い合わせフォームからのお問い合わせを、Hubspotフォーム機能に連携する方法を紹介します。


# 提供されているAPIについて
Hubspotフォーム機能連携用に提供されているAPIは、下記の２種類が存在します。
認証の有無以外に、仕様の大きな違いはありませんが、認証無しAPIについては非推奨とのことです。

* 認証無しAPI：Submit data to a form（※非推奨）

https://legacydocs.hubspot.com/docs/methods/forms/submit_form


* 認証有りAPI：Submit data to a form (Supporting Authentication)

https://legacydocs.hubspot.com/docs/methods/forms/submit_form_v3_authentication


# Hubspotの設定
APIを利用する前にHubspot側の設定が必要となるため、その設定方法を説明します。

:::note warn
注意事項
無料枠Hubspot（2023年10月現在）による操作手順となります。
料金プラン、時期によっては、操作手順が異なる場合があります。
:::


## フォーム作成
先ずは、Hubspotフォームに連携先となるフォームを作成します。

1.   **[マーケティング]**  メニューから  **[フォーム]**  ボタンを押下。
![create_form_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/a0c286f8-9fd5-ea5f-7583-c0a676e2f154.png)

1.   **[（無料）フォームを作成]**  ボタンを押下。
![create_form_02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/10c9579b-8109-2325-1750-3c1cc2610b48.png)

1. 任意のフォームのタイプを選択し、  **[次へ]**  ボタンを押下（本手順では、  **[埋め込みフォーム]**  を選択）。
![create_form_03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/548b4aea-ff6e-95e2-acb5-7d672a29fead.png)

1. 任意のテンプレートを選択し、  **[開始]**  ボタンを押下（本手順では、  **[お問い合わせ]**  を選択）。
![create_form_04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/5c1ed87c-ddbb-338d-1c3e-5b4e83378d13.png)

1. 必要に応じて利用するプロパティを左の画面からドラッグ＆ドロップで、右の編集画面に追加（本手順では、  **[会社名]**  を追加）。右の編集画面に表示されるプロパティ名とオブジェクト名をメモしたうえで、  **[更新]**  ボタンを押下。
![create_form_06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/750f019d-f382-ea6a-1f90-124a96a36972.png)

1. 表示された内容を確認し、  **[公開]**  ボタンを押下。
![create_form_07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/9e62edf9-5f62-934b-a020-8024f9f5021e.png)

1. 公開完了画面の  **[埋め込みコード]**  ボタンを押下。
![create_form_08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/eb49cf60-3f5b-5b91-e11b-22652f9e121c.png)

1. 表示された埋め込みコード内の  **[portalId]**  と  **[formId]**  をメモ。
![create_form_09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/ff503c1b-e1a1-82b6-19e0-ded89f297e8c.png)


## APIアクセストークン発行
次に、APIアクセストークンを発行します。
認証無しAPIを利用される場合は、本手順は不要となります。

1. 上部メニューの  **[設定]**  ボタンを押下。
![create_token_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/49b1bd9a-c954-c978-0113-a65dd770b8bf.png)

1. 左メニューの  **[連携]** ＞  **[非公開アプリ]**  ボタンを押下。
![create_token_02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/a7fce01d-c884-c45c-c1b1-7edf350c6265.png)

1.   **[非公開アプリを作成]**  ボタンを押下。
![create_token_03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/58300d2e-db53-2199-bbba-db36ccde97ab.png)

1.  基本情報に任意の  **[名前]**  と  **[説明]** を入力し、  **[スコープ]**  タブを押下。
![create_token_04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/00b181ba-1445-941d-22af-4f61f748f28e.png)

1.  スコープ検索を行い、  **[標準]**  ＞  **[forms]**  を選択し、  **[アプリを作成]**  ボタンを押下。
![create_token_05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/7f480d63-83fc-f2da-d532-bb144051bc67.png)

1.  表示された内容を確認し、  **[作成を続行]**  ボタンを押下。
![create_token_06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/7e9d358c-615d-f2af-fa97-d92a9b8a87a6.png)

1.   **[トークンを表示]**  を押下、  **[アクセストークン]**  をメモし、  **[非公開アプリを見てみる]**  ボタンを押下。
![create_token_07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/cb7fc27d-efad-2291-13ec-4300ce7457e7.png)

以上で、Hubspot側の設定は完了となります。

# API呼び出し設定
引き続きAPI側の設定方法を説明します。
本手順では「Postman App（Ver 10.19.0）」を利用して説明します。「Postman App」の詳細については下記リンクを参照してください。

https://www.postman.com/

なお、本手順では、作成したHubSpotフォームの項目（プロパティ）に対する連携のみを記載しています。IPアドレスやページURLなどの情報を連携する方法については、「[提供されているAPIについて](#提供されているAPIについて) 」に記載したAPIのドキュメントを参照してください。



## 認証無しAPI呼び出し設定
### メソッド・エンドポイント、パラメーターの設定
共通部分にメソッドとエンドポイントを設定し、 **[Params]** タブの **[Path Variables]** にパス変数の「キー項目」と「設定値」を設定します。

![postman_setting_11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/84ceb44d-5a81-1258-e2cd-844a34ea6975.png)

* メソッド・エンドポイント

|項目|設定値|
|:---:|:---|
|メソッド|POST|
|エンドポイント| https\://api.hsforms.com/submissions/v3/integration/submit/:portalId/:formGuid|

* パス変数

|項目|キー項目名|設定値|
|:---:|:---|:---|
|HubspotポータルID|portalId|「[フォーム作成](#フォーム作成)  ＞ 8.」  にて、メモした  **[portalId]**  |
|HubspotフォームID|formGuid|「[フォーム作成](#フォーム作成)  ＞ 8.」  にて、メモした  **[formId]**  |


### リクエストボディの設定
**[Body]** タブのコンテンツタイプとリクエストボディの内容を設定します。

![postman_setting_12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/5eb1b9da-fa3e-9636-3bbb-1e1c8a5aa8ed.png)

* コンテンツタイプ

|コンテンツタイプ|
|:---:|
|raw → JSON|

* 設定例（「[リクエストボディの設定内容について](#リクエストボディの設定内容について) 」を参照。）
```json:body
{
  "fields": [
    {
      "objectTypeId": "0-1", 
      "name": "email",
      "value": "test1@test.co.jp"
    },
    {
      "objectTypeId": "0-1",
      "name": "firstname",
      "value": "連携一"
    },
    {
      "objectTypeId": "0-1",
      "name": "lastname",
      "value": "問合"
    },
    {
      "objectTypeId": "0-1",
      "name": "company",
      "value": "株式会社 問い合わせ連携"
    },
    {
      "objectTypeId": "0-1",
      "name": "message",
      "value": "製品について問い合わせします。"
    }
  ]
}
```

## 認証有りAPI呼び出し設定
### メソッド・エンドポイント、パラメーターの設定
共通部分にメソッドとエンドポイントを設定し、 **[Params]** タブの **[Path Variables]** にパス変数の「キー項目」と「設定値」を設定します。

![postman_setting_21.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/a8593cd2-e3b7-72c2-913e-73abe1bf0a02.png)

* エンドポイント

|項目|設定値|
|:---:|:---|
|メソッド|POST|
|エンドポイント| https\://api.hsforms.com/submissions/v3/integration/secure/submit/:portalId/:formGuid|

* パス変数

|項目|キー項目名|設定値|
|:---:|:---|:---|
|HubspotポータルID|portalId|「[フォーム作成](#フォーム作成)  ＞ 8.」  の  **[portalId]**  |
|HubspotフォームID|formGuid|「[フォーム作成](#フォーム作成)  ＞ 8.」  の  **[formId]**  |


### 認証の設定
**[Authorization]** タブの認証情報を設定します。

![postman_setting_22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/74d5cc07-0955-9a96-708c-de56b3c8d7b7.png)

* 認証方式

|項目|設定値|
|:---:|:---|
|認証タイプ|Bearer Token|
|トークン| 「[APIアクセストークン発行](#APIアクセストークン発行)  ＞ 7.」  の  **[アクセストークン]**|


### リクエストボディの設定

![postman_setting_23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/6135a62f-f76c-a30d-395c-7eddc9842062.png)

* コンテンツタイプ
**[Body]** タブのコンテンツタイプとリクエストボディの内容を設定します。

|コンテンツタイプ|
|:---:|
|raw → JSON|

* 設定例（「[リクエストボディの設定内容について](#リクエストボディの設定内容について) 」を参照。）
```json:body
{
  "fields": [
    {
      "objectTypeId": "0-1",
      "name": "email",
      "value": "test2@test.co.jp"
    },
    {
      "objectTypeId": "0-1",
      "name": "firstname",
      "value": "連携二"
    },
    {
      "objectTypeId": "0-1",
      "name": "lastname",
      "value": "問合"
    },
    {
      "objectTypeId": "0-1",
      "name": "company",
      "value": "株式会社 問い合わせ連携"
    },
    {
      "objectTypeId": "0-1",
      "name": "message",
      "value": "製品について問い合わせします。"
    }
  ]
}
```

## リクエストボディの設定内容について

配列  **[fields]**  の設定内容は下記の通りとなります。

|キー|データ型|名称|設定内容|
|:---:|:---:|:---|:---|
|objectTypeId|文字列|オブジェクトタイプID|「[フォーム作成](#フォーム作成)  ＞ 5.」の **[オブジェクト名]** に対応したID。<br>　● コンタクトプロパティ ： 0-1<br>　● 会社プロパティ ： 0-2<br>　● 取引プロパティ ： 0-3<br>　● チケットプロパティ ： 0-5|
|name|文字列|プロパティ名|「[フォーム作成](#フォーム作成) ＞ 5.」の **[プロパティ名]** 。|
|value|文字列|設定値|プロパティに設定する値。|


# API実行
上記の設定が完了したら、 **[Send]** ボタンを押下して、それぞれのAPIを実行します。
設定等に問題がなければ、以下のような実行結果が確認できます。。

## 認証無しAPI実行結果
* 呼び出し側
![result_api_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/6c7281c4-14bc-1f8b-840d-0d069716b4f1.png)

* HubSpotフォーム
![result_form_01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/6d376b36-b365-1cbe-0510-3a0bd657ea09.png)


## 認証有りAPI呼び出し設定
* 呼び出し側
![result_api_02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/cecc62dc-116a-d383-e648-b3b36f6ebf36.png)

* HubSpotフォーム
![result_form_02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3579417/617fb4e3-b24a-daf7-ba35-d1c79bb2057f.png)


# おわりに
「認証無し」、「認証有り」、どちらのAPIでもHubSpotフォームへの登録が行えることが確認できました。
次回は、WordPressで構築された既に公開されているサイトのお問い合わせフォームの内容をHubSpotフォームへ連携する方法を紹介します。