Import customer or supplier contacts using a CSV or TXT file

Import your customer or supplier contacts into Xero in one go using a CSV or TXT file you've created or exported from another system.

Importing contacts Video (2.28) Importing contacts

You don't have to enter contacts in this way - you can add them individually in Xero by adding them from Contacts or they'll be added automatically when you create an invoice, bill or transaction for a customer or supplier for the first time.

If you already have contacts in Xero you can import additional contacts, make changes to existing contacts, or export your contacts.

You can't import contacts to a particular group. You can only allocate contacts to a group after you import them.

To import contacts into Xero go to Contacts > All Contacts and click on the 'Import' button. Users who have access to contacts can import. Contacts can be imported any time after setup is complete. You can't import employee contacts.

Contact import

You need to save your file in a CSV format, and not just rename a file so that it contains '.csv' or '.txt'. Xero will not accept any other file type. Then, as long as you follow some specific rules below, Xero will understand the data you put into your CSV file and will know how to create your Chart of Accounts from it.

Create & import your Contacts file

From any tab in Contacts, choose the Import button to go to the Import Contacts screen.

Import contacts

If you want to start with Xero's blank template or reformat your contacts from an existing system to match the template, you'll need to go to the Import Contacts screen initially to get the template even if you're not ready to import your contacts right away.

Download template

You need to be logged into Xero & on the Import Contacts screen in order to access the Contacts template link

Use the Xero template

Contacts need to be imported into Xero in the CSV format from a .csv or .txt file using a template that Xero can use to map values in your file to Contact fields in Xero.

Blank template

From the Import Contacts screen, click on the 'Download template file' link to save or open a blank template containing the headings under which you need to enter or copy your contacts' details. Depending on how your computer is set up, the CSV template provided by Xero will most likely open in Excel.

Import template

Export first & update

If you already have some contacts in Xero and want to add a whole lot more, or make some changes to the contacts you already have, you can Export your Contacts from Xero in the CSV format ready for you to make updates to.

If you're importing contacts into an organisation that already has contacts, or you want to edit your current contacts offline, take note of the points below that describe what happens when you import updated contacts back into Xero.

Enter contacts

Copy contacts from another system like MYOB, Quickbooks, Sage, Outlook, Entourage or any CRM system that you can export your contacts or address book from

 

Enter or copy your contacts into the CSV file

Whether you started with the blank Xero template or have got a file of your contacts exported from Xero or another system, enter or change contacts in the columns provided in the CSV file.

Blank template

If you have started with the blank template, make sure you enter or copy information from another exported file into the right columns on the template, one contact per row.

Excel

If you're not familiar working with CSV files, you'll probably find it easier to use Excel because you can work with your data in columns rather than in a straight line separated by commas as with a text editing program.

Notepad

Contacts exported from Xero

If you're updating a file that you've exported from Xero make sure you keep the updated information within the same original columns.

Xero export

Tips & rules for entering contacts

