HubSpot API入門ガイド｜認証・コンタクト取得・取引操作の基本をコード例付きで解説

「HubSpotのデータを外部システムと連携したい」「定型的な処理をAPIで自動化したい」——こうしたニーズが出てきたとき、最初の一歩となるのがHubSpot APIの理解です。

HubSpot APIとは、HubSpotのCRMデータや各種機能にプログラムからアクセスするためのインターフェースです。RESTful APIとして提供されており、コンタクト・会社・取引などのCRMオブジェクトの作成・取得・更新・削除（CRUD）や、マーケティング・セールス機能の操作が可能です。

この記事では、HubSpot APIの認証方法からコンタクト取得・取引操作の基本まで、実際のコード例付きで解説します。

この記事でわかること

• HubSpot APIの認証方式（プライベートアプリ・OAuth）の違いと設定方法
• コンタクトの取得・作成・更新のAPI操作とコード例
• 取引（Deals）の操作方法
• APIのレート制限と注意点
• 実務での活用パターン

HubSpot APIの全体像

出典: HubSpot Developers (developers.hubspot.com)

APIの種類

HubSpot APIは、大きく以下のカテゴリに分かれています。

公式ドキュメント

HubSpot APIの公式ドキュメントは developers.hubspot.com で公開されています。各エンドポイントの仕様、リクエスト例、レスポンス例が記載されていますので、開発時には必ず参照いただくことをおすすめします。

認証方式｜プライベートアプリとOAuth

出典: HubSpot Developers (developers.hubspot.com)

旧APIキーは廃止済み

HubSpotでは以前「APIキー」による認証方式が提供されていましたが、2022年11月30日をもって廃止されました。現在は以下の2つの方式を使用します。

方式1：プライベートアプリ（Private App）

プライベートアプリは、自社内部での利用に最適な認証方式です。アクセストークンを発行し、APIリクエストのヘッダーに含めるだけで認証が完了します。

設定手順は以下のとおりです。

1. HubSpotにログインし、歯車マーク（設定）をクリック
2. 左メニューから「連携」→「プライベートアプリ」を選択
3. 「プライベートアプリを作成」をクリック
4. アプリ名を入力し、必要なスコープ（権限）を選択
5. 「アプリを作成」をクリックしてアクセストークンを取得

アクセストークンの使い方は以下のとおりです。

curl --request GET \
  --url 'https://api.hubapi[dot]com/crm/v3/objects/contacts?limit=10' \
  --header 'authorization: Bearer [YOUR_TOKEN]'

プライベートアプリでは必要最小限のスコープのみを付与いただくのがセキュリティ上のベストプラクティスです。例えばコンタクトの読み取りだけが必要な場合、crm.objects.contacts.readのみを選択します。

方式2：OAuth 2.0

OAuthは、外部のサードパーティアプリや公開アプリで使用する認証方式です。ユーザーの同意を得た上でアクセストークンを取得するフローになります。

社内ツールや自社の管理スクリプトであれば、プライベートアプリの方がシンプルでおすすめです。マーケットプレイスに公開するアプリや、複数のHubSpotアカウントに対応する必要がある場合はOAuthを使用します。

Salesforceでいう「Connected App」に近い概念ですが、HubSpotのプライベートアプリの方が設定はシンプルかなと思います。

コンタクトAPIの基本操作

出典: HubSpot Developers (developers.hubspot.com)

コンタクト一覧の取得

コンタクト一覧を取得する基本的なAPIリクエストです。

curl --request GET \
  --url 'https://api.hubapi[dot]com/crm/v3/objects/contacts?limit=10&properties=firstname,lastname,email,company' \
  --header 'authorization: Bearer [YOUR_TOKEN]'

Pythonでの実装例：

import requests

BASE_URL = "https://api.hubapi[dot]com"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

headers = {
    "authorization": f"Bearer {ACCESS_TOKEN}",
    "content-type": "application/json"
}

# コンタクト一覧取得
response = requests.get(
    f"{BASE_URL}/crm/v3/objects/contacts",
    headers=headers,
    params={
        "limit": 10,
        "properties": "firstname,lastname,email,company"
    }
)

