問い合わせフォーム経由のコンタクトをAPIで取得したい

[Taiki_Ogasawara]

APIのドキュメントを読んで、GETメソッドで取得できる範囲のデータを、自動で日々一通り取得してDBに保持しています。

最近になって、過去からの特定フォーム経由の問い合わせ内容を、一覧で取得したい要求が発生しました。

各種分析や可視化を自動化したいと考えています。

そこで、あらためてAPIで取得してDBに蓄積しているデータを見たのですが、フォーム入力内容も、どのコンタクトがどのフォーム経由の問い合わせなのかも、見つけることができませんでした。

APIで取得できるデータでは、特定のフォームの問い合わせ内容を取得できないのでしょうか?

[Taiki_Ogasawara]

@assi 

いろいろ丁寧にありがとうございます!

助かります…これから実際に試してみます!

[assi · Accepted solution]

@Taiki_Ogasawara 

v1のエンドポイントを利用することにより、ある程度実現が可能になります。

まず1番クライアント側の処理数を少なくデータ取得する方法は、v1の「Get a contact by email address」エンドポイントを利用する方法です。

https://api.hubapi.com/contacts/v1/contact/email/:contact_email/profile?property=firstname 

 のレスポンスは以下のようになり、おおよそ希望のデータが取得できます。

{
  "vid": 123,
  "canonical-vid": 123,
  "merged-vids": [],
  "portal-id": 0000000,
  "is-contact": true,
  "properties": {
    "firstname": {
      "value": "惇志",
      "versions": [
        {
          "value": "惇志",
          "source-type": "FORM",
          "source-id": "1aada3f4-14db-42e1-8d11-af544d916676",
          "source-label": "名",
          "updated-by-user-id": null,
          "timestamp": 1708563112869,
          "selected": false
        }
      ]
    }
  },
  "form-submissions": [
    {
      "conversion-id": "1aada3f4-14db-42e1-8d11-af544d916676",
      "timestamp": 1708563112869,
      "form-id": "c1c95aba-6969-4a99-8892-69f632b865cd",
      "portal-id": 0000000,
      "page-url": "https://0000000.hs-sites.com/register",
      "content-type": "landing-page",
      "page-title": "登録フォーム",
      "page-id": "157926567090",
      "title": "保護者様とお子様の情報",
      "form-type": "HUBSPOT",
      "meta-data": []
    }
  ],
  "list-memberships": [],
  "identity-profiles": [],
  "merge-audits": []
}

※ドキュメントにも記載がありますが、ここまで多くの情報が取れるのは本エンドポイントのオプショナルパラーメータがデフォルトでそれぞれ propertyMode=value_and_history&formSubmissionMode=all になっているからです。

※もちろん、Batch Readのエンドポイントも存在します。

ただし、このエンドポイントは

• Contacts APIとしてはバージョンが古いものであり
• かつ、Contacts APIの後継はv3が正式リリースされている

という2点において、自己責任のもとご利用いただく必要があります。

※旧バージョンのエンドポイントだからといって、ある日突然利用できなくなる訳ではありません。 Developer Changelog のサイトにて、事前に廃止の告知がなされます。

例：https://developers.hubspot.com/changelog/2019-01-30-sunset-the-v1-forms-api-will-be-sunset-on-march-...

次にもう少し安全な方法としては、

1. Contacts API v3のエンドポイントを propertiesWithHistory のパラメータ付きで叩き
2. フォームから投入されたプロパティがあれば、そのプロパティを更新すると思しきフォームのIDを利用してForms API v1を叩きフォーム単位の送信データを取得し
3. 1と2を突き合わせる

という方法になります。

それぞれ、次のようなレスポンスになっています。

Contacts API v3のエンドポイント

https://api.hubapi.com/crm/v3/objects/contacts/:contactId?propertiesWithHistory=firstname

レスポンス

{
  "id": "151",
  "properties": {
    "createdate": "2024-02-22T00:51:54.167Z",
    "email": "atsushi.handa@example.com",
    "firstname": "惇志",
    "hs_object_id": "151",
    "lastmodifieddate": "2024-02-22T02:35:02.223Z",
    "lastname": "半田"
  },
  "propertiesWithHistory": {
    "firstname": [
      {
        "value": "惇志",
        "timestamp": "2024-02-22T00:51:52.869Z",
        "sourceType": "FORM",
        "sourceId": "1aada3f4-14db-42e1-8d11-af544d916676",
        "sourceLabel": "名"
      }
    ]
  },
  "createdAt": "2024-02-22T00:51:54.167Z",
  "updatedAt": "2024-02-22T02:35:02.223Z",
  "archived": false
}

これにより、

• どのプロパティが
• いつ
• 何経由で（ sourceType ）

更新されたかがわかります。

※もちろん、Batch Readのエンドポイントも存在します。

Forms API v1「Get submissions for a form」のエンドポイント

https://api.hubapi.com/form-integrations/v1/submissions/forms/:form_guid 

レスポンス

{
  "submittedAt": 1708481435124,
  "values": [
    {
      "name": "lastname",
      "value": "半田",
      "objectTypeId": "0-1"
    },
    {
      "name": "firstname",
      "value": "惇志",
      "objectTypeId": "0-1"
    },
    {
      "name": "email",
      "value": "atsushi.handa@example.com",
      "objectTypeId": "0-1"
    }
  ],
  "pageUrl": "https://share.hsforms.com/1wclaumlpSpmIkmn2MrhlzQqnjgi"
}

これにより、

• 送信時のタイプスタンプ （ submittedAt ）
• 更新されたプロパティ
• コンタクトのemail

がわかり、1の sourceType と2の submittedAt のタイプスタンプの一致が確認できたら、「どのコンタクトプロパティがどのフォームから送信されたものなのか」がわかります。

なおこちらでもForms API v1のエンドポイントを利用していますが、Forms API v3は未だベータですので、Forms APIについては現状はv1が現行バージョンとなります。