求HubSpot API CSV导入请求的正确可运行示例

我尝试使用HubSpot的Import API导入联系人，采用了官方示例CSV的简化版本，内容如下：

无论是用Postman还是PHP的Guzzle库，尝试多种请求变体后都返回400错误：

POST https://api.hubapi.com/crm/v3/imports/ resulted in a 400 Bad Request response

以下是我之前使用的简化请求代码：

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'multipart/form-data',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer xxx-xxx-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'
];
$options = [
  'multipart' => [
    [
      'name' => 'files',
      'contents' => Utils::tryFopen('/path/to/file/HubSpot example - Contacts import file.csv', 'r'),
      'filename' => '/path/to/file/HubSpot example - Contacts import file.csv'
    ],
    [
      'name' => 'importRequest',
      'contents' => '{"name":"customers_import","files":[{"fileName":"/path/to/file/HubSpot example - Contacts import file.csv","fileFormat":"CSV","fileImportPage":{"hasHeader":true,"columnMappings":[{"ignored":false,"columnName":"First Name","idColumnType":null,"propertyName":"firstname","columnObjectType":"CONTACT"},{"ignored":false,"columnName":"Last Name","idColumnType":null,"propertyName":"lastname","columnObjectType":"CONTACT"},{"ignored":false,"columnName":"Email Address","idColumnType":null,"propertyName":"email","columnObjectType":"CONTACT"}]}}]}'
    ]
]];
$request = new Request('POST', 'https://api.hubapi.com/crm/v3/imports/', $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();

我还尝试了以下调整，但均未解决问题：

• 将columnObjectType改为columnObjectTypeId: "0-1"
• 反复检查Authorization令牌和权限（确认权限无问题，因为权限错误会返回401）
• 确认PHP脚本可访问并读取文件（非Postman环境下）
• 尝试多种Header变体
• 改用Excel文件导入数据
• 为importRequest添加额外参数（无明显效果）：

  //...
  "importOperations" => [
       "0-1" => "CREATE"
  ],
  "dateFormat" => "DAY_MONTH_YEAR",
  "marketableContactImport" => true,
  //...
  

可正常运行的请求示例 #

以下是修正后的PHP代码，解决了导致400错误的关键问题：

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Utils;

$client = new Client();
$apiToken = 'xxx-xxx-xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'; // 替换为你的API令牌
$csvFilePath = '/path/to/file/HubSpot example - Contacts import file.csv';
$csvFileName = basename($csvFilePath); // 仅提取文件名，无需完整路径

// 构造导入请求参数
$importRequest = [
    "name" => "customers_import",
    "files" => [
        [
            "fileName" => $csvFileName,
            "fileFormat" => "CSV",
            "fileImportPage" => [
                "hasHeader" => true,
                "columnMappings" => [
                    [
                        "ignored" => false,
                        "columnName" => "First Name",
                        "propertyName" => "firstname",
                        "columnObjectTypeId" => "0-1" // CONTACT对象的官方ID
                    ],
                    [
                        "ignored" => false,
                        "columnName" => "Last Name",
                        "propertyName" => "lastname",
                        "columnObjectTypeId" => "0-1"
                    ],
                    [
                        "ignored" => false,
                        "columnName" => "Email Address",
                        "propertyName" => "email",
                        "columnObjectTypeId" => "0-1"
                    ]
                ]
            ]
        ]
    ]
];

$options = [
    'multipart' => [
        [
            'name' => 'files',
            'contents' => Utils::tryFopen($csvFilePath, 'r'),
            'filename' => $csvFileName // 仅传文件名，匹配importRequest中的fileName
        ],
        [
            'name' => 'importRequest',
            'contents' => json_encode($importRequest), // 自动处理JSON转义，避免手动错误
            'headers' => ['Content-Type' => 'application/json']
        ]
    ],
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => "Bearer {$apiToken}"
    ]
];

try {
    $response = $client->post('https://api.hubapi.com/crm/v3/imports/', $options);
    echo $response->getBody();
} catch (\GuzzleHttp\Exception\ClientException $e) {
    // 捕获并打印详细错误信息，便于排查
    echo "错误详情：" . $e->getResponse()->getBody();
}

关键修正说明 #

1. 文件名匹配：上传文件的filename和importRequest中的fileName必须一致，且仅需文件名（不要完整路径），HubSpot通过文件名关联上传文件和配置信息
2. 对象ID规范：使用columnObjectTypeId: "0-1"替代columnObjectType，这是HubSpot官方定义的CONTACT对象标识
3. JSON编码：用json_encode()生成请求配置，避免手动编写JSON时的转义错误
4. Header自动处理：无需手动设置multipart/form-data，Guzzle会自动生成正确的Content-Type；同时给importRequest部分单独设置application/json类型
5. 错误捕获：添加异常捕获逻辑，打印完整的错误响应内容，方便定位剩余问题

内容的提问来源于stack exchange，提问作者Angelin Calu