インポート

インポートAPIは、コンタクト、会社などのCRMレコードをHubSpotアカウントにインポートする際に使用します。インポートされたレコードは、コンタクトAPI関連付けAPIなどのCRM APIエンドポイント経由でのアクセスと更新が可能です。レコードのインポートには、HubSpotのガイド付きインポートツールを使用することもできます。

インポートを開始する

インポートの処理は、インポートファイルの列をHubSpot上のどのCRMプロパティーに割り当てるかをリクエスト本文に指定したPOSTリクエストを/crm/v3/importsに送信することで、開始できます。

APIインポートはform-dataタイプのリクエストとして送信され、リクエスト本文には次のフィールドが含まれます。

  • importRequestリクエストのJSONを格納するテキストフィールド。
  • filesインポートファイルを格納するファイルフィールド。

以下のスクリーンショットに、Postmanなどのアプリを使用したリクエストの例を示します。postman-import-request-no-response0

リクエストヘッダーについては、値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_YEARYEAR_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プロパティー。

コンタクトをインポートする場合のリクエスト本文の例を以下に示します。

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] }# This example a local file named 'test_import.csv' # This file contains a list of contact records to import. import requests import json import os # insert your api key here url = "https://api.hubapi.com/crm/v3/imports?hapikey={{}}" data = { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } datastring = json.dumps(data) payload = {"importRequest": datastring} current_dir = os.path.dirname(__file__) relative_path = "./test_import.csv" absolute_file_path = os.path.join(current_dir, relative_path) files = [ ('files', open(absolute_file_path, 'r')) ] print(files) response = requests.request("POST", url, data=payload, files=files) print(response.text.encode('utf8')) print(response.status_code) # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat <<EOF { "name": "November Marketing Event Leads", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "dateFormat": "DAY_MONTH_YEAR", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname", "idColumnType": null }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "idColumnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } EOF ) curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ https://api.hubapi.com/crm/v3/imports?hapikey=4123...4321

リクエストが成功すると、インポートの取得またはキャンセルに使用できるimportIdを含むレスポンスが返されます。 

以前のインポートを取得する

HubSpotアカウントから全てのインポートを取得するには、/crm/v3/imports/GETリクエストを送信します。この記事の上部にある「エンドポイント」タブから、結果のページ処理と制限に関する詳細をご確認ください。

特定のインポートの情報を取得するには、/crm/v3/imports/{importId}GETリクエストを送信します。

インポートをキャンセルする

インポートをキャンセルするには、/crm/v3/imports/{importId}/cancelPOSTリクエストを送信します。 

インポートをトラブルシューティングする

特定のインポートのエラーを表示するには、/crm/v3/imports/{importId}/errorsGETリクエストを送信します。典型的なインポートエラーとその解決方法の詳細をご確認ください。

「JSONを解析できない」などの全般的なエラーについては、次の手順に従います。

  • インポートファイルの各列のcolumnMappingがリクエスト本文に含まれていることを確かめます。リクエスト本文とインポートファイルの列の順序が一致している必要があります。
  • ファイルの名前がリクエストのJSONのfileNameフィールドと一致していて、fileNameフィールドにファイル拡張子が含まれていることを確かめます(例:import_name.csv)。
  • multipart/form-dataの値が含まれるContent-Typeがヘッダーにあることを確かめます。

制限

インポートの上限として、1,048,576行または512 MBのうち、最初に到達した条件が適用されます。リクエストが行制限またはサイズ制限のいずれかを超えた場合、HubSpotから429 HTTPエラーが返されます。このような上限に近づいたら、インポートを複数のリクエストに分割することをお勧めします。  


参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。