Upload using Import Template (Contact List Builder)
Overview
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.
Contact List Template Creation
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 Filter Creation
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:
- Set "sourceType": "ContactListTemplate"
- 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".
Import Template Creation
Splitting Criteria
When creating an import template, you have the option of using splitting criteria. The four splitting criteria are specified below:
Splitting Criterion | Explanation |
Quantity | The records will be added sequentially to target list(s). Each list will contain, at most, the amount of records specified by the criteria value. |
Percentage | The records will be added sequentially to target lists that will have at most the (criteria value * number of valid contacts) / 100. |
Column | The selected column (criteria value) will be used to split the records into target lists. See example below. |
Custom | The selected filters, separated by commas (criteria value), will be used to split the records into target lists. See example below. |
Remainder
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.
Waterfall Rule
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:
id | Phone Number | Color |
1 | 123-456-0000 | red |
2 | 123-456-0001 | green |
3 | 123-456-0002 | |
4 | 123-456-0003 | red |
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.
List Name Format Tokens
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).
Token | Explanation |
%N | Will be replaced by the listNamePrefix specified on upload. Mandatory. |
%P | Will be replaced by the part number. |
%F | Will be replaced by the Contact List Filter name. |
%C | Will be replaced by the column value for that record. |
YYYY | Will be replaced by the current year (e.g., 2023). |
MM | Will be replaced by the current month (e.g., 02). |
DD | Will be replaced by the current day (e.g., 10). |
hh | Will be replaced by the current hour. |
mm | Will be replaced by the current minute. |
ss | Will be replaced by the current second. |
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.
File Import
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:
Form Field | Value | Required |
importTemplateId | Id of your import template to use. | ✅ |
listNamePrefix | String that will replace %N in the listNameFormat specified on the import template. | ✅ |
file | Binary file data. | ✅ |
fileType | contactlist | ✅ |
divisionIdForTargetContactLists | Id of the division to be used for the creation of the target contact lists. If not provided, Home division will be used. | |
contact-id-name | The column name from your file to use as the contact id. |
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.