data = response.json()
for contact in data.get("results", []):
    props = contact.get("properties", {})
    print(f"{props.get('firstname')} {props.get('lastname')} - {props.get('email')}")

propertiesパラメータで取得したいプロパティを指定します。指定しない場合はデフォルトのプロパティのみが返されます。

特定のコンタクトを取得

コンタクトIDまたはメールアドレスで特定のコンタクトを取得できます。

# IDで取得
contact_id = "12345"
response = requests.get(
    f"{BASE_URL}/crm/v3/objects/contacts/{contact_id}",
    headers=headers,
    params={"properties": "firstname,lastname,email,phone,company"}
)

# メールアドレスで取得
email = "example@company.com"
response = requests.get(
    f"{BASE_URL}/crm/v3/objects/contacts/{email}",
    headers=headers,
    params={
        "idProperty": "email",
        "properties": "firstname,lastname,email,company"
    }
)

コンタクトの作成

新しいコンタクトを作成するリクエストです。

new_contact = {
    "properties": {
        "firstname": "太郎",
        "lastname": "山田",
        "email": "taro.yamada@example.com",
        "company": "サンプル株式会社",
        "phone": "03-1234-5678"
    }
}

response = requests.post(
    f"{BASE_URL}/crm/v3/objects/contacts",
    headers=headers,
    json=new_contact
)

if response.status_code == 201:
    print(f"コンタクト作成成功: ID={response.json()['id']}")

コンタクトの更新

既存コンタクトのプロパティを更新します。

contact_id = "12345"
update_data = {
    "properties": {
        "company": "新会社名株式会社",
        "lifecyclestage": "marketingqualifiedlead"
    }
}

response = requests.patch(
    f"{BASE_URL}/crm/v3/objects/contacts/{contact_id}",
    headers=headers,
    json=update_data
)

コンタクトの検索

条件を指定してコンタクトを検索できます。

search_body = {
    "filterGroups": [{
        "filters": [{
            "propertyName": "company",
            "operator": "EQ",
            "value": "サンプル株式会社"
        }]
    }],
    "properties": ["firstname", "lastname", "email", "company"],
    "limit": 20
}

response = requests.post(
    f"{BASE_URL}/crm/v3/objects/contacts/search",
    headers=headers,
    json=search_body
)

検索APIには認証トークン1つにつき1秒あたり4リクエストという制限がありますので、大量の検索処理を行う場合はレート制限に注意が必要です。

取引（Deals）APIの操作

取引一覧の取得

response = requests.get(
    f"{BASE_URL}/crm/v3/objects/deals",
    headers=headers,
    params={
        "limit": 10,
        "properties": "dealname,amount,dealstage,closedate,pipeline"
    }
)

取引の作成

new_deal = {
    "properties": {
        "dealname": "サンプル株式会社 - CRM導入案件",
        "amount": "1000000",
        "dealstage": "appointmentscheduled",
        "pipeline": "default",
        "closedate": "2026-03-31T00:00:00.000Z"
    }
}

response = requests.post(
    f"{BASE_URL}/crm/v3/objects/deals",
    headers=headers,
    json=new_deal
)

取引とコンタクトの関連付け

HubSpotではオブジェクト間の関連付け（Association）が重要です。取引を作成したら、該当するコンタクトや会社と関連付けることで、データのリレーションが構築されます。

deal_id = "67890"
contact_id = "12345"

response = requests.put(
    f"{BASE_URL}/crm/v3/objects/deals/{deal_id}/associations/contacts/{contact_id}/deal_to_contact",
    headers=headers
)

バッチ操作で効率化する

複数のレコードを一度に処理する場合、バッチAPIを使用すると効率的です。各カテゴリのAPIには、1回のリクエストで最大10件のCRUD操作が可能なバッチコマンドが用意されています。

# コンタクトの一括作成
batch_contacts = {
    "inputs": [
        {
            "properties": {
                "firstname": "太郎",
                "lastname": "田中",
                "email": "tanaka@example.com"
            }
        },
        {
            "properties": {
                "firstname": "花子",
                "lastname": "鈴木",
                "email": "suzuki@example.com"
            }
        }
    ]
}

response = requests.post(
    f"{BASE_URL}/crm/v3/objects/contacts/batch/create",
    headers=headers,
    json=batch_contacts
)

