HubSpot CRM Imports
Browse all Hubspot APIs✓ Official Vendor SpecCRMContact Managementoauth25 EndpointsREST
For Agents
Bulk-import CSV or spreadsheet files into HubSpot CRM and monitor import status, errors, and cancellations programmatically.
Use for: I need to import a CSV of new contacts into HubSpot, I want to migrate deals from Salesforce into a HubSpot account, Check whether the import I started yesterday completed successfully, List all active imports running in the HubSpot account right now
Not supported: Does not handle per-record contact updates, exports out of HubSpot, or property schema changes — use for bulk CSV ingestion of CRM records only.
The HubSpot CRM Imports API lets you bulk-load CRM records from CSV or spreadsheet files into HubSpot, mapping columns to standard or custom properties on contacts, companies, deals, and other objects. You can start a new import, monitor active imports, cancel an in-progress import, and inspect row-level errors after the job runs. It is the right tool for migrating data from another CRM, syncing periodic exports from external systems, or seeding a HubSpot account with historical records.
Install Jentic One Beta
Connect the CRM Imports to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the CRM Imports, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with CRM Imports API.
Submit a CSV or spreadsheet file to HubSpot for bulk record creation across contacts, companies, deals, and custom objects
Track the status of an in-progress import and retrieve row-level error reports after completion
Cancel an active import job before it finishes processing
List every active or recent import in the account with filtering by date and status
Map source-file columns to HubSpot properties and association references during the import request
Use Cases
Patterns agents use CRM Imports API for, with concrete tasks.
★ Bulk Migration from Another CRM
Move thousands of contact, company, and deal records from a legacy CRM into HubSpot in a single import job rather than calling the create endpoint per record. The Imports API accepts a CSV with column-to-property mappings, queues the file for processing, and returns an importId that can be polled for completion. Migrations of 50,000+ records typically finish within a few hours and surface row-level errors for any rows that failed validation.
Submit a CSV file containing 5,000 contact records to POST /crm/v3/imports/ with column mappings for email, firstname, and lastname, then poll GET /crm/v3/imports/{importId} every 60 seconds until the status is COMPLETE.
Scheduled Sync from an External System
Run a recurring nightly or weekly bulk-load of records exported from an ERP, billing system, or marketing warehouse into HubSpot. Each scheduled job submits a fresh CSV through the Imports API and persists the returned importId for status tracking. This pattern keeps HubSpot in sync with an upstream source without writing per-record API calls and stays under HubSpot's daily request limits.
Trigger POST /crm/v3/imports/ with the previous-night export from an ERP, store the importId, and check GET /crm/v3/imports/{importId}/errors after completion to flag any rows that failed property validation.
Agent-Driven Import Recovery
An AI agent can detect a failed or stuck import, retrieve the error details, and either cancel and retry or surface a remediation plan to a human operator. Through Jentic, the agent searches for the import operation, loads the schema, and chains the cancel and create endpoints without browsing HubSpot's REST docs. This is useful in data-engineering copilots that own the operational health of a HubSpot instance.
List active imports via GET /crm/v3/imports/, identify any with status FAILED, fetch errors via GET /crm/v3/imports/{importId}/errors, then cancel the job via POST /crm/v3/imports/{importId}/cancel and report the failed row count.
Key Endpoints
5 endpoints — the hubspot crm imports api lets you bulk-load crm records from csv or spreadsheet files into hubspot, mapping columns to standard or custom properties on contacts, companies, deals, and other objects.
METHOD
PATH
DESCRIPTION
POST
/crm/v3/imports/
Start a new import
GET
/crm/v3/imports/
List active imports
GET
/crm/v3/imports/{importId}
Get the status of a specific import
GET
/crm/v3/imports/{importId}/errors
Retrieve row-level errors for an import
POST
/crm/v3/imports/{importId}/cancel
Cancel an active import
POST
/crm/v3/imports/
Start a new import
GET
/crm/v3/imports/
List active imports
GET
/crm/v3/imports/{importId}
Get the status of a specific import
GET
/crm/v3/imports/{importId}/errors
Retrieve row-level errors for an import
POST
/crm/v3/imports/{importId}/cancel
Cancel an active import
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth tokens and Private App tokens are stored encrypted in the Jentic vault. Agents receive scoped access references — raw tokens never enter the agent's context window or model prompts.
Intent-based discovery
Agents search by intent (e.g., 'bulk import contacts to HubSpot') and Jentic returns the matching POST /crm/v3/imports/ operation with its full input schema, including the file and column-mapping shape.
Time to first call
Direct integration: 1-2 days to build CSV submission, status polling, and error-handling. Through Jentic: under 30 minutes — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using CRM Imports API through Jentic.
What authentication does the HubSpot CRM Imports API use?
It uses OAuth 2.0 (oauth2_legacy scheme) or HubSpot Private App tokens (private_apps_legacy scheme), passed as a Bearer token in the Authorization header. Through Jentic, your HubSpot token is stored in the encrypted vault and the agent receives a scoped access reference rather than the raw token.
Can I import custom objects with the HubSpot CRM Imports API?
Yes. The POST /crm/v3/imports/ endpoint accepts a column mapping that targets standard objects (contacts, companies, deals) and any custom object schemas defined in the account. The mapping declares which CSV column populates which property on the target object.
What are the rate limits for the HubSpot CRM Imports API?
HubSpot enforces a default account-wide limit of 100 requests per 10 seconds for OAuth apps and 110 for Private Apps, with daily caps that vary by Hub tier. The Imports API additionally caps the number of concurrent active imports per account, so polling GET /crm/v3/imports/ before submitting a new job is recommended.
How do I submit a CSV import through Jentic?
Run pip install jentic, then call client.search('start a HubSpot CRM import') to discover the operation, client.load to get the schema for POST /crm/v3/imports/, and client.execute with the file reference and column mappings. The importId in the response feeds GET /crm/v3/imports/{importId} for status polling.
How do I retrieve row-level errors after an import fails?
Call GET /crm/v3/imports/{importId}/errors with the importId returned from the original POST. The response lists each rejected row with the error reason, which is typically a property validation failure or a missing required association reference.
Can I cancel an import that is already running?
Yes. POST /crm/v3/imports/{importId}/cancel stops an active import. Records that were already committed before the cancel call remain in the account; only the unprocessed portion of the file is dropped.
GET STARTED