HubSpot

HubSpot CRMのコンタクトを作成・更新・取得

​

概要

HubSpotツールはHubSpot CRM APIと連携し、ワークフローからコンタクトを管理します。どちらのツールもメールアドレスをキーにするため、Search API（レート制限あり）を経由せずにレコードを照合できます。

​

主な機能

• HUBSPOT_UPSERT_CONTACT
  • コンタクトを作成します。同じメールアドレスのコンタクトが既にある場合は更新します。カスタムプロパティにも対応しています。
• HUBSPOT_GET_CONTACT
  • オブジェクトIDまたはメールアドレスでコンタクトを取得します。該当するコンタクトがない場合はエラーにせず found: false を返します。

​

認証

設定手順についてはHubSpot認証情報ページをご確認ください。

設定フィールド	説明
access_token	HubSpotのアクセストークン（ワークスペースのシークレットから選択）。crm.objects.contacts.read と crm.objects.contacts.write スコープが必要です。

​

例: コンタクトを検索してから作成・更新する

- id: find_contact
  tool: HUBSPOT_GET_CONTACT
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: email
      value: "[e-mail]"
    - name: properties
      value: "email, firstname, lastname, company"
- id: upsert_contact
  tool: HUBSPOT_UPSERT_CONTACT
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: email
      value: "[e-mail]"
    - name: firstname
      value: "Ada"
    - name: lastname
      value: "Lovelace"
    - name: lifecyclestage
      value: "lead"
    - name: properties
      value: '{"hs_lead_status":"OPEN"}'

​

入力パラメータ

​

HUBSPOT_UPSERT_CONTACT

パラメータ	必須	説明
email	○	照合キー。このメールアドレスのコンタクトが既にあれば更新し、なければ新規作成します。
firstname, lastname, phone, company, jobtitle, website		標準のコンタクトプロパティ。
lifecyclestage		例: subscriber, lead, marketingqualifiedlead, customer。
properties		その他のHubSpotプロパティを「内部名 → 値」のJSONオブジェクトで指定します（例: {"hs_lead_status":"OPEN"}）。値を null にするとそのプロパティをクリアします。

名前付きパラメータを空にした場合は送信されません。HubSpot は空文字を「プロパティをクリア」と解釈するため、クリアは properties から明示的に指定してください（{"firstname": null}）。キーが重複した場合、名前付きパラメータが properties より優先されます。properties.email に email パラメータと異なる値を指定するとエラーになります（大文字小文字の違いのみは同一として扱います）。

出力は result.id / result.created / result.properties と、生のレスポンス result.contact です。

​

HUBSPOT_GET_CONTACT

パラメータ	必須	説明
contact_id	どちらか一方	HubSpotのコンタクトオブジェクトID。
email	どちらか一方	コンタクトのメールアドレス。
properties		取得するプロパティ名をカンマ区切りで指定します（例: email, firstname, company）。空にするとHubSpotは最小限のプロパティしか返しません。カスタムプロパティは内部名で指定します（HubSpotの設定 → プロパティで確認できます）。
associations		関連レコードのIDも取得するオブジェクト種別をカンマ区切りで指定します（例: companies, deals）。

出力は result.found / result.id / result.properties / result.associations と、生のレスポンス result.contact です。

​

備考

• 該当なしはエラーではない: HUBSPOT_GET_CONTACT はコンタクトが見つからない場合に result.found = false を返します。「検索して、なければ作成する」を通常の条件分岐ステップとして組めます。
• 同時書き込みは後勝ち: HubSpotのCRM APIには楽観的ロックの仕組みがないため、更新が重なるとプロパティ単位で後勝ちになります。実行が重なりうる状況で「スコアを読んで加算して書き戻す」といった処理に HUBSPOT_UPSERT_CONTACT を使わないでください（HubSpotの計算プロパティを利用してください）。
• アーカイブ済みコンタクト: HubSpotのゴミ箱にあるコンタクトはメールアドレスを予約したままのため、そのアドレスへのupsertは成功しません。ゴミ箱から復元するか、別のアドレスを使用してください。
• タイムアウト: すべてのリクエストに30秒のタイムアウトが設定されており、レート制限や一時的なサーバーエラーには自動でリトライします。