Skip to main content

Import Customers from a CSV

Import customers when you're moving from another system or have a one-off list of contacts to load. The import is upsert-style: if a customer with the same first name + last name + company name already exists, their record is updated. Otherwise a new one is created.

CSV, TXT, XLSX, and XLS files all work. Maximum file size is 10 MB.

Before you start​

  • You have the customers.create permission.
  • The customer integration is off (same constraint as creating one by hand).
  • Your file has a header row with the column names below. Capitalization doesn't matter, but the words do.

Expected columns​

Column headerRequired?Notes
nameRecommendedPerson's full name or company name. The importer auto-detects which by looking for words like LLC, Inc, Restaurant, Bank, etc.
company_nameOptionalSet this when name is a person and the company is separate.
customer_typeOptionalcommercial (or anything containing "commercial" / "business") → Commercial. Anything else → Residential. There's no government auto-detect — set those to Commercial and switch them in the UI after.
emailOptionalMultiple emails can be separated by commas or semicolons. Bad emails are silently dropped.
phoneOptionalFree text, kept as-is.
street_addressOptionalLine breaks become commas.
city, country, zipOptionalPlain text. zip maps to Postcode in the UI.

Rows with no name and no email are skipped.

Steps​

  1. Open Customers

    Select Customers in the top navigation bar.

  2. Open the import dialog

    Select the Import button at the top-left of the list.

  3. Pick your file

    Select Select File and choose your .csv, .xlsx, .xls, or .txt file.

  4. Run the import

    Select the blue Import button at the bottom-right of the dialog. The page reloads when the import finishes.

  5. Read the result

    The green flash banner at the top shows "Import complete: N created, M updated." That's your created / updated count.

What happens next​

  • Created customers appear in the Customers list immediately.
  • Updated customers had their email, phone, address, city, country, postcode, and type overwritten with the values from your file. Their existing units, quotations, and work orders are untouched.
  • Skipped rows (no name, no email) don't generate an error — they're silently dropped from the count.

Common situations​

SituationWhat to do
You're migrating from QuickBooksExport the customer list as CSV. Make sure the columns are named name, company_name, customer_type, email, phone, street_address, city, country, zip. Run the import.
Your CSV has the company in the name column for some rows and a real person in othersThe importer handles this. It looks for company-indicator words (e.g. LLC, Inc, Restaurant) and routes the row accordingly.
You want to dry-run before committingImport a small file (5–10 rows) first. Confirm the result in the list. Then re-run with the full file. The duplicate match (first + last + company) means the small batch will be detected as updates and won't create dupes.
The file has government customersImport them as commercial (no government auto-detect). Then open each in the UI and switch Type to Government.
You have a column the importer doesn't recognize (e.g. notes, account_number)The importer ignores unknown columns silently. Add the data manually in the UI after import, or open a feature request.

Troubleshooting​

The Import button isn't there.

You're missing the customers.create permission, or the customer integration is enabled. The import button respects the same gates as the New button.

The import says 0 created, 0 updated.

Your file probably has the wrong column names. The importer is keyed off header names — name, company_name, email, etc. Open the file and check the header row matches the table above (case doesn't matter). Save and re-import.

The import says some were updated when you expected new customers.

A row was matched on first name + last name + company name to an existing customer. If the source file has the same name as an existing customer for a different person (e.g. two "John Smith" without companies), they'll collide. Add a distinguishing Company Name in the source file, or merge in the UI after.

The import fails with "The file failed to upload" or a 413 error.

The file is over 10 MB. Split it into smaller files (e.g. 5,000 rows each) and import them in batches. The upsert match key prevents duplicates across batches.

Some emails dropped after import.

The importer validates each email and silently discards anything that doesn't pass. Common culprits: trailing punctuation, missing @, double-encoded &. Open the dropped customers and fix the emails by hand.