インポート
インポート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などのアプリを使用したリクエストの例を示します。
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メール」列を含めるケースが考えられます。
以下は、コンタクトを作成するためのインポートのリクエスト本文の例です。
リクエストが成功すると、インポートの取得またはキャンセルに使用できるimportId
を含むレスポンスが返されます。
以前のインポートを取得する
HubSpotアカウントから全てのインポートを取得するには、/crm/v3/imports/
にGET
リクエストを送信します。特定のインポートの情報を取得するには、/crm/v3/imports/{importId}
にGET
リクエストを送信します。
インポートを取得すると、インポートの名前、ソース、ファイル形式、言語、日付形式、列マッピングなどの情報が返されます。また、インポートのstate
も返されます。これは次のいずれかです。
STARTED
:HubSpotはインポートが存在することを認識していますが、インポートの処理はまだ開始されていません。PROCESSING
:インポートがアクティブに処理されています。DONE
:インポートは完了済みです。全てのオブジェクト、アクティビティー、または関連付けが更新または作成されました。FAILED
:インポートの開始時に検出されなかったエラーがありました。インポートは完了しませんでした。CANCELED
:エクスポートがSTARTED
、PROCESSING
、DEFERRED
のいずれかの状態だったときに、ユーザーがエクスポートをキャンセルしました。DEFERRED
:最大数(3件)のインポートが同時に処理されています。他のインポートの1つの処理が終了すると、インポートが開始されます。
この記事の上部にある「エンドポイント」タブから、結果のページ処理と制限に関する詳細をご確認ください。
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 thefileName
field. For example, import_name.csv. - Ensure that your header includes
Content-Type
with a value ofmultipart/form-data
.
注:エラーが発生する場合は、Content-Type
などの重複するヘッダーがあるかどうかを確認してください。これが発生する可能性があるのは、Postmanを使用している場合、またはPythonスクリプトのヘッダーにそれが含まれている場合です。リクエストを完了する前に重複を削除してください。
インポートAPIを使用すると、1日あたり最大80,000,000行をインポートできます。ただし、個々のインポートファイルの上限として、1,048,576行または512MBのうち最初に到達した条件が適用されます。
リクエストが行制限またはサイズ制限のいずれかを超えた場合、HubSpotから429 HTTPエラーが返されます。このような上限に近づいたら、インポートを複数のリクエストに分割することをお勧めします。
貴重なご意見をありがとうございました。