> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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認証情報ページ](/ja/pages/credentials/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` スコープが必要です。 |

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

```yaml theme={null}
- id: find_contact
  tool: HUBSPOT_GET_CONTACT
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: email
      value: "customer@example.com"
    - 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: "customer@example.com"
    - name: firstname
      value: "Ada"
    - name: lastname
      value: "Lovelace"
    - name: lifecyclestage
      value: "lead"
    - name: properties
      value: '{"hs_lead_status":"OPEN"}'
```

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

```yaml theme={null}
- 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"
```

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

```yaml theme={null}
- 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"
```

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

```yaml theme={null}
- 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秒のタイムアウトが設定されており、レート制限や一時的なサーバーエラーには自動でリトライします（ノート・タスクの作成は上記のとおり例外です）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.