大量のデータインポートが必要な場合は、API経由よりもHubSpotのインポート機能（CSVアップロード）を使った方が効率的なケースもあります。数百件程度ならAPI、数千〜数万件ならインポート機能を検討いただくのがいいかなと思います。

APIのレート制限と注意点

レート制限

HubSpot APIには以下のレート制限があります。

レート制限に達すると429 Too Many Requestsエラーが返されます。大量処理を行う場合は、リクエスト間にスリープを入れるなどの制御が必要です。

よくあるエラーと対処法

セキュリティ上の注意

• アクセストークンをソースコードに直接記述しない（環境変数やシークレット管理を使用）
• 不要になったプライベートアプリは削除する
• 必要最小限のスコープのみを付与する
• 本番データに対する操作は十分テストしてから実行する

実務での活用パターン

パターン1：外部フォームからのリード取り込み

自社のカスタムフォームやLPからHubSpotにコンタクトを自動登録する仕組みです。フォーム送信時にAPIでコンタクト作成→ライフサイクルステージ設定→担当者割り当てまでを自動化できます。

パターン2：基幹システムとのデータ同期

ERPや販売管理システムとHubSpotの間で、顧客情報や取引データを同期します。定期的にAPIで差分データを取得・更新するバッチ処理を組むパターンが一般的です。

パターン3：レポート・ダッシュボードの自動生成

HubSpotのデータをAPIで取得し、BIツールやスプレッドシートに流し込んで独自のレポートを生成します。HubSpot標準のレポートでは不足する分析が必要な場合に有効です。

なお、iPaaS（YoomやZapierなど）を使えば、コードを書かずにHubSpotと外部システムを連携できる場合もあります。ノーコードで対応可能な範囲はiPaaSを活用し、複雑なロジックが必要な場合にAPIを使うという切り分けが効率的です。

まとめ

HubSpot APIを活用することで、CRMデータの外部連携や業務の自動化が実現できます。

1. 認証：プライベートアプリでアクセストークンを発行（社内利用はこれで十分）
2. 基本操作：GET/POST/PATCHでCRMオブジェクトのCRUD
3. 検索：Search APIで条件指定のデータ取得
4. バッチ処理：複数レコードの一括操作で効率化
5. 関連付け：オブジェクト間のAssociationでデータのリレーション構築

まずはプライベートアプリの作成とコンタクトの取得から始めて、段階的にAPIの活用範囲を広げていきましょう。CRMのデータを外部システムと連携できるようになると、業務全体の効率化と自動化の幅が大きく広がります。

よくある質問（FAQ）

Q1. HubSpot APIを使うのに追加費用はかかりますか？

HubSpot APIの利用自体は無料プランを含む全プランで可能です。ただし、プランによって利用できるAPIの範囲やレート制限が異なります。また、ワークフローやカスタムオブジェクトなど一部の機能はProfessional以上のプランで利用可能です。

Q2. プライベートアプリとOAuth、どちらを選ぶべきですか？

自社内部のデータ連携やスクリプトであれば、プライベートアプリがシンプルでおすすめです。マーケットプレイスへの公開や、他社のHubSpotアカウントにアクセスする必要がある場合はOAuthを選択してください。

Q3. PythonとNode.js、どちらが適していますか？

HubSpotは公式のクライアントライブラリとして、Python（hubspot-api-client）、Node.js（@hubspot/api-client）、Ruby、PHPを提供しています。どちらも十分に使えますが、データ処理やスクリプトにはPython、ウェブアプリケーションやリアルタイム処理にはNode.jsが向いているケースが多いかなと思います。

Q4. APIでデータを更新する際、ワークフローは発火しますか？

はい、APIによるプロパティ更新でもワークフローのトリガー条件に該当すればワークフローが発火します。大量データのインポートやバッチ更新を行う際は、意図しないワークフロー発火に注意が必要です。事前にテスト環境（サンドボックス）で確認いただくのがおすすめです。

Q5. レート制限に引っかからないようにするには？

リクエスト間に適切なスリープ（例：0.1秒）を入れる、バッチAPIを活用して1リクエストで複数レコードを処理する、検索APIの利用は1秒4リクエストを超えないよう制御するといった対策が有効です。