# Importing contacts ### Overview Importing is the quickest way to get a large number of contacts into your UbiQuity database, or to update existing ones in bulk. Rather than adding contacts one by one, you prepare your data in a spreadsheet, export it as a CSV, and work through the import wizard. You can also use the import function to bring contacts in directly from UbiQuity Survey responses or Event registrations, without needing to download data from those modules first. To access the import screen, go to **Database** then **Manage Imports.**
Screenshot of the Import Contacts screen in UbiQuity showing the Import Contacts button in the left panel and a table listing previous imports with their details and progress.

The Import Contacts screen, accessed via Database then Manage Imports.

*** ### Before you start A few things worth checking before you run an import: * Your file should be in CSV or text format. Excel workbooks are not supported - if your data is in Excel, save it as a CSV before importing. * Your file should ideally have column headings in the first row. These do not need to match the names of your UbiQuity fields exactly, as you will map them during the import. * Give your import file a meaningful name before uploading. The file name becomes the import name in UbiQuity, and a descriptive name makes it easier to identify later - especially if others share the account. * Check that your data is clean and consistent. UbiQuity validates data against field types during the import, and rows that do not match will be rejected. *** ### Step 1 - Select import source On the Import Source screen, choose how you are importing your data: * **Import from a file** - Upload a CSV or text file from your computer * **Import from an Engage survey** - Pull in responses from a UbiQuity survey * **Import from an Engage event** - Pull in registrations from a UbiQuity event If importing from a file, select your file and confirm that the first row contains field names.
A screenshot of the Import Source screen showing the import type selector, file upload, and a data preview.

The Import Source screen showing the import type selector, file upload, and a data preview.

*** ### Step 2 - Map your fields Field mapping is one of the most important steps in the import process. This is where you match the columns in your file to the correct fields in your UbiQuity database. For each column on the left, select the corresponding UbiQuity field on the right. If a column is not relevant, you can choose to ignore it. If you need a field that does not yet exist in your database, you can create a new one directly from this screen (subject to your user permissions). After mapping, a data preview will show a snapshot of how your data will be brought in. If you have ignored or added columns, click Refresh to update the preview.
A screenshot of the Field Mapping screen showing Import Fields mapping, as well as a Data Preview below.

The Field Mapping screen showing Import Fields mapping, as well as a Data Preview below.

*** ### Step 3 - Analysing data UbiQuity analyses your data before making any changes to the database. Any rows that do not meet the required criteria are identified and rejected at this stage. Rows are rejected here if the data does not match the field type. Common examples include an email address missing the @ symbol, or a mobile number with a missing leading zero. If you see rejections at this stage you have two options - download the error list, cancel the import to fix your file and start again, or continue with the import and download the errors at the end.
A screenshot of the Analysing Data screen showing the valid rows and invalid rows, and progress status.

The Analysing Data screen showing the valid rows and invalid rows, and progress status.

*** ### Step 4 - Select update type Choose how UbiQuity should handle the records in your file: * **Append/Update** - Adds any contacts that do not already exist, and updates those that do. This is the most commonly used option. * **Append** - Only adds new contacts. Any contact that already exists in the database will be skipped. * **Update** - Only updates existing contacts. Any contact that does not already exist will be skipped.
A screenshot of the update type screen showing the three import options — Append/Update, Append, and Update.

The Update Type screen showing the three import options — Append/Update, Append, and Update.

#### Matching fields For Append/Update and Update imports, UbiQuity needs to know how to identify whether a contact already exists. This is done using matching fields - the fields UbiQuity will use to look up each row against your existing contacts. You should use the unique field or fields set on your database. For example, if your database is unique on email address, select Email Address as the matching field. If it is unique on a combination of fields, select all of them. Do not tick all available columns - this will likely cause rows to be rejected.
A screenshot of the Select Matching Fields screen with Email Address selected as the matching field.

The Select Matching Fields screen with Email Address selected as the matching field.

#### Importing blank values If your file contains blank values for some fields, you can choose how UbiQuity handles them: * **Preserve existing data** - Blank values in the file are ignored, and any existing values in the database are kept. * **Import blank values** - Blank values in the file will overwrite existing values in the database.
A screenshot of the Importing Blank Values screen showing the two options for handling blank fields in the import file.

The Importing Blank Values screen showing the two options for handling blank fields in the import file.

*** ### Step 5 - Indexing data Indexing is the second stage where rows can be rejected. Rows fail here due to duplication issues rather than data formatting problems. This happens when your file contains two rows with the same matching field values, or when a row in your file matches multiple contacts in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. As with the Analysing Data stage, you can download the error list and either cancel to fix your file or continue and review errors at the end.
A screenshot of the Indexing Data screen showing the rows to insert, update and skip, and progress status.

The Indexing Data screen showing the rows to insert, update and skip, and progress status.

*** ### Step 6 - Confirm The final screen shows a summary of your import before it runs, including the import type, matching criteria, blank value handling, and a full mapping table showing how each column will be handled. Review the details carefully, then click **Finish,** type **ACCEPT** and click **Import Contacts** to run the import.
A screenshot of the Confirm Import Details screen showing a summary of import settings and a field mapping table.

The Confirm Import Details screen showing a summary of import settings and a field mapping table.

A screenshot of the Import Contacts confirmation dialog where you type ACCEPT to run the import.

The Import Contacts confirmation dialog where you type ACCEPT to run the import.

**Import progress** Once the import is running, the progress screen will show when it has completed, including a breakdown of rows inserted, updated, and skipped. If any rows were skipped, an error file will be available to download at the bottom of the page. This file is only available for 7 days after the import, so download it promptly if you need to review and fix errors. You can return to this screen at any time from the Import Contacts list by clicking the page icon next to a previous import.
A screenshot showing the import progress screen showing the rows inserted, updated and skipped, with progress status.

The import progress screen showing the rows inserted, updated and skipped, with progress status.

*** ### Frequently asked questions **Why are there invalid rows during the analysing stage?** This is caused by data in your file not matching the field type in the database. Common examples are an email address missing the @ symbol, or a mobile number where the leading zero has been dropped by Excel. Mobile numbers must be in NZ format (02 + 6 to 9 digits) or include an international country code such as 6421 123 456. **Why are there invalid rows during the indexing stage?** This is caused by duplicate matching field values - either in your import file or in your database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. Check your file for duplicate entries on the matching field. **What should I select for matching fields?** Use the unique field or fields set on your database. You can find these under **Database > Edit Fields** at the bottom of the page. If you are unsure, contact your UbiQuity account manager. **Why is my file not uploading?** UbiQuity only accepts CSV and text files. Excel workbooks (.xls or .xlsx) are not supported. To convert, open your file in Excel and save it using the CSV option - note that CSV files can only contain a single sheet. **Why does the number of contacts in my import differ from my mailout filter?** Contacts that are opted out or marked as GNA are automatically excluded from email sends. The import may have succeeded for those contacts, but they will not appear in an emailable filter. See Opt Outs and GNA for more information. **Why can I not add new contacts?** If you see the error "In order to Append contacts you need to have mapped all mandatory fields with no default values", it means your database has a mandatory field with no default value that is not included in your import file. Every new contact must have a value for this field. Check your mandatory fields under **Database > Edit Fields** and either include the field in your import or remove the mandatory requirement if it is no longer needed. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ubiquity.co.nz/documentation/data-and-integrations/imports/importing-contacts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.