Skip to main content
Import a CSV file to create or update many contacts at once, and export contacts to a CSV file for use in another tool. Both run from the Contacts page.
Contacts in your OpenCX dashboard. The page has no sidebar entry: press ⌘K (Ctrl+K on Windows) and choose Contacts. See keyboard shortcuts. Importing requires the Contacts permission with Write; exporting the list requires Read.

Prepare your file

Empty rows are skipped, and spaces around values are trimmed.

Import contacts

Importing a CSV of eight contacts: Add contacts, Import from CSV, the detected columns, automatic column mapping, match by phone, and a preview of 7 new contacts and 1 update

Upload, Map columns, Options and Preview: the preview counts new and updated contacts before anything is saved.

1

Open the import

On the Contacts page, select Add contacts → Import from CSV. On an empty contact list, Import contacts opens the same dialog.
2

Upload

Drop the file on the upload area or click to browse. The dialog shows the row count, the column count and the detected columns. Select Choose another file to start over.
3

Map columns

For each column, pick what it becomes: Name, Email, Phone, Language, Custom data (with a field key you can edit) or Don’t import. Common headers such as Name, Email, Phone, Mobile, WhatsApp and Language are matched for you, and every other column starts as custom data named after its header. Map at least one column, and use each field and each custom data key only once.
4

Choose options

Set Match existing contacts by, When a match is found and Only fill blank fields (see How rows are matched). Below them, you can tag every imported contact with the same custom data. An import_batch field is filled in for you with the date and file name, such as 2026-07-30-contacts. Use Add field for more.
5

Preview

OpenCX checks the whole file without saving anything and shows how many rows are new, will update existing contacts, are duplicates within the file, or are invalid. Invalid rows and cells are highlighted in the first 50 rows. Select Import N contacts to start.
6

Follow the import

A progress bar shows rows processed. You can close the dialog: the import keeps running, a spinner shows on Add contacts, and a notification reports the totals when it finishes. Cancel import stops it; contacts already imported stay.
7

Review the result

The result lists contacts created, updated, skipped and failed, plus duplicates in the file and rows that matched more than one contact. Row errors are grouped by reason; up to 1,000 are listed, and the counts include every row. Download error rows saves those rows with their original columns plus an error column. Fix them, set the error column to Don’t import, and import that file.
To find the contacts from one import later, filter the contact list on Custom data import_batch equals the batch value. Imported contacts show csv as their source.

How rows are matched

Match existing contacts by is an ordered list. For each row, the first property in the list that the row has a value for decides which existing contact it is. Use Add fallback to add properties, shown as then, if blank. The default is Phone number. For example, match by a custom field customer_id, then Email: rows with a customer ID match on it, and rows without one match on their email. At least one property in the list must be mapped to a column. Don’t match (always create) turns matching off, and every row creates a new contact. When a row matches an existing contact: A few rules apply to every import:
  • Blank cells never erase data. An empty cell leaves the existing value alone.
  • Tags from the Options step are always written, even with Only fill blank fields on, so every contact in the import carries the batch value. A row’s own value for the same key wins over the tag.
  • Repeated rows are skipped. A row with the same identity as an earlier row is listed as “Duplicate of row N”.
  • Several matches use the newest. If a row matches more than one contact, the most recently updated contact is used.
  • An email can’t be taken from another contact. A row that would give a contact an email another contact already has fails with “Email already belongs to another contact”.
  • Matching needs distinct values. If the property you match on is shared by more than 20,000 existing contacts, the preview stops and asks you to match on a property with distinct values per contact.
Imports don’t start workflows: a contact created by an import doesn’t fire contact triggers. Segment membership is updated for every contact the import created or changed.
In a sequence’s Audience tab, when no contacts are targeted yet, the Add contacts menu offers Bulk Import, Connect with CRM, Import via API and Import history. An import started there points the sequence’s audience at that import’s batch when it completes.Import history lists your 20 most recent imports with their status, created and failed counts. Open a completed import to see its result and select Target these contacts to point the audience at that batch. Error rows downloaded from history list only the row number, column and message, not the original row data.
The upload step links to Settings → CRMs to sync contacts from a connected CRM, and to the create contact API for imports from your own systems.

Export contacts

1

Open the export

On the Contacts page, select the export button in the list toolbar (Export contacts).
2

Choose what to export

Current view exports what the list shows: the selected view, search and filters, in the list’s order. All contacts exports everyone and ignores filters. Each option shows its contact count.
3

Choose columns

Contact ID, Name, Email, Phone, Source and Created at are checked by default. Under Custom properties, every custom data key used on your contacts is listed and checked; uncheck the ones you don’t need.
4

Download

Select Export CSV. The file is built in your browser and downloads as contacts_export_<date>.csv. Keep the dialog open until the download starts.
One export holds up to 10,000 contacts, or the top 1,000 matches when a search is active. If the scope is larger, the file contains the first contacts and a warning asks you to narrow the scope with filters and export again. To export a few contacts, select their rows and choose Export CSV in the selection bar. This downloads the selected rows from the current page with the fixed columns only, and requires Write.

Troubleshooting


Manage contacts

Find, filter and edit contacts.

Segments

Group contacts with saved conditions.

Create a contact (API)

Add contacts from your own systems.

Sequences API

Reach imported contacts with outbound sequences.