Upload using Import Template (Contact List Builder)

After creating a contact list template using the POST /api/v2/outbound/contactlisttemplates resource and an import template using the POST /api/v2/outbound/importtemplates resource, records can be uploaded by importing files.

For this type of import, the configuration of the target list(s) (e.g., column names, attempt control etc.) is done during the creation of a contact list template, which is then used to create an import template.

Contact List Filters used in Import Template either as main filter or for custom splitting need to be of source type "ContactListTemplate". Filters specified for Campaigns are of source type "ContactList" and cannot be used in this scenario.

When creating a Contact List Filter using the POST /api/v2/outbound/contactlistfilters resource, to specify a Contact List Template as the source for the filter, it is necessary to:

1. Set "sourceType": "ContactListTemplate"
2. Pass the Contact List Template's id in "contactListTemplate": {"id": "contact-list-template-id"}

The filters created based on a Contact List Template can then be used in the Import Templates creation as either a main filter, i.e., the "contactListFilter" field, or for Custom splitting, i.e., the "criteriaValue" field, when "criteria" is set to "Custom".

When creating an import template, you have the option of using splitting criteria. The four splitting criteria are specified below:

If createRemainderContactList is true, records that do not match the splitting criteria will be added to a remainder list.

• For Quantity and Percentage splitting criteria, if the last target list does not have enough records to satisfy the splitting condition, then this last target list is the remainder list, e.g., if the criteria value is 20000, and the list being split has 30000 records, the last 10000 records will be added to the remainder list, which is only created if createRemainderContactList is true.
• For Column splitting criterion, records that have blank values for the selected column are added to the remainder list.
• For Custom splitting criterion, records that do not match any filters are added to the remainder list.

There is a scenario unique to the Custom splitting criterion: records can match multiple filters. In this case, the Waterfall Rule decides how they are handled. When useWaterfallRule is true, records will only be added to the target list of the first matching filter. When it is false, contacts will be added to the target lists of all matching filters. All other splitting criteria ignore this parameter.

Examples

Records:

Column:

If the Color is specified as the criteriaValue, records with id 1 and 4 will be added to one target list, record with id 2 to another, and record with id 3 will only be added to the remainder list if createRemainderContactList is true.

Custom:

If you have one filter to match (color IS red) with id "random-uuid-1" and one filter to match (color IS green OR color IS red) with id "random-uuid-2", and you specify the criteriaValue as "random-uuid-2,random-uuid-1" (note that 2 is coming before 1):

• If useWaterfallRule is false, records with id 1 and 4 will be added to both target lists, while record with id 2 will only be added to the target list corresponding to "random-uuid-2".
• If useWaterfallRule is true, records with id 1, 2 and 4 will only be added to the target list corresponding to "random-uuid-2", while the target list corresponding to "random-uuid-1" will be empty.
• If createRemainderContactList is true, record with id 3 will be added to the remainder list, as it doesn't match any of the filters.

When creating the import template, you have the option of specifying listNameFormat as Custom and passing in a customListNameFormatValue. The table below illustrates the available tokens. Any parts of the string that do not match any tokens, as well as tokens that are not applicable (such as %F when using Quantity splitting), will be left as is when creating target lists (please refer to examples below).

When using splitting criteria, the following rules apply:

• For Quantity and Percentage, %P is mandatory.
• For Custom, either %P or %F is mandatory.
• For Column, either %P or %C is mandatory.

Examples

Assume that the listNamePrefix provided on upload for the following examples is "Genesys".

• %N_YYYYMMDD_%C when using splitting criterion = Column will generate target list names such as: Genesys_20230210_red and Genesys_20230210_green (note that the character "_" is left as is).
• %N_YYYYMMDD_%P_%F when using splitting criterion = Column will generate target list names such as: Genesys_20230210_1_%F and Genesys_20230210_2_%F (note that %F is left as is).

Note: be wary of the limit of 64 characters when using custom list names. A list name format such as "%N_YYYYMMDDhhmmss_%F" can easily exceed this limit if a large enough list name prefix is passed in and/or the filters selected have long names.

Importing a file is done by making a POST request to url https://apps.mypurecloud.com/uploads/v2/contactlist. The domain name of the url should be the same as the one you use when using the Genesys Cloud app (Genesys Cloud Platform API.

The request headers should include the Authorization header with the same bearer token that you would use to make other API requests. The body of the POST should be a form encoded value with the following details:

Note: If id is provided along with importTemplateId, the latter is ignored (along with listNamePrefix and divisionIdForTargetContactLists) and the import is treated as a normal contact list upload.