HubSpot CRM データインポート完全ガイド：UI・API活用とCSV作成要件

1️⃣ UI インポート vs. API インポート ― いつどちらを選ぶべきか

選択指針
- UI が最適 → データ量が少なく、担当者が非エンジニアの場合。
- API が最適 → 定期的なインポート、外部システムと統合した自動化が必要な場合。

2️⃣ CSV/Excel ファイル作成の必須要件

2‑1️⃣ 公式テンプレートの入手方法（最新 UI に合わせた手順）

1. 設定 (Settings) → データ管理 (Data Management) → インポート (Imports)
2. ページ右上の 「サンプル CSV をダウンロード」 ボタンをクリック
3. ダウンロードしたファイルは、HubSpot が期待する列順・プロパティ ID がすでに記載されているので、作業シートのベースとして利用可能

※旧 UI の「データ連携」や「ファイルをインポート」は 2024 年度に統合されました。上記手順が現在の公式フローです。

3️⃣ UI インポート – 手順とポイント解説

複数オブジェクトの同時インポート & アソシエーション自動生成

• CSV 構成例（コンタクト + 企業）

company_domain が企業オブジェクトの 一意キー として扱われ、インポート完了時に自動で コンタクト ↔ 企業 のリンクが作成されます。

• 取引も同時にインポートしたい場合

associated_company_domain が取引と企業のアソシエーションキーとなります。
※「複合インポート」画面で 「オブジェクト間の関係を自動作成」 オプションを必ず有効にしてください。

4️⃣ カスタムプロパティの一括アップサートとエラーハンドリング

4‑1️⃣ 「新規作成」 vs. 「既存レコード更新」の選び方

4‑2️⃣ よくあるエラーと対策

エラーレポートは UI の インポート結果 → ダウンロード CSV から取得できます。ダウンロードしたファイルに errorMessage 列が付与されているので、原因特定が容易です。

5️⃣ API を使ったインポート – 完全フロー

5‑1️⃣ 認証とトークン取得

公式ドキュメント → https://developers.hubspot.com/docs/api/authentication

5‑2️⃣ ファイルアップロード（必須ステップ）

1. POST /files/v3/files にバイナリ CSV を送信
   bash
curl -X POST "https://api.hubapi.com/files/v3/files" \
-H "Authorization: Bearer <PRIVATE_APP_TOKEN>" \
-F "file=@contacts.csv;type=text/csv" \
-F "folderPath=/imports"
2. 成功するとレスポンスに id（＝ fileId）が返る
3. 取得した fileId を次のインポートジョブ作成リクエストで使用

※UI のインポートでは自動的にこの手順が内部で走りますが、API では 必ず先にアップロード が必要です。

5‑3️⃣ インポートジョブ作成

5‑4️⃣ ジョブステータス取得とポーリング

• status が COMPLETED、FAILED、CANCELLED のいずれかになるまで 30 秒ごとにポーリング
• 完了時は statistics にインポート件数・失敗件数が含まれる

5‑5️⃣ ロールバック / 再インポート手順

ベストプラクティス：大規模インポートは必ずテスト用のサンドボックス環境（もしくは「非公開」ステージングレコード）で 1 万件程度を先行実行し、エラー率とパフォーマンスを測定してから本番ジョブに移行。

6️⃣ インポート後のデータ検証フロー

1. 件数比較
   bash
curl -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"filterGroups":[{"filters":[{"propertyName":"email","operator":"HAS_PROPERTY"}]}],"limit":0}'
   → total がインポート前後で同じか確認。差分がある場合はエラーログを精査。

2. プロパティ整合性サンプリング

3. 重要カスタムプロパティ（例: lead_score, industry) の上位 100 件を取得し、元 CSV と突き合わせる。

4. 不一致が多い場合はマッピングミスやデータ型変換エラーの可能性。

5. アソシエーション検証（複合インポート時）
   bash
GET /crm/v3/objects/contacts/{contactId}/associations/company?limit=10
   → 期待した企業オブジェクトと正しくリンクしているか確認。

6. エラーログの永続化

7. GET /crm/v3/imports/{importId} のレスポンスに含まれる errorDetails を S3 や社内 DB に保存し、監査用レポートを自動生成。

7️⃣ まとめ ― UI と API の使い分けポイント

最終チェックリスト
1. ✅ UTF‑8 / カンマ区切りの CSV を使用したか。
2. ✅ 公式テンプレートと列名・必須プロパティが一致しているか。
3. ✅ UI ならエラーレポートを保存、API なら onError 設定でロールバックを有効化したか。
4. ✅ インポート完了後に件数・アソシエーションの整合性チェックを実施したか。

これらの手順とベストプラクティスを守れば、HubSpot CRM へのデータインポートは 正確かつ効率的 に行えます。質問や不明点があれば、HubSpot の公式サポートまたは開発者フォーラムをご利用ください。

本稿の数値・手順は執筆時点（2024 年 11 月）の HubSpot 公式情報に基づきます。最新の上限や UI 表示は随時変更される可能性があるため、導入前に必ず公式ナレッジベースをご確認ください。