Onboarding's Biggest Blocker Solved
New Velocity X customers arrive with baggage: 500 leads from their old system, deals scattered across Salesforce exports, a Pipedrive CSV dump from six months ago. "Can we just... import all of this?" is the first question after signup. Most SaaS tools answer with a manual importer buried in settings and a promise that "it probably works." Velocity X's CSV importer is built to be fast, visible, and bulletproof — because onboarding friction loses customers.
Why CSV Migration Is the Biggest Blocker
A 50-person sales team switching to Velocity X doesn't need a demo of the map UI or the territory engine. They need their 2,000 existing prospects loaded by Monday morning, without manual re-entry. If that takes four hours and produces 47 import errors in a column you didn't know was broken, the CEO's question isn't "how cool is the UI?" — it's "how long until we can actually use this?"
The importer is the do-or-die feature that decides whether onboarding feels like "seamless handoff from Salesforce" or "we're starting from scratch again." Velocity X bundles an enterprise-grade importer in all plans because the only acceptable barrier is zero.
The Architecture
The flow: paste CSV → auto-detect schema → map columns → preview 10 rows → validate rows → batch upsert 100 at a time → error log per row → success report.
Step 1: Parse & detect. PapaParse (19k stars) transforms the raw CSV into objects with inferred headers. Velocity X sniffs the first row for common field names: `email`, `name`, `company`, `phone`, `status`, `owner`, `created_at`. No config needed for basic imports.
Step 2: Column mapping UI. After detection, users see a table: "CSV column" on the left, "Velocity X field" on the right. The importer suggests mappings (if the CSV has a `contact_email` header, it prompts "map to Email?"). Users can skip columns, remap, or add custom fields on the fly.
Step 3: Row validation. Before touching the database, every row runs through Zod schemas. Email is valid email. Phone is E.164 format or accepted as-is. Status is one of `prospect|qualified|won|lost`. Invalid rows get flagged: "Row 47: status 'maybe' is not recognised." Users can fix the CSV and re-upload, or skip bad rows and proceed.
Step 4: Batch upsert. Rows are inserted in batches of 100 via Supabase's `upsert` (insert or update by unique key). If the email already exists, the row updates. If it's new, it inserts. Progress bar moves in real-time — Firebase-style chunk notifications, no polling.
Step 5: Error log. Any upsert error (database constraint, permission) logs row-by-row: "Row 123: duplicate email in deals table (FK constraint)". Users see the error, the row data, and a suggestion to re-import after fixing the source data.
Why Batch Size = 100?
Supabase has soft limits on request size (~10MB per request). A batch of 100 mid-sized rows (name, email, company, phone, status, owner) lands at ~200KB — well under the limit, fast to process, slow enough that users see smooth progress and can cancel mid-import if needed.
Smaller batches (10–20 rows) mean 10–20 requests for a 1,000-row CSV and wasted latency. Larger batches (500+) mean one slow request blocks the whole import and risks timeout. 100 is the Goldilocks number for SaaS importer UX.
Frequently Asked Questions
What if I have 50,000 rows?
Velocity X's importer scales to ~10K rows per import before the UI becomes sluggish. For larger datasets, the solution is two imports, or contact support for a direct ETL pipeline (Airtable/Zapier/CSV-to-Supabase script). In practice, sales teams with 50K rows import in three batches and it's done in under an hour.
Can I import custom fields?
Yes. If the CSV has columns that aren't in the standard schema (e.g. `custom_region`, `annual_budget`), the UI prompts "create as custom field?" and adds them on-the-fly as long as they're plain text or numbers. Custom field limits are per-org (50 custom fields), not per-row.
What happens if the import fails halfway through?
Rows already inserted stay. Failed rows don't insert. The UI shows which rows failed and why. You can fix the CSV, delete the partial import from the dashboard, and re-run. Or keep the partial import and manually add the rest later.
Does the importer work on mobile?
The CSV paste/upload works on mobile, but the column-mapping UI is optimised for desktop (side-by-side layout). For mobile, upload the CSV on mobile, then open Velocity X on desktop to map and confirm.
Can I schedule recurring CSV imports?
Not yet — all imports are manual. Recurring imports (sync a Salesforce export every Monday) are on the roadmap. Today, the workaround is Zapier or a lightweight cron job that feeds CSV files to the Velocity X API.
How do I handle duplicates?
The importer's upsert strategy uses email as the unique key by default. If the CSV has two rows with the same email, the second one overwrites the first. For merging duplicates that are already in Velocity X, the dashboard has a dedicated "merge contacts" tool. (See our CRM sync post for how duplicates in your CRM get surfaced.)
The Bottom Line
CSV import is where SaaS onboarding either starts smooth or derails fast. Velocity X's importer is built to swallow real-world data (messy headers, skipped columns, partial updates) and report errors clearly so users fix-and-retry without frustration. It's the buy-once feature that makes switching costs zero — no engineering hand-holding, no "contact sales for migration help", just upload and move on.