Data Export & Import Troubleshooting

Issues with importing CSVs, exporting data, or migrating between tools? Here's the playbook.

Import errors

"Required field missing"

Your CSV doesn't have one of the required columns:

Customers: name (only required field)
Jobs: customer_email (or customer_name), title, status, date

Add the missing column and re-upload.

"Invalid date format"

HandyBook expects YYYY-MM-DD or MM/DD/YYYY (US default).

Open CSV in Excel/Sheets
Format the date column as text or your expected format
Re-save as CSV

"Customer not found"

When importing jobs, the customer_email or customer_name doesn't match an existing customer:

Import customers first, then jobs
Or pre-create the customer in HB
Check for typos in the email

"Status invalid"

Job status must be one of: lead, quoted, scheduled, in_progress, complete, invoiced, paid, cancelled. Anything else is rejected.

"Phone format error"

Phones with leading zeros lost (Excel autocorrect). Format the phone column as Text in Excel before saving.

"Encoding error"

CSV uses non-UTF-8 characters (e.g. accented characters from older systems). Save the CSV with UTF-8 encoding.

Export issues

Export is missing data

Check your filters before exporting (date range, status filter, etc.)
Some fields are excluded from CSV exports for privacy (e.g. card numbers)
Photos export as a separate ZIP, not in CSV

Export takes forever

For large accounts (10k+ records):

Async export — HB emails you when ready
Can take up to 30 minutes for very large data sets
Done — link in email to download

Export download corrupted

Re-trigger the export. Sometimes the first attempt is interrupted (network glitch, browser closed early).

CSV opening issues

Excel garbles the file

Excel auto-converts dates and numbers. Issues:

Long numbers shown in scientific notation
Phones with leading zeros lose them
Dates auto-convert to Excel's default format

Workarounds:

Open in Google Sheets instead — usually cleaner
Or in Excel: File → Import (not File → Open) → CSV → set every column to Text type

Unicode characters not displaying

Excel needs UTF-8 BOM to detect encoding. HandyBook exports include the BOM. If still garbled, open in Notepad++ first and confirm encoding.

Migrating from another system

Generic strategy

Export from the source system as CSV
Map columns to HandyBook's template
Import customers first
Then jobs (referencing customer email)
Then expenses, time, etc.
Photos / files migrate separately (manual or via API)

Source-specific tips

From Jobber

Export Customers and Jobs separately
Jobber's "client" column maps to HB's "customer name"
Jobber statuses don't map 1:1 — translate ("Active" → "scheduled", "Completed" → "complete")

From Housecall Pro

Export via Reports → Customer Export, Jobs Export
HCP uses specific job statuses; map to HB's

From ServiceTitan

Export via Settings → Data Export
Large exports — likely need to split into multiple imports
Some custom fields may need manual recreation in HB

From spreadsheet

Easiest case — match your columns to the template
Anything not in the template is dropped (you can add custom fields after import to retain unique data)

From QuickBooks

Customer list export → import to HB
Don't import invoices via CSV — connect QB sync instead, it brings them automatically

Photo / file migration

CSV doesn't carry photos. For bulk migration:

Smaller volumes: drag photos into HB customer/job after import
Larger volumes: contact support for assisted migration
Via API: developers can write scripts to upload photos with file metadata

API-based migration

For complex migrations:

Use HandyBook API to script the import
Better control over field mapping
Can migrate hundreds of thousands of records reliably

See Integrations → API Basics.

FAQ

Can I undo a bad import? Within 24 hours, yes — Settings → Data → Recent Imports → Undo. Past 24 hours, you'd need to delete records manually.

Can I import partial files (just specific columns)? Yes — match the columns you have. Empty columns are fine.

My import is stuck "Processing" For very large files, processing can take several minutes. If stuck > 30 min, contact support — there may be a corruption.

What's the row limit per import? 10,000 rows. Larger files: split into multiple files.

How do I migrate from HandyBook to another tool? Export everything via Settings → Data → Export All. Most other tools accept CSV; you'd map and import on their side.