Import Builder
Import Builder/Guides/Xero contacts import errors
Accounting

Xero Contacts Import Errors and How to Fix Them

Importing contacts into Xero saves typing in every customer and supplier, as long as the file follows Xero's rules. These are the problems that stop an import, or leave you with duplicates and wiped details, since imported contacts can't be deleted.

Xero's import rules

Xero's own CSV template, with its column headings
A contact name on every row: it's the only required column
Up to 1,000 contacts per file
Text within Xero's character limits, such as 255 for names and 50 for tax numbers
Emails written like email@domain.com, websites with http://
Tax rates, account codes and tracking options exactly as set up in Xero

How to import

In Xero, go to Contacts, All contacts, then choose Import from the menu at the top right. Download the template there, fill it in, then select your file, choose what empty fields should do for existing contacts, review and click Complete Import. Imported contacts can't be deleted, only archived, so Xero suggests trying the file in its demo company first.

Common errors and their fixes

A contact was added twice

Cause: Xero matches existing contacts on the contact name. Smith & Co in the file and Smith and Co in Xero are different names, so the import creates a second contact, and imported contacts can't be deleted, only archived.

Fix: Copy names from an export of your Xero contacts rather than retyping them, and try the file in Xero's demo company first. Archive any duplicate that gets through. More on spotting them in the duplicate rows guide.

Renaming contacts created new ones

Cause: The contact name is what the import matches on, so it can't change a name: a new name is treated as a new contact.

Fix: Rename contacts in Xero itself, one at a time, and leave the ContactName column untouched when updating details.

Existing details were wiped

Cause: When updating, Xero asks what empty fields should do. With Delete existing information, every blank cell clears what's in Xero.

Fix: Choose Be ignored unless you mean to clear fields. If you do choose Delete existing information, keep every column in the file: deleting a column makes the import fail.

Bank account numbers turned into 1.23E+15

Cause: Excel shows numbers longer than 11 digits in scientific notation, and saving the file keeps the damaged value.

Fix: Write bank account numbers with hyphens, as Xero recommends, or keep the column as text. Importing bank details also needs Xero's admin user permission. See stopping scientific notation in Excel.

Text is too long

Cause: Xero limits most columns. Names, cities, regions and attention lines take 255 characters; postal codes, countries, tax numbers, company numbers and bank account details take 50; websites 200.

Fix: Shorten the long values. Addresses that run over usually have a whole address squeezed into one line: split it across the address line columns.

More than 1,000 contacts

Cause: Xero asks for files of up to 1,000 contacts.

Fix: Split the list into several files and import them one after another.

Emails rejected, or extra people missing

Cause: Email addresses must be complete, like email@domain.com. Additional people (the Person columns) can only be added when the main contact has an email address, and importing that column replaces the extra people already in Xero.

Fix: Fix incomplete emails, fill in the main email before any additional people, and delete the Person columns when updating if you don't want to change them.

Tax rates, accounts or tracking not picked up

Cause: These columns must match what's set up in Xero exactly: the tax rate's name, the account's code (just the code) and tracking category and option names. Tracking categories must exist before the import.

Fix: Copy names and codes from Xero's settings and your chart of accounts, and set up tracking categories first.

Payment terms ignored

Cause: Each payment term is two columns that go together: a day (DueDateSalesDay or DueDateBillDay) and a term (DueDateSalesTerm or DueDateBillTerm).

Fix: Fill in both. The term must be Current Month, Following Month, Days After or Days After End of Month; the day is up to 2 digits for a day of the month, or up to 3 for days after.

Contacts don't show under Customers or Suppliers

Cause: Imported contacts go into the All group. Xero moves them to Customers or Suppliers once they have an invoice, bill or credit note.

Fix: That's expected. Create your own contact group if you need to sort them before then.

Updating contacts in bulk

To change many contacts at once, export them from Xero (All contacts, then Export from the same menu), edit the file and import it back. The export uses the same columns as the import template. Leave the ContactName column exactly as exported, or Xero adds new contacts instead of updating.

To change one thing, such as account numbers, Xero suggests deleting every column except the name and that one, then importing with empty fields set to Be ignored. Fewer columns means nothing else can be changed by accident.

Checklist before you import

Started from Xero's template or an export of your contacts
A contact name on every row, spelled as in Xero for existing contacts
1,000 contacts or fewer per file
Bank account numbers with hyphens, not scientific notation
Values within Xero's character limits
Tax rates, account codes and tracking options matching Xero exactly
Both halves of each payment term filled in
Empty fields set to Be ignored, unless you mean to clear them
A test import in the demo company first

Collecting contacts from a client?

Send them a form instead of a spreadsheet. The Xero Contacts template requires a unique contact name on every row, keeps to Xero's character limits, checks emails, phones and websites as they're entered, and keeps bank and tax numbers as text. Using QuickBooks? See QuickBooks CSV import errors.

Try the Xero template

Related Guides

Relevant Templates

Import Builder is an independent product and is not affiliated with, endorsed by, or sponsored by Xero Limited. Xero is a trademark of Xero Limited. Import rules as described in Xero Central, October 2026.