Import into Notion — CSV, Excel & PDF

• Overview
• From
• Into

Importing for your users — or for yourself?

Building a product that fills Notion? A product that writes into customers’ Notion workspaces, internal tooling on Notion — this page is your integration guide: your users bring files, clean records land in the database (and your backend sees every row first), and nobody leaves your app. Read on.

Just trying to get your own file into Notion? You have the file and the workspace; 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 integration 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 Notion 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 Notion API call.

1. Embed the importer

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

2. Publish a catalog that mirrors Notion

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 the database properties you’ll write, and publish. The widget loads that published catalog by catalog-key.

Title (Name) is required on a Notion page. Add Email, Stage, Owner — or whichever properties the destination database actually has. Scan from a sample page JSON if the database is large.

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

POST https://api.notion.com/v1/pages per record (integration token, Notion-Version header) — parent = your database id

Notion-specific gotchas

• one page per request (no batch endpoint) — a 5k-row import is 5k calls; queue with ~3 req/s pacing.
• every property type has its own JSON shape (title vs rich_text vs select) — generate the property payload from the catalog type.
• select options are created implicitly; guard against typo-driven option sprawl in validation.

Why not Notion’s own CSV import?

Notion’s CSV import creates a new database, and Merge with CSV can append rows to an existing one — add-only, no updates, no dedupe. What neither can be is part of YOUR product: feeding customers’ workspaces with typed, validated rows takes the API — and an importer that validates before you spend 5,000 API calls.

---

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.