インポート
インポートAPIは、コンタクト、会社などのCRMレコードをHubSpotアカウントにインポートする際に使用します。インポートされたレコードは、コンタクトAPIや関連付けAPIなどのCRM APIエンドポイント経由でのアクセスと更新が可能です。レコードのインポートには、HubSpotのガイド付きインポートツールを使用することもできます。
インポートを開始する
インポートの処理は、インポートファイルの列をHubSpot上のどのCRMプロパティーに割り当てるかをリクエスト本文に指定したPOST
リクエストを/crm/v3/imports
に送信することで、開始できます。
APIインポートはform-dataタイプのリクエストとして送信され、リクエスト本文には次のフィールドが含まれます。
- importRequest:リクエストのJSONを格納するテキストフィールド。
- files:インポートファイルを格納するファイルフィールド。
以下のスクリーンショットに、Postmanなどのアプリを使用したリクエストの例を示します。
リクエストヘッダーについては、値multipart/form-data
が含まれるContent-Type
ヘッダーを追加します。
importRequestデータの形式を整える
リクエストのJSONでは、インポートファイルの詳細(スプレッドシートの列のHubSpotデータに対するマッピングなど)を定義します。リクエストのJSONには次のフィールドを含める必要があります。
- name:インポートの名前。これはHubSpot上で、リストなどの他のツールで参照できる名前で、インポートツールにも表示される名前です。
- marketableContactImport:インポートファイルに含まれるコンタクトのマーケティングステータス。これは、マーケティングコンタクトの利用が可能なアカウントにコンタクトをインポートする場合にのみ、使用します。ファイル内のコンタクトをマーケティング対象として設定するには、
true
の値を使用します。ファイル内のコンタクトをマーケティング対象外として設定するには、false
の値を使用します。 - files:インポートファイルの情報を格納する配列。
- fileName:インポートファイルの名前。
- fileFormat:インポートファイルの形式。CSVファイルの場合に使用する値は
CSV
です。Excelファイルの場合に使用する値はSPREADSHEET
です。 - dateFormat:ファイルに含まれる日付の形式。これは、既定では
MONTH_DAY_YEAR
に設定されていますが、DAY_MONTH_YEAR
もYEAR_MONTH_DAY
も使用できます。 - fileImportPage:インポートファイルのデータをHubSpotデータにマッピングするために必要な
columnMappings
配列を格納します。列マッピングの詳細については、以下をご覧ください。
HubSpotプロパティーにファイルの列をマッピングする
columnMappings
配列内には、スプレッドシート内の順序に従ってインポートファイル内の各列を格納します。各列には、次のフィールドを格納します。
- columnObjectTypeId:データが存在するオブジェクトのタイプのID。カスタムオブジェクトの値は、カスタムオブジェクトAPIを使用して取得できます。標準オブジェクトの場合は、次の値を使用します。
- コンタクト:
0-1
- 会社:
0-2
- 取引:
0-3
- チケット:
0-5
- 注:
0-4
- コンタクト:
- columnName:列ヘッダーの名前。
- idColumnType:プロパティーデータを格納する列の場合に使用する値は
null
です。固有IDを格納する列の場合に使用する値は、次のうちのいずれかです。- HUBSPOT_OBJECT_ID:レコードのID。例えば、コンタクトのインポートファイルに、コンタクトを関連付ける会社のIDを格納した「会社ID」列を含めるケースが考えられます。
- HUBSPOT_ALTERNATE_ID:レコードID以外の固有ID。例えば、コンタクトのインポートファイルに、コンタクトのEメールアドレスを格納した「Eメール」列を含めるケースが考えられます。
- propertyName:データのマッピング先のHubSpotプロパティー。
コンタクトをインポートする場合のリクエスト本文の例を以下に示します。
リクエストが成功すると、インポートの取得またはキャンセルに使用できるimportId
を含むレスポンスが返されます。
以前のインポートを取得する
HubSpotアカウントから全てのインポートを取得するには、/crm/v3/imports/
にGET
リクエストを送信します。この記事の上部にある「エンドポイント」タブから、結果のページ処理と制限に関する詳細をご確認ください。
特定のインポートの情報を取得するには、/crm/v3/imports/{importId}
にGET
リクエストを送信します。
インポートをキャンセルする
インポートをキャンセルするには、/crm/v3/imports/{importId}/cancel
にPOST
リクエストを送信します。
特定のインポートのエラーを表示するには、/crm/v3/imports/{importId}/errors
にGET
リクエストを送信します。典型的なインポートエラーとその解決方法の詳細をご確認ください。
「JSONを解析できない」などの全般的なエラーについては、次の手順に従います。
- インポートファイルの各列の
columnMapping
がリクエスト本文に含まれていることを確かめます。リクエスト本文とインポートファイルの列の順序が一致している必要があります。 - ファイルの名前がリクエストのJSONの
fileName
フィールドと一致していて、fileName
フィールドにファイル拡張子が含まれていることを確かめます(例:import_name.csv)。 multipart/form-data
の値が含まれるContent-Type
がヘッダーにあることを確かめます。
インポートの上限として、1,048,576行または512 MBのうち、最初に到達した条件が適用されます。リクエストが行制限またはサイズ制限のいずれかを超えた場合、HubSpotから429 HTTPエラーが返されます。このような上限に近づいたら、インポートを複数のリクエストに分割することをお勧めします。
貴重なご意見をありがとうございました。