CRM API | インポート

• ファイル要件
• レコードとアクティビティーのインポートに必要なプロパティー
• マーケティングイベント参加者のインポートに必要なプロパティー

​

インポートを開始する

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

​

importRequestデータを書式設定する

• 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プロパティーにファイルの列をマッピングする

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

​

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"
}
]
}
}
]
}

// Example POST to https://api.hubspot.com/crm/v3/imports
// Content-Type header set to multipart/form-data

{ "name": "Marketing Events Import Example", "marketingEventObjectId": 377224141223, "importOperations": { "0-1": "UPSERT", "0-54": "CREATE" }, "dateFormat": "YEAR_MONTH_DAY", "timeZone": "America/New_York", "files": [ { "fileName": "Marketing Events Import Example.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnName": "First Name", "columnObjectTypeId": "0-1", "propertyName": "firstname", "columnType": "STANDARD" }, { "columnName": "Last Name", "columnObjectTypeId": "0-1", "propertyName": "lastname", "columnType": "STANDARD" }, { "columnName": "Email", "columnObjectTypeId": "0-1", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnName": "Registered", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "REGISTERED" }, { "columnName": "Attended", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "JOINED" }, { "columnName": "Left", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "LEFT" }, { "columnName": "Cancelled", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "CANCELLED" } ] } } ] }

​

複数のオブジェクトを含む1つのファイルをインポートする

// Example POST to https://api.hubspot.com/crm/v3/imports
// Content-Type header set to multipart/form-data

{
"name": "Association Label Import",
"dateFormat": "DAY_MONTH_YEAR",
"files": [
{
"fileName": "association label example.xlsx",
"fileFormat": "SPREADSHEET",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"columnObjectTypeId": "0-1",
"columnName": "Email",
"propertyName": "email"
},
{
"columnObjectTypeId": "0-2",
"columnName": "Domain",
"propertyName": "domain"
},
{
"columnName": "Association Label",
"columnType": "FLEXIBLE_ASSOCIATION_LABEL",
"columnObjectTypeId": "0-1",
"toColumnObjectTypeId": "0-2"
}
]
}
}
]
}

​

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

// 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" } } ] } } ] }

​

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

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

​

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

​

インポートエラーの意味とトラブルシューティング

• ファイル内の各列に列ヘッダーがあり、リクエスト本文に各列のcolumnMappingエントリが含まれていることを確認します。次の条件を満たしている必要があります。
  • リクエスト本文とインポートファイルの列の順序は一致していなければなりません。列の順序が一致しない場合、自動的な並べ替えの試行に失敗し、インポートの開始時にエラーが発生する可能性があります。
  • 全ての列がマッピングされていなければなりません。列がマッピングされていない場合でもインポートリクエストは成功する可能性がありますが、インポートの開始時に「列数が正しくありません」というエラーが発生する場合もあります。
• ファイルの名前がリクエストのJSONのfileNameフィールドと一致していて、fileNameフィールドにファイル拡張子が含まれていることを確かめてください（例：import_name.csv）。
• multipart/form-dataの値のあるContent-Typeがヘッダーが含まれていることを確かめます。

Example POST URL:
https://api.hubapi.com/crm/v3/imports?

Example importRequest JSON data:
This example contains 3 columns:
- First name, mapped to the firstname contact property
- Email, mapped to the email contact property
- Company ID, which contains a list of company record IDs
that the contact will be assocated with.
{
"name": "test_import",
"files": [
{
"fileName": "final_emails.csv",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"ignored": false,
"columnName": "First Name",
"idColumnType": null,
"propertyName": "firstname",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Company ID",
"idColumnType": "HUBSPOT_OBJECT_ID",
"propertyName": null,
"foreignKeyType": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 1
},
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
}
]
}
}
]
}

​

上限