Enter your contacts to the CSV file one contact per row.

  • Ensure you save in CSV format (like 'somefilename.csv'). If in doubt when using Excel, save the file again ensuring it is saved as one of the CSV file types, e.g. CSV (MS-DOS) or CSV (Comma delimited).
  • Xero will also accept comma separated values in a text-based file (created by a program like Notepad or Text Edit) which when saved will have a name like 'somefilename.txt'.
  • You must leave the first row in place as the header row and all columns must all be present and in the same order as the template file or the file you've exported from Xero. If you're copying data from another system, make sure you use this exact format. If you delete the header row Xero will not import your file.
  • Xero understands the order of the columns or comma separated values to determine which fields in Xero to put the contact information you've entered.
  • The CSV file is essentially 'mapped' column or group of columns to fields in Xero so by completing contact information column by column you're essentially 'filling in' the fields in Xero automatically.
    E.g. Name column goes to Name field; EmailAddress column goes to Email Address field; POAddressLine1, POAddressLine2, POAddressLine3 and POAddressLine4 all go to Street Address or PO Box field; POCity column goes to Town/City field and so on.
  • All columns except Name are optional. If you have no use for a column e.g. none of your contacts has State/Region, you may either leave the relevant column blank, or you can simply delete the columns you don't need.
  • Every contact entered must at least have a name and it must be unique. All other columns can be left blank or removed if required.
  • If you enter more than one contact with the same name, regardless of whether all the other information is different, Xero will treat them as duplicates and will just import the first of the contacts with the same name. You cannot enter 2 contacts with the same name in Xero either.
  • The data entered in the EmailAddress, FirstName and LastName columns will populate as the primary person in the contact. Additional people's details cannot be included in the import file - enter them in the contact in Xero when the import is completed.
  • If you have created more than one tax code with the same name (e.g. with different tax rates), then Xero will only import the first tax code.
  • The columns that require data to be entered in a specific format are the:
    • EmailAddress - If you enter an email address make sure it's in an email format using @ and dots
    • phone number fields - Enter full phone numbers with spaces between the different components of the phone number i.e. between the country code and area code, and between the area code and phone number itself. These are individual fields in Xero and the number will be added into these fields depending on the spacing you've used in any of the phone or fax number fields on your file
      Ph map
    • Accounts Receivable GSTVATTax and Accounts Payable GSTVATTax - Make sure you use exactly the same name used in the Name field in the Tax Rates screen.
    • Bank account number columns in Excel - you may need to change the number formatting to ensure that Excel is displaying your bank account numbers appropriately, e.g. not displaying numbers with decimal places. The numbers will not display correctly in Xero if they do not display correctly in the CSV file.
    • Website - this must have http:// at the beginning of the address, for example, http://www.xero.com.
    • Discount - enter the number to 2 d.p. and without the % sign.
    • DueDateBillDay or DueDateSalesDay - Enter up to:
      • 2 numbers, if you enter 'Current Month' or 'Following Month' in the DueDateBillTerm or DueDateSalesTerm field
      • 3 numbers, if you enter 'Days After' in the DueDateBillTerm or DueDateSalesTerm field.
    • DueDateBillTerm or DueDateSalesTerm - Enter one of the following (exactly, and with spaces and capitals):
      • Current Month
      • Following Month
      • Days After
  • All other columns can have any letters and numbers entered into them.
  • You can’t enter the Xero Network key or Invoice Branding option (or the Default currency if you’re using multi-currency) for your contacts in the CSV file. Enter these fields manually in the individual contact record in Xero.
  • The order in which you enter your contacts on the CSV file doesn't matter; they can be alphabetical or as you enter them. Contacts are displayed in Xero alphabetically regardless of the order they are on the spreadsheet.
  • You cannot distinguish on the CSV file between customers and suppliers. This will be determined in Xero when you enter customer invoices or supplier bills for a contact.
  • If you are using Excel to create your CSV file take care not to enter figures and symbols which could be automatically reconfigured by Excel to read as dates or numbers or some other formula as this data will be imported as is into Xero.
  • If the name field is empty or the email address is not formatted correctly or there are any other errors with your CSV Xero will tell you about these on the Import Summary screen where you can choose to proceed without the contacts that have errors or cancel the import process and make corrections to your CSV.

If you're working with a CSV file from another source and have opened it in Excel, make sure the comma separated data is spread across the columns under each relevant heading rather than all data displaying in the first column of the spreadsheet. Sometimes this happens by default if you open the CSV using Excel, to ensure the data displays correctly you might need to open Excel first then use the import feature in Excel to import the CSV data. If all your data appears as comma separated in the first column of the spreadsheet it will fail to import into Xero.

Convert TXT data into columns

Update existing contacts using the CSV import

If you've exported existing contacts from Xero into a CSV file, you can edit them and then import them into Xero.

