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

# HubSpot

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

## 概要

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

## 主な機能

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

## 認証

設定手順については[HubSpot認証情報ページ](/ja/pages/credentials/hubspot)をご確認ください。

| 設定フィールド        | 説明                                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `access_token` | HubSpotのアクセストークン（ワークスペースのシークレットから選択）。`crm.objects.contacts.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"}'
```

## 入力パラメータ

### `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秒のタイムアウトが設定されており、レート制限や一時的なサーバーエラーには自動でリトライします。