Bulk Import Contacts into Xero from a Spreadsheet

Why contact imports go wrong

A contact list rarely arrives clean. Names get typed slightly differently between systems, addresses are split across inconsistent columns, and the same customer shows up under a shortened name in one export and a full legal name in another. Xero's own CSV contact import accepts a fixed set of columns and matches on name, but it doesn't tell you beforehand which rows will create a new contact and which will update an existing one, so a load of a few hundred rows can leave you with a mix of updated records and quiet duplicates you only notice later.

What decides update vs. create

A contact import needs an upsert key: a value that tells Xero "this row is the same contact as last time." Two fields can do that job. The contact's display name, if it matches an existing contact exactly, updates that contact. A contact number, your own reference code stored on the Xero contact, matches an existing contact by that code even if the display name has since changed. Deciding which key you're relying on before the import, and checking it against the live contact list first, is what actually prevents duplicates.

Fields worth including

• Name, and separately first name and last name where the contact is a person rather than a business.
• Contact number, if you maintain your own reference codes across systems.
• Email and phone.
• Street address, city, region, postal code, and country, written to the contact's postal address, which is what appears on invoices.
• Tax number: ABN, VAT, GST, or EIN, whichever applies in your region.
• A default currency, for contacts you invoice or bill in a currency other than the organisation's base currency, provided that currency is already enabled in Xero.

Running it safely

1. Resolve every name (or contact number) in the sheet against the organisation's live contact list before importing anything, so you know upfront how many rows will create new contacts versus update existing ones.
2. Check tax numbers and currencies for obviously wrong formats or currencies not enabled on the organisation.
3. Import a small batch first and confirm in Xero that the right contacts were created or updated, not duplicated.
4. Run the remainder once the pattern is confirmed correct.

Importing invoices or bills next?

Once contacts are clean, see how to bulk import invoices into Xero from a spreadsheet or how to bulk import bills into Xero from a spreadsheet, both of which resolve against the same contact list.