HubSpot

HubSpot CRMのコンタクトを作成・更新・取得、取引を取得・検索、会社と担当者を取得、取引にノートとタスクを記録

​

概要

HubSpotツールはHubSpot CRM APIと連携し、ワークフローからコンタクトの管理と取引（Deal）の参照を行います。コンタクトツールはメールアドレスをキーにするため、Search API（レート制限あり）を経由せずにレコードを照合できます。取引ツールはIDでの取得のほか、名前・ステージ・担当者・クローズ予定日・作成日・任意のプロパティで検索できます。会社・担当者ツールは取引が持つID（関連会社、hubspot_owner_id）を会社名・ドメイン・メールアドレスに解決し、ノート・タスクツールは取引自体を変更せずにエンゲージメントを取引へ紐付けます。

​

主な機能

• HUBSPOT_UPSERT_CONTACT
  • コンタクトを作成します。同じメールアドレスのコンタクトが既にある場合は更新します。カスタムプロパティにも対応しています。
• HUBSPOT_GET_CONTACT
  • オブジェクトIDまたはメールアドレスでコンタクトを取得します。該当するコンタクトがない場合はエラーにせず found: false を返します。
• HUBSPOT_GET_DEAL
  • オブジェクトIDで取引を取得します。関連するコンタクト・会社のIDも合わせて取得できます。該当する取引がない場合はエラーにせず found: false を返します。
• HUBSPOT_SEARCH_DEALS
  • 名前・ステージ・パイプライン・担当者・クローズ予定日や作成日の範囲で取引を検索します。フリーテキスト検索と任意プロパティのフィルタにも対応し、ページ分割で返します。
• HUBSPOT_GET_COMPANY
  • オブジェクトIDで会社を取得します。関連するコンタクト・取引のIDも合わせて取得できます。該当する会社がない場合はエラーにせず found: false を返します。
• HUBSPOT_GET_OWNER
  • 担当者IDまたはメールアドレスで担当者を取得し、氏名・メールアドレス・ユーザーIDを返します。該当する担当者がない場合はエラーにせず found: false を返します。
• HUBSPOT_LIST_OWNERS
  • アカウントの担当者を一覧します。メールアドレスでの絞り込みや、アーカイブ済み担当者のみの取得もできます。ページ分割で返します。
• HUBSPOT_CREATE_NOTE
  • ノートを作成して取引・コンタクト・会社に紐付けます。タイムスタンプと作成者を指定できます。
• HUBSPOT_CREATE_TASK
  • 期限・ステータス・優先度・担当者を指定してタスクを作成し、取引・コンタクト・会社に紐付けます。

​

認証

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

設定フィールド	説明
access_token	HubSpotのアクセストークン（ワークスペースのシークレットから選択）。コンタクトツールには crm.objects.contacts.read と crm.objects.contacts.write、取引ツールには crm.objects.deals.read、HUBSPOT_GET_COMPANY には crm.objects.companies.read、担当者ツールには crm.objects.owners.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"}'

​

例: 担当者の今月クローズ予定の取引を一覧する

- id: search_deals
  tool: HUBSPOT_SEARCH_DEALS
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: owner_id
      value: "12345678"
    - name: close_date_from
      value: "2026-09-01T00:00:00+09:00"
    - name: close_date_to
      value: "2026-09-30T23:59:59+09:00"
    - name: sort_by
      value: "amount"
    - name: sort_direction
      value: "descending"
    - name: properties
      value: "dealname, amount, dealstage, closedate"
- id: get_deal
  tool: HUBSPOT_GET_DEAL
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: deal_id
      value: "{{steps.search_deals.result.deals[0].id}}"
    - name: associations
      value: "contacts, companies"

​

例: 新規取引の担当者と会社を解決する

- id: search_deals
  tool: HUBSPOT_SEARCH_DEALS
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: create_date_from
      value: "2026-09-30T09:00:00+09:00"
    - name: sort_by
      value: "createdate"
    - name: sort_direction
      value: "ascending"
- id: get_deal
  tool: HUBSPOT_GET_DEAL
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: deal_id
      value: "{{steps.search_deals.result.deals[0].id}}"
    - name: associations
      value: "contacts, companies"
- id: get_owner
  tool: HUBSPOT_GET_OWNER
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: owner_id
      value: "{{steps.get_deal.result.properties.hubspot_owner_id}}"
- id: get_company
  tool: HUBSPOT_GET_COMPANY
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: company_id
      value: "{{steps.get_deal.result.associations.companies.results[0].id}}"
    - name: properties
      value: "name, domain, industry, city"

​

例: 取引に商談メモとフォローアップタスクを記録する

- id: create_note
  tool: HUBSPOT_CREATE_NOTE
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: deal_id
      value: "98765432"
    - name: body
      value: "<p><strong>Meeting 2026-10-01</strong></p><p>Reviewed pricing. Customer will confirm budget by next week.</p>"
- id: create_task
  tool: HUBSPOT_CREATE_TASK
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: deal_id
      value: "98765432"
    - name: subject
      value: "Follow up on budget confirmation"
    - name: due_date
      value: "2026-10-08T09:00:00+09:00"
    - name: priority
      value: "HIGH"
    - name: owner_id
      value: "12345678"

