Contact List Formats, Fields, and Tables

From Genesys Documentation
Jump to: navigation, search
  • Scenario 1: The UK number +44 (0)020 7551 8700 is in the contact list as +44 20 7551 8700.
  • Result: This number can be called from any account because the country code is included.
  • Scenario 2: The UK number is in the contact list as 20 7551 8700.
  • Result: This number can only be dialed from an account whose number begins with +44 (i.e. a UK account).
  • Scenario 1: The UK number +44 (0)020 7551 8700 is in the contact list as +44 20 7551 8700.
  • Result: This number can be called from any account because the country code is included.
  • Scenario 2: The UK number is in the contact list as 20 7551 8700.
  • Result: This number can only be dialed from an account whose number begins with +44 (i.e. a UK account).
This topic is part of the manual Outbound (CX Contact) CX Contact Help for version Current of Outbound (CX Contact).

Learn the basics about contact lists.

Contact lists are used to store and organize contact information. Once you import a contact list into CX Contact, you can use it for one or multiple campaign groups.

On the Import, Export, and Manage Contact Lists page, you will learn how to work with contact lists, but first it's important to understand the basics:

Supported File Formats

CX Contact supports the following file formats for contact lists and suppression lists:


The easiest text file format for importing contact information is comma separated value (CSV). In a CSV file, each record is on its own row, and each field within a record is delimited, or separated, with commas.

Important: We recommend you use a header record, the first row of the list, which names and describes the data fields. The header row is used to govern the mapping between the fields in the data file and the fields in the contact list.


You can import a contact list in a text file format, including any of the following:

  • Pipe-delimited files
  • Colon-delimited files
  • Tab-delimited files
  • Semicolon-delimited files
  • Fixed position files, containing values in specified columns (such as a 10-digit phone number starting from character offset 105 through to 114).
XLS Microsoft Excel files are supported.
XLSX Microsoft Excel Open XML Format Spreadsheet files are supported.
To avoid problems with mapping, we recommend you use an input specification file or the data mapping feature when importing your files.

View a Contact list

When you go to the Lists menu and select the Lists page, you'll see a list of all available contact lists and their associated details, as follows:

Contact List Details Description
Name The name of the list.
Description A description of the list.
Caller ID The caller's phone number.
Label Indicates the purpose of the list.
Size The number of records in the list.
Secured Indicates if the Contact list was PGP encoded before it was imported/exported.
Retention Indicates the amount of time for which the entries in the contact list should be maintained. A retention period is mandatory. If a retention period is not selected, Permanent is selected by default.
Last Modified Date The date and time the list was last changed.
Created Date The date and time the list was created.

If you want to view the details of an individual contact list, click the box next to its name and select the Edit List icon from the Actions menu.

Contact List Fields

A contact list can contain any or all of the fields described in this section. While the Device field (at least one) is the only mandatory field, Genesys recommends you also include a Client ID field. Otherwise, that field will be auto-filled with the Device information (phone number, for example).

Contact List Import

When you import a list into CX Contact, it can contain any or all of the fields listed in the table below.

  • When working in the List Details View, the DB field name of every Contact List field is located under its respective column header. When working with SQL use the DB field name to query the correct DB fields. For example, in the following image you can see that contact list field for Client ID is c_client_id.
  • To hide a column from the List Details View, right click the column heading and select Hide from the menu that appears. Click Unhide to unhide all of the hidden columns.

New database field name.png

Type of Information Description
  • FirstName— 64 characters maximum
  • LastName—64 characters maximum
  • Company—64 characters maximum
  • Client Identifier—64 characters maximum.
  • Time Zone - Java formatted time zone (for example, Europe/London)
  • Postal Code - 32 characters maximum
  • Country Code - 3 characters
  • State/Region - 2 characters
  • Original Record - Reserved for future use
If the data in any of your Other or General fields contains commas, those fields must be enclosed in double quotation marks.
Other (User-defined Fields) Other1 to OtherN are user-defined fields, meaning you use them to specify free-form information about the contact. The character limit for these fields is 1,024.

By default, these fields are labelled as Other1, Other2, Other3, and so on, but you can override the default labels to clearly identify what the field is used for. Refer to the Create or Manage Field Labels page for more information.