As well as the above guidelines for putting new contacts into a CSV file, please take note of the following:

  • Only the primary person's name and email address will be included in the exported file. If this is changed in the CSV file, it will overwrite the existing data in the contact on import.
  • Additional people's names and email addresses in contacts are not included in the export file and are not affected by the import.
  • You have a choice of how you want Xero to handle any empty fields (blank cells) in your CSV file. Xero can either ignore the empty fields or wipe any existing information from the corresponding fields in Xero.

    Choose whether to ignore empty fields or overwrite existing information.

    • 'Ignore empty fields' - it will retain existing information.
    • 'Empty fields should delete existing information' - it will allow any blank cells in your CSV file to wipe existing information from their corresponding fields in Xero. For example, if you remove all the data from the 'Email' column in your CSV file, and select this option, all your email addresses will be removed from your contacts in Xero.

If you add new contacts to those already in the file

  • New contacts added to those already in the file will be imported into Xero as new contacts.

Contact names are unique identifiers

  • If you want to change a contact's name, do this within Xero, not via the CSV import. Editing a contact in Xero to change its name will update any transactions and information that already exist for the contact with the new name.
  • Keep the name the same if you want to update an existing Xero contact. If you change a contact's name in the CSV file, Xero will not recognise the new name as a contact already existing in Xero to update so will import it as a new contact (essentially creating a duplicate).

Removing, merging or restoring contacts

  • You can't merge, archive or restore archived contacts via the CSV import. You can do these tasks within Xero.
  • If you delete a contact (entire row) from the CSV, the contact will not be removed or archived in Xero. If you no longer want a contact to be active in Xero, you need to archive or merge it within Xero.

Contact types are not exported with the contact out of Xero

  • If you're working with a CSV file of exported contacts you can't change any of this information. Transaction and grouping is retained in Xero and will still be the same when you import your updated CSV back into Xero. As described above, if you change the name of your contact, Xero will treat this as a new contact so no grouping or transactional information will be present for the contact in Xero.

If you've imported a file with information in the wrong columns

  • If you previously imported a file into Xero with information in the wrong columns, you can export it back out to a CSV, make the necessary changes to move the data into the right columns and import it again.

Import

Browse

Import

Cancel button.

 

Locate and select the file to import

Click the Browse button to locate the CSV or TXT file you want to import into Xero.

Select file

Browse your computer's file system to find the CSV file you've saved on your computer.

Browse file

  • Make sure you have saved the file you want to import.
  • Xero will only accept a .csv or .txt file.
  • You can import up to 1000 contacts per file. If you have more than this, as long as you don't have duplicate contact names, you can import separate files of contacts in groups of 1000 and these will be added to those already imported into Xero.

Click the Update button to bring the contacts from the file into Xero where you will be asked to confirm the import before finally importing the contacts into Xero.

Import

Click the Cancel button if you want to stop the import process for now.

Confirm the contact import

Confirm

Complete

Go back

Review the contacts to be imported

Once you have created your Contacts file and selected the .csv or .txt file to import into Xero, you can review what's going to be imported before finally completing the process.

Import summary

  • As long as you have followed the guidelines for entering contacts on the CSV, including the mandatory header row and mandatory name for each contact, and valid email address formats have been used you'll see that Xero will import the same number of contacts into Xero as you have on your CSV.
  • If there is something wrong with the structure of your file i.e. missing or incorrectly labelled columns, missing header row or incorrect format, Xero will not import the file.
  • If individual contacts on your CSV cannot be imported or are duplicates, the reasons why will be listed so that you can stop the import process to fix your CSV and try again.
  • Use the line item numbers given in the list of errors to identify where the contacts are on your CSV which need to be fixed.

Errors

  • In Excel the line numbers correspond to the row number.
  • If you're working with a text (TXT) file in the Notepad program, line numbers will be displayed if you have the program set up to show the status bar (do this from the 'View' menu).

Notepad

  • If you want to address the errors on your CSV file, use the Go Back button to stop the import process to make corrections on your CSV before importing it again.
  • If you want to proceed without importing the erroneous contacts, click the Complete Import button. You can manually add the missing contacts in Xero or import another CSV containing those that weren't imported.
  • Once imported, your contact will display on the All tab in Contacts. From there you can create groups, update information, merge or archive and start entering transactions for these contacts.