インポート

インポート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"}.このフィールドを含めない場合、インポートに使用されるデフォルト値はUPSERTです。
  • dateFormat:ファイルに含まれる日付の形式。これは既定ではMONTH_DAY_YEARに設定されていますが、DAY_MONTH_YEARまたはYEAR_MONTH_DAYも使用できます。
  • marketableContactImport:インポートファイルに含まれるコンタクトのマーケティングステータスを示す任意指定のフィールド。これは、マーケティングコンタクトの利用が可能なアカウントにコンタクトをインポートする場合にのみ、使用します。ファイル内のコンタクトをマーケティング対象として設定するには、trueの値を使用します。ファイル内のコンタクトをマーケティング対象外として設定するには、falseの値を使用します。 
  • createContactListFromImport:インポートからコンタクトの静的リストを作成するための任意指定のフィールド。ファイルからリストを作成するには、trueの値を使用します。
  • files:インポートファイルの情報を格納する配列。
    • fileName:インポートファイルの名前。
    • fileFormat:インポートファイルの形式。CSVファイルの場合に使用する値はCSVです。Excelファイルの場合に使用する値はSPREADSHEETです。
    • fileImportPage:インポートファイルのデータをHubSpotデータにマッピングするために必要なcolumnMappings配列を格納します。列マッピングの詳細については、以下をご覧ください。

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

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

  • columnObjectTypeId:データが属するオブジェクトまたはアクティビティーの名前またはobjectTypeId値。objectTypeId値の一覧については、こちらの記事をご覧ください。
  • columnName:列ヘッダーの名前。
  • propertyName:データのマッピング先となるHubSpotプロパティーの内部名。toColumnObjectTypeIdフィールドが使用されている場合、複数ファイルのインポートで共通する列では、propertyNamenullである必要があります。
  • columnType:これを使用して、列に一意のIDプロパティーが含まれることを指定します。インポートのプロパティーと目標に応じて、次のいずれかの値を使用します。
    • HUBSPOT_OBJECT_ID:レコードのID。例えば、コンタクトのインポートファイルに、コンタクトに関連付けられる会社のIDを格納する「レコードID」列を含めるケースが考えられます。
    • HUBSPOT_ALTERNATE_ID:レコードID以外の固有ID。例えば、コンタクトのインポートファイルに、コンタクトのEメールアドレスを格納した「Eメール」列を含めるケースが考えられます。
    • ASSOCIATION_KEYS:同じオブジェクト関連付けインポートの場合にのみ、関連付けられる同じオブジェクトレコードの固有IDにこの列タイプを含めます。たとえば、コンタクト関連付けインポートのリクエストでは、[関連付けされたコンタクト[Eメール/レコードID]]列にcolumnTypeとしてASSOCIATION_KEYSが必要です。詳しくは、同じオブジェクト関連付けインポート用にインポートファイルを設定する方法についてご確認ください。
  • toColumnObjectTypeId共通の列プロパティーが属するオブジェクトの名前またはobjectTypeId複数ファイルのインポートの場合のみ)。プロパティーが属していないオブジェクトのファイルに共通する列プロパティー(および使用しているなら関連付けラベル)用にこのフィールドを含めます。例えば、共通する列として[Eメール]コンタクトプロパティーを持つ2つのファイルのコンタクトと会社を関連付ける場合、会社ファイルの「Eメール」列用にtoColumnObjectTypeIdを含めます。
  • foreignKeyTypeassociationTypeIdassociationCategoryで指定された、共通の列が使用する関連付けのタイプ(複数ファイルのインポートの場合のみ)。プロパティーが属していないオブジェクトのファイルに共通する列プロパティー用にこのフィールドを含めます。例えば、共通する列として[Eメール]コンタクトプロパティーを持つ2つのファイルのコンタクトと会社を関連付ける場合、会社ファイルの「Eメール」用にforeignKeyTypeを含めます。
  • associationIdentifierColumn:レコードを関連付けるために共通の列で使用されるプロパティーを示します(複数ファイルのインポートの場合のみ)。プロパティーが属しているオブジェクトのファイルに共通する列プロパティー用にこのフィールドを含めます。例えば、共通する列として[Eメール]コンタクトプロパティーを持つ2つのファイルのコンタクトと会社を関連付ける場合、会社ファイルの「Eメール」列についてassociationIdentifierColumntrueに設定します。

1つのファイルをインポートする

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

// 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

複数のファイルをインポートする

以下は、2つのファイル内のコンタクトと会社をインポートして関連付けるためのリクエスト本文の例です。コンタクトプロパティー[Eメール]がファイル内の共通の列です。

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "Contact Company import", "dateFormat": "YEAR_MONTH_DAY", "files": [ { "fileName": "contact-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", "associationIdentifierColumn": true } ] } }, { "fileName": "company-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-2", "columnName": "Company name", "propertyName": "name" }, { "columnObjectTypeId": "0-2", "columnName": "Company domain name", "propertyName": "domain", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnObjectTypeId": "0-2", "toColumnObjectTypeId": "0-1", "columnName": "Email", "propertyName": null, "foreignKeyType": { "associationTypeId": 280, "associationCategory": "HUBSPOT_DEFINED" } } ] } } ] }

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

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

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

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

  • STARTED:HubSpotはインポートが存在することを認識していますが、インポートの処理はまだ開始されていません。
  • PROCESSING:インポートがアクティブに処理されています。
  • DONE:インポートは完了済みです。全てのオブジェクト、アクティビティー、または関連付けが更新または作成されました。
  • FAILED:インポートの開始時に検出されなかったエラーがありました。インポートは完了しませんでした。
  • CANCELED:エクスポートがSTARTEDPROCESSINGDEFERREDのいずれかの状態だったときに、ユーザーがエクスポートをキャンセルしました。
  • 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 errors such as Incorrect number of columns, 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 following criteria should be met:
    • The column order in the request body and import file should match. If the column order doesn't match, the system will attempt to automatically reorder but may be unsuccessful, resulting in an error when the import is started.
    • Every column needs to be mapped. If a column is not mapped, the import request may still be successful, but would result in the Incorrect number of columns error when the import is started.
  • 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がご提供しているヘルプはこちらでご確認ください。