Work with data in the source .csv file - Genesys Cloud Resource Center
Work with data in the source .csv file
AI-generated summary
Genesys Cloud's bulk import process uses External IDs as the required unique identifier for contacts, enabling precise record creation and updates through CSV file uploads. External IDs can contain any combination of letters and numbers up to with UUIDs from CRM systems recommended for future synchronization capabilities. Phone numbers and email addresses serve as secondary matching identifiers; phone numbers must follow E.164 format to ensure accurate call and SMS syncing and proper contact merging. During import, the system matches contacts by External ID, phone, and email, then merges matched records while retaining the most recent CSV data and deduplicating existing emails and phones to prevent data loss.
The same External ID must be used consistently to update existing records rather than create duplicates; changing the External ID results in a new record. If phone numbers lack E.164 formatting, the import continues but identity resolution accuracy for phone-based matching is not guaranteed. The contact title field header has been renamed from "Contact Title" to "Contact Job Title" in the new Bulk Import process, and legacy templates using the old header may fail to import job title values during mapping.
For external organizations, the External Organization External ID serves as the unique identifier determining record creation, with the import process generating one organization record per unique ID and supporting composite keys up to Multiple external contacts can be associated with a single external organization by assigning the same External Organization External ID, though all organization-specific fields across related rows must be identical. Manually created organizations cannot receive imported members via CSV file.
Contact records in Genesys Cloud exist in three types: Ephemeral (auto-generated with web identifiers only, 60-day TTL), Identified (auto-generated with PII, 60-day TTL), and Curated (manually created or promoted by agents/API calls, no TTL limit). Ephemeral and identified contacts do not appear in search APIs or reverse-whitepages lookups.
During merge operations, the system applies a hierarchy for conflict resolution: CSV data takes priority for most fields, but values from the newest curated contact are used when conflicts exist between curated and identified contacts. Null values from CSV imports are not applied, allowing existing contact data to remain intact. When multiple values exist for the same field type, the system relocates data to alternative available fields rather than discarding information. Field-specific import settings, such as the Import Field checkbox, control whether existing contact data is overwritten or preserved during the merge process. The "Update first matched contact only" option restricts merge operations to a single matching contact, leaving other partially matching contacts unchanged. The External ID from CSV records becomes the primary identifier in merged contacts, replacing previously used contact IDs
External ID is the required key field that Genesys Cloud’s import process uses to determine unique contacts. This field helps identify contacts so that you can easily update existing contacts via the same spreadsheet. For each unique External ID, the import process creates one Genesys Cloud external contact record. The import process imports all the contact fields in the row to the corresponding Genesys Cloud external contact record.
When you create an External ID, you can use any combination of letters and numbers. For example, you can use a unique identifier from your CRM or ERP system, or you can create a composite key that is meaningful to you. It can be any External ID you want to use to identify the record, as long as it meets the 255 character limitation. If your .csv is extracted from a CRM, we recommend using unique identifiers (UUIDs) from your CRM. UUIDs allow synchronizing contacts from your CRM in upcoming feature updates.
If you only plan to import the record once, you can use any external ID you want. The system generates internal IDs to correspond with those external IDs.
Notes:
If you have previously imported your contacts using the old Bulk Import process, the system only uses the Phone or Email Address identifiers to match and update your contact with the new External ID.
To successfully merge the existing contacts with the new records, when you perform the .csv bulk import, it is important that all phone numbers in the .csv file follow the E.164 format when matching by phone.
If phone numbers in your .csv file do not follow the E.164 format, the data validation step of the import process triggers warnings. While the import process continues to import the contacts, there is no guarantee that the identity resolution algorithm accurately matches and merges the contacts based on phone numbers.
If your old contacts do not have an email or phone number that matches the email or phone in your new .csv file, the system creates a record with your specified External ID in the .csv.
If a contact’s information is repeated multiple times in the same file, the contact updates multiple times, and the rows imported counter reflect the repetition. However, the order in which the updates occur is not guaranteed.
The contact title field header is renamed from Contact Title to Contact Job Title in the new Bulk Import process. If you use old templates that still use Contact Title in the header, the import process may not import the job title values and the field may appear as missing during import mapping.
When updating previously imported contacts, ensure you use the same External IDs to avoid creating duplicate records.
For example, if you import a spreadsheet with a record using ‘A’ as the External ID and later reimport the same spreadsheet with ‘B’ as the External ID for that record, Genesys Cloud creates a record instead of updating the existing one. To update an existing record, always use the same External ID.
Notes: Phone numbers must be in E.164 format to sync call and SMS interactions with that phone numbers.
External organizations
The External Organization External ID is the key field, which the import process uses to determine unique organizations. For each unique External Organization External ID, the import process creates one Genesys Cloud external organization record. The import process imports all the account fields in the row to the corresponding Genesys Cloud external organization record.
When you create an External Organization External ID, you can use any combination of letters and numbers. You can create a composite key that is meaningful to you, as long as you meet the 255 character limitation. If your .csv is extracted from a CRM, we recommend using unique identifiers (UUIDs) from your CRM. UUIDs allow synchronizing contacts from your CRM in upcoming feature updates.
Associate an external contact with an external organization
To associate an external contact with an external organization, type them on the same line in the .csv source file.
Note: In the following example, some fields are resized or hidden.
In this example, Angus Reid is a Problem Solver for Phoenix Foundation II. The import process creates the external organization record for Phoenix Foundation II and an external contact record for Angus Reid. In External Contacts, Angus Reid appears as an external contact for the Phoenix Foundation II organization.
Associate multiple externalcontacts with one external organization
To associate multiple external contacts with one external organization, assign the same External Organization External ID to all of them.
Note: In the following example, some fields are resized or hidden.
In this example, Kathryn, Josh, and Rebecca are all contacts for the Office Mart organization.
Notes:
If multiple rows share an External Organization External ID, all organization-specific fields must be identical (for example, Account Name) and Genesys Cloud creates one External Organization for all related contacts. Genesys Cloud imports only one row per External ID, creates one External Organization for all related contacts and does not guarantee which row is used. If differences exist across rows, each row is sent separately for updates to the External Org.
You cannot use a .csv file to import members to an organization that you manually created.
How the bulk import process manages the merge actions
In this example, import contacts only and assume that all external contact organization fields in the .csv file are empty.
During the Bulk Import process, the following options were selected in the Import Profile screen:
Match Contacts by: External ID, Phone Number, and Email Address
Merge Matched Contacts: Merge and update all matched contacts
In this example, the following identifiers are searched:
ExternalID: 123AABC
phone: +1 919 432 5523
email: tom.sellenta@sag.aftra.com
The Work Phone from .csv is matched with Contact C’s mobile phone number. A new merged ContactD is created.
In the following table,
The Field Name column indicates the field name in the .csv file.
The CSV Data (Enrich Request) column indicates the data from the .csv file.
The Contact B column is a curated contact in Genesys Cloud.
The Contact C column is a curated contact in Genesys Cloud.
The Contact D column is the merged contact after completion of the import.
The Explanation column describes how the Contact D column data was imported.
Field Name
CSV Data (Enrich Request)
Contact B
Contact C
Contact D (Merged Contact)
Explanation
External ID
123AABC
123AABC
The External ID from the .csv record enriches the merged record as its primary identifier. The Contact ID used by the old .csv import is no longer used or displayed in the contact records.
firstName
Tom
Tommy
Tom
Tom
Data conflict, the merged contact retains the most recent data from the .csv file.
middleName
T
T
Null values are not used from the .csv imports. Contact C’s value is used.
lastName
Selleck
Selk
Selleck
Data conflict, the merged contact retains the most recent data from the .csv file.
title
Problem Solver
Problem Solver
Value from Contact C is used.
salutation
Mister
Mr.
Mister
Data conflict, the merged contact retains the most recent data from the .csv file.
work Email
tom.selleck@sag.aftra.com
tom@gmail.com
tom.selleck@sag.aftra.com
tom.selleck@sag.aftra.com
Data conflict, the merged contact retains the most recent data from the .csv file.
personal Email
tom@hotmail.com
tommy@yahoo.com
tom@gmail.com
Emails and phone numbers are handled carefully during merges to avoid data loss. If two contacts use the same field (for example, workEmail), the data is moved to another available field (for example, personalEmail or otherEmail).
In this example, “tom@gmail.com” is moved from workEmail to personalEmail instead of dropping it. This process continues iteratively until all possible fields are used. If space is limited, older emails are dropped to accommodate request values.
other Email
tommy@hotmail.com
The specific field names aren’t important and data is preserved from merged contacts wherever possible. If no available fields remain for relocation, the data is dropped.
cell Phone
+1 919 432-5523
Work Phone from .csv is matched with Contact C’s cell phone.
work Phone
+1 919 432-5523
+1 317 845-1232
+1 317 845-1232
As the Import Field checkbox was cleared, Contact C’s WorkPhone remains unchanged after the import.
home Phone
No updates, no value in any contact.
other Phone
No updates, no value in any contact
This example imports contacts only. The assumption is that the External Org fields in the .csv file are empty.
During the Bulk Import process, the following options were selected in the Import Profile screen:
Match Contacts by: External ID, Email Address, Phone
Merge Matched Contacts: Update first matched contact only
In this example, the order of identifiers searched for is: (The email id comes before ExternalID)
ExternalID: 123AABC
email: tom.selleck@sag.aftra.com
phone: +1 919 432-5523
The Work email from .csv is matched with Contact C’s Work Email and the work phone was matched to Contact B’s cell phone. As the Merge and update all matched contacts option is not selected, only Contact C will be updated after the import and the Contact B remains unchanged, even though both contacts partially match the CSV data.
In the following table,
The Field Name column indicates the field name in the .csv file.
The CSV Data (Enrich Request) column indicates the data from the .csv file.
The Contact B column is a curated contact in Genesys Cloud.
The Contact C column is a curated contact in Genesys Cloud
The Updated Contact C column is the data after the completion of the import.
The Explanation column describes how the Contact D column data was imported.
Field Name
CSV Data (Enrich Request)
Contact B
Contact C
Updated Contact C
Explanation
External ID
123AABC
123AABC
The External ID from the .csv record enriches the Contact C record as its primary identifier.
The Account ID used by the old .csv import is no longer used or displayed in the contact records.
firstName
Tom
Tommy
Tom
Tom
No conflict, no change.
middleName
T
T
.csv has no value for middleName, but Contact C does.
Therefore, Contact C’s middleName value does not change.
lastName
Selleck
Selk
Selleck
Conflict. Update Contact C with data from the .csv.
title
Problem Solver
Problem Solver
No updates since the Import field is cleared.
salutation
Mister
Mr.
Mister
Conflict. Update Contact C with data from the .csv.
work Email
tom.selleck@sag.aftra.com
tom@gmail.com
tom.selleck@sag.aftra.com
tom.selleck@sag.aftra.com
Work email from the .csv is matched with Contact C’s Work Email.
This contact is updated after the import and Contact B remains unchanged as it was not the first contact matched and Contact C was the first matched contact.
personal Email
tommy@yahoo.com
tom@yahoo.com
No updates since the Import field is not selected.
other Email
No updates, no value in any contact.
cell Phone
+1 317 845-1232
+1 317 845-1232
No updates since the Import Field is not selected.
work Phone
+1 919 432-5523
+1 317 845-1232
+1 919 432-5523
As there is a conflict, Contact C is updated with data from .csv.
home Phone
No updates, no value in any contact.
other Phone
No updates, no value in any contact.
In this example, some contacts are identified, and some contacts are curated.
Contacts can be one of three types:
Ephemeral: An autogenerated contact that is associated with a client-side web identifier or cookie, but it has no other information. In other words, it is an empty contact where a web cookie/client-side identifier points to it. They have a 60-day time-to-live (TTL) limit.
Identified: An autogenerated contact having non-cookie PII and has a 60 day TTL limit.
Curated: Contacts that have been created or _promoted_ by agents or API calls. They have no TTL limit.
Ephemeral and identified contacts are system-generated and do not appear in search APIs, reverse-whitepages lookups, or scans.
The following two contacts are matched in the system:
Contact B (Curated)
Contact C (Identified)
During the Bulk Import process, the following options were selected in the Import Profile screen:
Match Contacts by: External ID, Email Address, and Phone Number.
Merge Matched Contacts: Merge and update all matched contacts.
In this example, the following identifiers are searched:
ExternalID:123AABC
email: johnny@gmail.com
phone: +1 919 432-5523
The Personal email field from the .csv file is matched with Contact C’s other Email field, that is, johnny@gmail.com.
Work phone from .csv is matched with Contact B’s cell phone, that is, +1 919 432-5523.
In the following table,
The Field Name column indicates the field name in the .csv file.
The CSV Data (Enrich Request) column indicates the data from the .csv file.
The Contact B column is a curated contact in Genesys Cloud.
The Contact C column is an identified contact in Genesys Cloud.
The Contact D column is the merged contact after completion of the import.
The Explanation column describes how the Contact D column data was imported.
Field Name
CSV Data (Enrich Request)
Contact B
Contact C
Contact D
Explanation
External ID
123AABC
123AABC
The External ID from the .csv record enriches the Merged Contact D record as its primary identifier.
firstName
Johnny
Johnny
Null values are not used from the .csv imports. Contact C’s value is used.
middleName
Matthew
M
Matthew
As there is a conflict, the value from the newest curated contact is used.
lastName
Banks IV
Banks
Banks IV
Banks IV
The value from the .csv takes priority here.
title
Johnny Boy
Johnny Boy
Null values are not used from the .csv imports. Contact C’s value is used.
salutation
Mr
Mr
Null values are not used from the .csv imports. Contact B’s value is used.
Personal email from the .csv is matched with Contact C’s other Email.
Merged contact’s other email stays empty in this scenario since personal Email has already taken this email address, and duplicate phone or email values are not saved.
cell Phone
+1 919 432-5523
Work phone from .csv is matched with Contact B’s cell phone.
The merged contact’s cell phone stays empty in this scenario since work Phone has already taken this phone number value, and duplicate phone or email values are not saved.
work Phone
+1 919 432-5523
+1 919 432-5523
Work phone from .csv is matched with Contact B’s cell phone.