Device Device1 - Device10 fields are used to store the contact's phone number. Phone numbers can be entered using the following format:
  • International (the phone number being dialed is outside the country of the account) - + followed by the country code, followed by the area code and phone number
  • National (the phone number being dialed is within the same country as the account) - the area code and phone number.

However, it's safe to use the country code in all circumstances. Click to see examples.

When a file is imported, all phone numbers, regardless of format, are normalized to E.164 standards (i.e. + followed by country code).

Contact List Export

When you export a contact list from CX Contact, the list can contain any of the fields listed in the table above, in addition to the fields listed in the table below.

Field Name Type
Agent ID String
Application DBID Integer
Number of Attempts Integer
ISO country Code (Contact) String
Original Record String
Postal Code String
State/Region Code String
Time Zone DBID (Contact) Integer
Time Zone Name (Contact) String
Call Result Enum
Disposition Code String
Call Time Integer, UNIX Epoch
Campaign DBID Integer
Area Code Integer
Country Code (Device) String
ISO Country Code (Device) String
Device Index Integer
Device Type Integer
Device Exchange Integer
Device Extension Integer
Device Mask Decimal integer
Device Number Integer
State/Region Code (Device) String
Timezone DBID (Device) Integer
Time Zone Name (Device) String
Chain ID Integer
Number in Chain Integer
Contact Info (Device) String
Contact Info Type Enum
Contact From Integer
Contact Till Integer
Scheduled Time Integer, UNIX Epoch
Group DBID Integer
Record ID Integer
Record Status Enum
Record Type Enum
Switch DBID Integer
Treatment History String
Time Zone DBID Integer

Contact List Database Tables

When contact list data is imported into CX Contact, the data is stored in a database table. In CX Contact, there are two distinct database tables: the main table and the secondary table. There are distinct differences between the two:

  • Stores all General, Device, and Other1-Other20 data
  • Contains one record for each device within a chain
  • All fields in this table can be modified
Use these fields for any data that will be part of a dialing filter or contact order, or for data that will be edited by an agent.
  • Stores all Other21-OtherN data
  • Each record is tied to a Chain ID in the main table. Records are not separated by devices.
  • All user-defined (Other21-OtherN) data is presented within the same row as all other data.
  • There is one record for each user-defined (Other) field. For example, if for one particular Chain ID, there are three user-defined fields containing user data (for example Other21, Other22, Other23), there will be three separate records for this one Chain ID.
  • User-defined data (Other 21 and onward) cannot be modified. Important: Genesys recommends you use fields Other1-Other20 (the main table) for data that might need to be modified later.

There is a significant difference between user fields Other1-Other20 and user fields Other21+.

  • Other1-Other20 are stored in the main calling list table, they are defined per-device and can be modified by agent desktop requests to OCS.
  • Other21+ are stored in separate table, they are defined per-contact and they cannot be modified.
It is recommended that you use Other1-Other20 fields first and only use Other21+ fields when all Other1-Other20 fields are being used.

It's possible that the contact data you import into CX Contact is stored into two separate database tables.


Customer Information:

  • John Smith
  • Two devices (primary and secondary)
  • One chain: The chain_id is 1

User-defined fields used:

  • Other 5: Device information (primary vs. secondary)
  • Other 20: A promise to pay, answered by spouse
  • Other 21: The amount John promised to pay ($500.44)
  • Other 22: The payment date (05-10-2018)


In this scenario, two tables are used in the database: the main table and the secondary table.

The main table contains two records for John Smith - one for each device. It includes all customer data, including the data contained in the Other5 and Other20 fields.

CXC ContactList main.png

The secondary table contains the user data contained in Other21 and Other22 fields:

CXC ContactList secondary.png

In this table, you will still see two separate records for John Smith, but this time the records are not tied to a device; instead, they are tied to a Chain ID. In this example, the value of ud_chain_id is 1, which, as you can see in the main contact list table, is associated with customer John Smith. Also note that the labels in the header row always contain the prefix ud. The remaining part of the labels match to those in the main table.

You'll also notice that the Other21 and Other22 fields (the amount John Smith promised to pay and the date on which he promised to pay it) are not standard column headings in this table; instead, they're presented as user data within a record. This table is designed that way to support filtering functionality within CX Contact, meaning that CX Contact can easily join the two tables together when it receives a request to filter data (in the case of selection rules) within the contact list.

Refer to the Import a Specification File page to see how a database table is created from a specification file.

Related Topics

Comments or questions about this documentation? Contact us for support!