インポート

概要エンドポイント

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

インポートを開始する前に、インポートできるオブジェクトとアクティビティー、およびファイルとプロパティーの要件について詳しくご確認ください。

インポートを開始する

インポートを開始するには、POSTリクエストを/crm/v3/importsに送信します。その際、インポートファイルの列をHubSpot上の関連するCRMプロパティーに割り当てる方法をリクエスト本文で指定します。

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

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

リクエストヘッダーについては、値multipart/form-dataが含まれるContent-Typeヘッダーを追加します。

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

postman-import-request-no-response0

importRequestデータの形式を整える

リクエストのJSONでは、インポートファイルの詳細（スプレッドシートの列のHubSpotデータに対するマッピングなど）を定義します。リクエストのJSONには次のフィールドを含める必要があります。

  • name：インポートの名前。これはHubSpot上で、リストなどの他のツールで参照できる名前で、インポートツールにも表示される名前です。
  • importOperations：このオプションフィールドを使用して、インポートで特定のオブジェクトやアクティビティーのレコードの作成と更新、作成のみ、または更新のみのどれを行うかを指示します。オブジェクト／アクティビティーのobjectTypeIdを指定し、レコードのUPSERT（作成と更新）、CREATE、またはUPDATEを行うことを指定します。例えばリクエストのフィールドは次のようになります："importOperations": {"0-1": "CREATE"}.
  • dateFormat：ファイルに含まれる日付の形式。これは既定ではMONTH_DAY_YEARに設定されていますが、DAY_MONTH_YEARまたはYEAR_MONTH_DAYも使用できます。
  • marketableContactImport：インポートファイルに含まれるコンタクトのマーケティングステータス。これは、マーケティングコンタクトの利用が可能なアカウントにコンタクトをインポートする場合にのみ、使用します。ファイル内のコンタクトをマーケティング対象として設定するには、trueの値を使用します。ファイル内のコンタクトをマーケティング対象外として設定するには、falseの値を使用します。 
  • files：インポートファイルの情報を格納する配列。
    • fileName：インポートファイルの名前。
    • fileFormat：インポートファイルの形式。CSVファイルの場合に使用する値はCSVです。Excelファイルの場合に使用する値はSPREADSHEETです。
    • fileImportPage：インポートファイルのデータをHubSpotデータにマッピングするために必要なcolumnMappings配列を格納します。列マッピングの詳細については、以下をご覧ください。

HubSpotプロパティーにファイルの列をマッピングする

columnMappings配列内には、スプレッドシート内の順序に従ってインポートファイル内の各列を格納します。各列には、次のフィールドを格納します。

  • columnObjectTypeId：データが属するオブジェクトまたはアクティビティーの名前またはobjectTypeId値。objectTypeId値の一覧については、こちらの記事をご覧ください。
  • columnName：列ヘッダーの名前。
  • propertyName：データのマッピング先となるHubSpotプロパティーの内部名。
  • columnType：これを使用して、列に一意の識別子プロパティーが含まれることを指定します。プロパティーに応じて、次のいずれかの値を使用します。
    • HUBSPOT_OBJECT_ID：レコードのID。例えば、コンタクトのインポートファイルに、コンタクトに関連付けられる会社のIDを格納する「レコードID」列を含めるケースが考えられます。
    • HUBSPOT_ALTERNATE_ID：レコードID以外の固有ID。例えば、コンタクトのインポートファイルに、コンタクトのEメールアドレスを格納した「Eメール」列を含めるケースが考えられます。

以下は、コンタクトを作成するためのインポートのリクエスト本文の例です。

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "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 url = "https://api.hubapi.com/crm/v3/imports" YOUR_ACCESS_TOKEN = 'xxxxxxx'; # Content-Type header will be set automatically by the requests library headers = { 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } data = { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": True, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "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, 'rb')) ] print(files) response = requests.request("POST", url, data=payload, files=files, headers=headers) 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", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "import_file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } EOF ) YOUR_ACCESS_TOKEN="xxx-xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \ https://api.hubapi.com/crm/v3/imports

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

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

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

インポートを取得すると、インポートの名前、ソース、ファイル形式、言語、日付形式、列マッピングなどの情報が返されます。また、インポートのstateも返されます。これは次のいずれかです。

  • STARTED：HubSpotはインポートが存在することを認識していますが、インポートの処理はまだ開始されていません。
  • PROCESSING：インポートがアクティブに処理されています。
  • DONE：インポートは完了済みです。全てのオブジェクト、アクティビティー、または関連付けが更新または作成されました。
  • FAILED：インポートの開始時に検出されなかったエラーがありました。インポートは完了しませんでした。
  • CANCELED：エクスポートがSTARTED、PROCESSING、DEFERREDのいずれかの状態だったときに、ユーザーがエクスポートをキャンセルしました。
  • DEFERRED：最大数（3件）のインポートが同時に処理されています。他のインポートの1つの処理が終了すると、インポートが開始されます。

この記事の上部にある「エンドポイント」タブから、結果のページ処理と制限に関する詳細をご確認ください。

注：非公開アプリ アクセス トークンを使用してインポートを取得する場合、応答にはその非公開アプリによって実行されたインポートのみが含まれます。HubSpotまたは別の非公開アプリを介して完了したインポートは返されません。

Cancel an import

To cancel an active import, make a POST request to /crm/v3/imports/{importId}/cancel. 

View and troubleshoot import errors

To view errors for a specific import, make a GET request to /crm/v3/imports/{importId}/errors. Learn more about common import errors and how to resolve them.

For more general errors, such as Unable to parse JSON or 404 text/html is not accepted:

  • Ensure that there is a column header for each column in your file, and that the request body contains a columnMapping entry for each column. The column order in the request body and import file should match, and every column needs to be mapped.
  • Ensure that the file's name and the fileName field in your request JSON match, and that you've included the file extension in the fileName field. For example, import_name.csv.
  • Ensure that your header includes Content-Type with a value of multipart/form-data.

注：エラーが発生する場合は、Content-Typeなどの重複するヘッダーがあるかどうかを確認してください。これが発生する可能性があるのは、Postmanを使用している場合、またはPythonスクリプトのヘッダーにそれが含まれている場合です。リクエストを完了する前に重複を削除してください。 

制限

インポートAPIを使用すると、1日あたり最大80,000,000行をインポートできます。ただし、個々のインポートファイルの上限として、1,048,576行または512MBのうち最初に到達した条件が適用されます。

リクエストが行制限またはサイズ制限のいずれかを超えた場合、HubSpotから429 HTTPエラーが返されます。このような上限に近づいたら、インポートを複数のリクエストに分割することをお勧めします。  

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