​

入力パラメータ

​

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_DEAL

パラメータ	必須	説明
deal_id	○	HubSpotの取引オブジェクトID（取引URLに含まれる数字、または HUBSPOT_SEARCH_DEALS が返す id）。
properties		取得するプロパティ名をカンマ区切りで指定します（例: dealname, amount, dealstage）。デフォルトは dealname, amount, dealstage, pipeline, closedate, hubspot_owner_id です。
associations		関連レコードのIDも取得するオブジェクト種別をカンマ区切りで指定します（例: contacts, companies）。

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

​

HUBSPOT_SEARCH_DEALS

すべて任意です。名前付きの条件はAND で結合されます。

パラメータ	説明
query	フリーテキスト検索。取引名などのデフォルト検索対象プロパティに前方一致で照合します。
deal_name	取引名の単語単位の一致（例: renewal は「Acme renewal 2026」に一致しますが、renew は一致しません）。* を付けると単語の前方一致になります（renew*）。キーワードでざっくり探す場合は query を使ってください。
deal_stage	取引ステージの内部ID（例: appointmentscheduled, closedwon、カスタムステージは数値ID）。
pipeline	パイプラインの内部ID（例: default、カスタムパイプラインは数値ID）。
owner_id	HubSpotの担当者ID（hubspot_owner_id）。設定 → ユーザーに表示されるユーザーIDとは別の値です。
close_date_from, close_date_to	クローズ予定日の範囲。取引の closedate のタイムスタンプに対して >= / <= で比較します。ISO 8601の日付または日時。時刻のない日付はUTCの0時として扱うため、close_date_to: "2026-09-30" ではその日の0時以降にクローズする取引は含まれません。その日全体を含めるには 2026-09-30T23:59:59+09:00 のように終了時刻を明示してください。
create_date_from, create_date_to	作成日の範囲。取引の createdate に対して比較します。形式と「時刻のない日付はその日の0時」という注意点はクローズ予定日と同じです。前回の実行以降に作成された取引だけを拾うには、前回実行時刻を create_date_from に渡してください。
filters	追加フィルタを {"propertyName","operator","value"} オブジェクトのJSON配列で指定します（例: [{"propertyName":"amount","operator":"GTE","value":"10000"}]）。演算子: EQ, NEQ, LT, LTE, GT, GTE, BETWEEN（value + highValue）, IN / NOT_IN（values 配列）, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN。
properties	各取引について返すプロパティ名をカンマ区切りで指定します。デフォルトは HUBSPOT_GET_DEAL と同じです。
sort_by	並び替えに使うプロパティ（例: createdate, closedate, amount）。
sort_direction	descending（降順、デフォルト）または ascending（昇順）。sort_by を指定したときだけ使われます。
limit	1ページあたりの件数（1〜200）。デフォルトは20です。
after	前回の結果の next_after を渡すと次のページを取得します。

出力は result.deals（各要素に id と properties）、result.count、result.total、result.next_after（最終ページでは null）です。

​

HUBSPOT_GET_COMPANY

パラメータ	必須	説明
company_id	○	HubSpotの会社オブジェクトID（会社URLに含まれる数字、または HUBSPOT_GET_DEAL の associations.companies に含まれるID）。
properties		取得するプロパティ名をカンマ区切りで指定します（例: name, domain, industry）。デフォルトは name, domain, industry, city, hubspot_owner_id です。
associations		関連レコードのIDも取得するオブジェクト種別をカンマ区切りで指定します（例: contacts, deals）。

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

​

HUBSPOT_GET_OWNER

パラメータ	必須	説明
owner_id	どちらか一方	HubSpotの担当者ID（取引やコンタクトの hubspot_owner_id）。設定 → ユーザーに表示されるユーザーIDとは別の値です。
email	どちらか一方	担当者のメールアドレス。

出力は result.found / result.id / result.email / result.first_name / result.last_name / result.user_id / result.archived と、生のレスポンス result.owner です。

​

HUBSPOT_LIST_OWNERS

すべて任意です。

パラメータ	説明
email	このメールアドレスの担当者だけを返します。
archived	active（デフォルト）または archived。HubSpotはどちらか一方のみを返し、両方を同時には返しません。
limit	1ページあたりの件数（1〜500）。デフォルトは100です。
after	前回の結果の next_after を渡すと次のページを取得します。

出力は result.owners（各要素に id、email、first_name、last_name、user_id、archived）、result.count、result.next_after（最終ページでは null）です。

​

HUBSPOT_CREATE_NOTE

パラメータ	必須	説明
body	○	ノート本文。プレーンテキストまたは簡単なHTML。最大65,536文字。
deal_id, contact_id, company_id	いずれか1つ以上	ノートを紐付けるレコード。指定したすべてのレコードに関連付けられます。
timestamp		ノートの記録日時。ISO 8601またはエポックミリ秒。デフォルトは現在時刻です。
owner_id		作成者として記録するHubSpotの担当者ID。空の場合は未設定のままになります（サービスキーや非公開アプリのトークンには固有のユーザーがありません）。
properties		その他のエンゲージメントプロパティを「内部名 → 値」のJSONオブジェクトで指定します。キーが重複した場合、名前付きパラメータが properties より優先されます。

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

