CRM Imports

Name: CRM Imports API
Brand: HubSpot CRM Imports
Availability: InStock

✓ Official Vendor SpecCRMContact Managementoauth25 EndpointsREST

For Agents

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

Quickstart

Get started with CRM Imports in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"bulk import a CSV of records into HubSpot CRM"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

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

GET STARTED

Start building with CRM Imports API

Explore with Jentic

View OpenAPI Document

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.

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

Complementary

HubSpot CRM Exports

The mirror of Imports for getting HubSpot data out as CSV

Choose CRM-exports when you need to extract records from HubSpot for downstream processing rather than load records in

Complementary

HubSpot CRM Contacts

Per-record contact CRUD for cases that do not need bulk loading

Use CRM-contacts when adding or updating fewer than ~100 records, where the per-record API is faster than queueing an import

Alternative

Salesforce REST API

Salesforce Bulk API serves the same role for the Salesforce CRM

Choose Salesforce when the target CRM is Salesforce rather than HubSpot

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.