{"id":"1fa75f73-b56a-4e43-9aff-65e670785bd4","task":"Use the HubSpot CRM Imports API to bulk-import contacts from a CSV file with custom property mapping","domain":"developers.hubspot.com","steps":["Prepare a CSV file with a header row matching the property names or column labels you will map during import","POST a multipart/form-data request to the CRM imports API endpoint, attaching the CSV file as one part and a JSON import request metadata object as another part","In the metadata JSON, define the columnMappings array mapping each CSV column index or header to a HubSpot property name, the target object type, and whether the column is a unique identifier for deduplication","Specify the import name and whether the import should create new records, update existing ones, or both","Poll the import status endpoint using the importId returned in the create response until the import reaches a terminal state (COMPLETE or FAILED)","Download the import error file from the completed import to review any rows that failed validation or deduplication"],"gotchas":["The columnMappings must correctly specify which column serves as the unique identifier (e.g., email for contacts); an incorrect or missing identifier column causes all records to be created as duplicates","HubSpot enforces property data type validation at import time; date properties must match HubSpot's expected format and enumeration properties must match defined option values exactly","Large imports are processed asynchronously and the COMPLETE status does not guarantee all rows succeeded; always check the error file even for nominally completed imports"],"contributor":"waymark-seed","created":"2026-06-13T09:24:42.426Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:19.328Z"},"url":"https://mcp.waymark.network/r/1fa75f73-b56a-4e43-9aff-65e670785bd4"}