​

HUBSPOT_CREATE_TASK

パラメータ	必須	説明
subject	○	タスクのタイトル。
due_date	○	タスクの期限。ISO 8601またはエポックミリ秒。HubSpotではすべてのタスクに期限が必須です。
deal_id, contact_id, company_id	いずれか1つ以上	タスクを紐付けるレコード。指定したすべてのレコードに関連付けられます。
body		タスクの説明。プレーンテキストまたは簡単なHTML。
status		NOT_STARTED（デフォルト）, IN_PROGRESS, WAITING, COMPLETED, DEFERRED。
priority		LOW, MEDIUM, HIGH。指定しない場合は未設定のままです。
task_type		TODO（デフォルト）, EMAIL, CALL。
owner_id		タスクを割り当てるHubSpotの担当者ID。空の場合は未割り当てのタスクになります。
properties		その他のエンゲージメントプロパティを「内部名 → 値」のJSONオブジェクトで指定します。キーが重複した場合、名前付きパラメータが properties より優先されます。

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

​

備考

• 該当なしはエラーではない: HUBSPOT_GET_CONTACT、HUBSPOT_GET_DEAL、HUBSPOT_GET_COMPANY、HUBSPOT_GET_OWNER はレコードが見つからない場合に result.found = false を返します。「検索して、なければ作成する」を通常の条件分岐ステップとして組めます。
• ノートとタスクは取引を編集しない: エンゲージメントは独立したレコードで、指定した取引・コンタクト・会社に関連付けられます。取引自体のフィールドは書き換えませんが、HubSpot がアクティビティ由来のプロパティ（最終アクティビティ日など）を更新するため、それらを条件にしたワークフローには影響します。Engagements API が作成に必要と案内しているスコープは crm.objects.contacts.write で、crm.objects.deals.write ではありません。
• エンゲージメントの日時: timestamp と due_date はISO 8601またはエポックミリ秒を受け付けます。時刻のない日付はUTCの0時として扱うため、時刻が重要な場合はオフセット付きで時刻を明示してください（2026-10-08T09:00:00+09:00）。
• ツールは作成をリトライしない: ノートやタスクの作成の HTTP 呼び出しは、失敗の理由を問わずツール自身は再送しません（再送するとレコードが二重に作成される可能性があるためです）。ステップに retry を設定した場合、429 のような明確な拒否の後はステップが再実行されますが、結果が不明な失敗（ツール内でのタイムアウト、接続断、HubSpot の 5xx）ではステップ側の retry も適用されません。ただし 1 点注意: ステップの timeout がリクエスト途中で発火した場合はツールでなくランナーがエラーを出すため、他のエラーと同様にリトライされます。そのようなステップには retry を付けないか、ステップの timeout をツール自身の 30 秒より十分長くしてください。ステップを再実行する前に、HubSpot上でレコードが作成されていないか確認してください。
• 担当者IDとユーザーIDの違い: hubspot_owner_id は設定 → ユーザーに表示されるユーザーIDとは別の値です。担当者IDから氏名・メールアドレスを引くには HUBSPOT_GET_OWNER、特定の人の担当者IDを探すには HUBSPOT_LIST_OWNERS を使ってください。
• 検索の制限: HubSpotの検索は1リクエストあたり最大6フィルタ（名前付き条件と filters の合計）、1ページ最大200件、1クエリ最大10,000件で、Search APIにはアカウントあたり毎秒5リクエストの独立したレート制限があります。検索インデックスは書き込みから数秒遅れることがあるため、直前に作成した取引が含まれない場合があります。
• 日付プロパティ: HubSpotの closedate と createdate は日時型です。範囲指定の入力はエポックミリ秒へ自動変換されます。filters の値はそのまま送られるため、エポックミリ秒で指定するのが確実です。
• 差分取得: create_date_from は「以上」（>=）で比較します。前回実行で取得した最新取引の createdate をそのまま渡すと、その取引が再度返るため、後続で id による重複排除をしてください。
• 同時書き込みは後勝ち: HubSpotのCRM APIには楽観的ロックの仕組みがないため、更新が重なるとプロパティ単位で後勝ちになります。実行が重なりうる状況で「スコアを読んで加算して書き戻す」といった処理に HUBSPOT_UPSERT_CONTACT を使わないでください（HubSpotの計算プロパティを利用してください）。
• アーカイブ済みコンタクト: HubSpotのゴミ箱にあるコンタクトはメールアドレスを予約したままのため、そのアドレスへのupsertは成功しません。ゴミ箱から復元するか、別のアドレスを使用してください。
• タイムアウト: すべてのリクエストに30秒のタイムアウトが設定されており、レート制限や一時的なサーバーエラーには自動でリトライします（ノート・タスクの作成は上記のとおり例外です）。