canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-imports

# HubSpot CRM Imports

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.

## For AI agents

Bulk-import CSV or spreadsheet files into HubSpot CRM and monitor import status, errors, and cancellations programmatically.

## Scope

Does not handle per-record contact updates, exports out of HubSpot, or property schema changes - use for bulk CSV ingestion of CRM records only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Imports** — Submit, list, inspect, and cancel bulk import jobs for HubSpot CRM records
- **Import errors** — Retrieve row-level error reports for any import that completed with rejected records

## Why Jentic

- **Setup:** Wiring the HubSpot Imports API by hand means handling its OAuth 2.0 authorization-code flow, targeting api.hubapi.com, and coding the multipart file upload with column mapping plus status and error polling yourself. Through Jentic you install once, import HubSpot Imports from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The import id travels in the URL path (/crm/v3/imports/{importId}/...) and HubSpot gates access with per-object OAuth scopes, so you grant only the scopes your agent needs and you choose which operations it may call: you can allow starting imports and reading their status while leaving cancel out of the allowed set unless you add it.
- **Credential handling:** Your HubSpot OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'bulk import contacts to HubSpot' or 'check an import's status and errors', and Jentic returns the matching imports operation with its input schema, including the file and column-mapping shape, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Exports** — The mirror of Imports for getting HubSpot data out as CSV
- **HubSpot CRM Contacts** — Per-record contact CRUD for cases that do not need bulk loading
- **Salesforce REST API** — Salesforce Bulk API serves the same role for the Salesforce CRM

## FAQ

### 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.

### Can I limit what my agent is allowed to do with the HubSpot CRM Imports API?

Yes. Because you run Jentic One yourself, your own rules decide which HubSpot CRM Imports operations the agent may call, so you can allow it to start imports (POST /crm/v3/imports/), list them, and read status and row-level errors while leaving cancel (POST /crm/v3/imports/{importId}/cancel) out of the allowed set. Access is also gated by the per-object OAuth scopes you grant to your stored HubSpot token, so the agent only touches the contact, company, or deal objects you permit. The token is injected at execution time and never enters the agent's prompt or logs.