Use the HubSpot CRM Imports API to bulk-import contacts from a CSV file with custom property mapping
domain: developers.hubspot.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
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
Known 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
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp