Import into HubSpot — CSV, Excel & PDF

Building a product that feeds HubSpot? An integration or sync product, agency onboarding tooling, a vertical app with HubSpot as its CRM — this page is your integration guide: your users bring files, clean records land in the portal (and in your own backend, which sees every row first), and nobody leaves your app. Read on.

Just trying to get your own file into HubSpot? You have the file and the HubSpot account; the file is the problem — renamed headers, merged columns, a PDF where a spreadsheet should be. See the wizard handle genuinely messy files in the playground (free, no signup). And a run-it-yourself importer is in the works: your own private-app token, runs on your machine, every row staged for review — and revertible after it lands. Join the waitlist.

Goal: your users bring the file they have — CSV, Excel, even a PDF or a scan — and clean records land in HubSpot without leaving your product, and without you writing a mapping/validation UI. The pattern is the same every time: embed → validate → deliver. Mildport handles the first two; your webhook handler owns the HubSpot API call.

1. Embed the importer

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  catalog-key="hubspot"
></mildport-import>

2. Publish a catalog that mirrors HubSpot

The schema lives in a target catalog, not in host code. Create it in the catalog editor (/admin/catalogs on your engine, or embed <mildport-catalog-editor>), match Contacts and Companies, and publish. The widget loads that published catalog by catalog-key.

Use HubSpot’s lowercase internal property names as field keys (email, firstname, lastname, company.name) so the apply payload maps 1:1 onto the CRM v3 API. Mark email required — HubSpot dedupes contacts on it.

Users then upload anything — renamed headers, six languages, XLSX/ODS, even PDF tables — and Mildport’s deterministic matcher plus the review step produce typed, validated rows.

Need the schema computed per user at runtime, or versioned with your app? That’s the schema-as-code path — pass targets from host code instead of catalog-key.

3. Deliver from your webhook

Clean rows arrive on your signed apply webhook; your handler feeds HubSpot:

POST https://api.hubapi.com/crm/v3/objects/contacts/batch/create (private-app token; 100 inputs max)

HubSpot-specific gotchas

HubSpot dedupes contacts by email — decide upsert vs create BEFORE the batch (batch/upsert endpoint).
property names are lowercase internal names (firstname, not First Name) — keep catalog keys aligned.
rate limits are per-portal; spread big imports with the batch endpoints, not record-by-record.

Why not HubSpot’s own CSV import?

HubSpot’s own import is a capable wizard: in HubSpot’s UI it takes a CSV, XLSX or XLS and maps your columns onto properties in any order — and there’s an import API for developers. What it can’t be is part of your product: your users leave your app and need HubSpot logins with import permissions, and the rows never pass through your backend — so your validation rules, your dedupe policy and your audit trail don’t apply. It also takes spreadsheets only: a PDF or a scan has to become a clean spreadsheet before HubSpot will look at it. Embedding import keeps users in your product — and your backend controls what actually lands in the portal.

Try the flow first: the playground (no signup), then the Quickstart and target catalogs. Prices are published — hosted and flat-annual self-host — at mildport.com/#pricing.