Overview

The CSV upload feature lets you create lists by uploading a CSV file. Unlike dynamic lists, these lists can be used in communication journeys within 10 minutes. With bulk upload capabilities, this feature eliminates the need to manually create records individually, saving you time and effort.

We support Candidate Lead and Contact Lead entities for CSV upload.

Prerequisites

You will need to select a unique key before creating your first CSV list for a specific person type.

This setup needs to be done for each focus entity separately: candidate lead and contact lead.

To set the unique key for the first time, navigate to Configuration > Variables. Here, you will see options for candidate lead and contact lead.
You can choose from three supported unique key options: email, phone number, or both email and phone number.
It is crucial to understand the implications of your unique key selection. For example, if you select only the phone number as the unique key, any records in your CSV with the same phone number will be considered duplicates, even if their email addresses are different. Similarly, selecting only email as the unique key will lead to records with the same email being treated as duplicates, regardless of their phone numbers. If you choose both email and phone number, a record will only be considered a duplicate if both the email address and phone number match an existing record.
The system will prompt you to select the unique key upon first using the CSV list feature for each focus entity. Once set, the unique key will be saved for that entity.

CSV Lists Dashboard

This dashboard helps you efficiently manage all your imported CSV lists. It includes filters, search capabilities, status indicators, and bulk actions for better organization and control.

Tab Switcher: Dynamic Lists / CSV Lists

You can use this toggle to switch between:

Dynamic Lists: Lists generated based on saved filters or conditions.
CSV Lists: Lists imported manually via CSV files.

The active tab, which is CSV Lists, is highlighted in purple.

Search Bar

You can search for any list by name. This is a quick way to locate specific lists, especially when you manage many of them.

Entities Filter

The Entities dropdown will filter lists based on the focus entity (e.g., Candidate lead). This allows you to view only those lists relevant to a specific entity type.

Status Filter

Filter lists by their status. Common statuses include:

In Use: Lists that are active and in use.
Ready to use: Lists are active and usable.
Building:
Archived: Lists are stored but not in use.
Failed: Lists that have failed to upload.

History button

Clicking the History button displays your past CSV uploads. This will open the CSV Upload History page.

List Table Overview

This is the main data view where all CSV lists are displayed with the following columns:

List Name: The name of your list (clickable, leading to list details).
Count: Number of records in the list.
Focus Entity: The type of data the list targets (e.g., Candidate lead).
Mapped Resources: Number of resources successfully mapped to the platform's schema.
Status: Current list status (e.g., Ready to use).
Created by: Email of the user who uploaded the list.
Last Updated: Shows when the list was last modified (sortable).

Bulk Actions

When you select multiple lists using the checkboxes on the left:

A bulk action bar appears at the bottom.
You can choose to Archive or Delete selected lists.
Use the Close button to cancel the bulk selection mode.

⋮ Three Dots Menu

For each list, click the vertical three-dot icon to open the context menu:

View Details: See list details, mappings, and history.
Archive: Store the list without deleting it.
Delete List: Permanently remove the list (confirm before deletion).

Creating a CSV List

To create a new CSV list, follow these steps:

Navigate to Lists > CSV List > +CSV List.
Provide a unique List Name.
Select the Focus Entity for your list, either candidate lead or contact lead. The system will inform you of the unique key that has been set up for the selected entity.

Uploading a CSV File

You can export a sample CSV template, which will provide the expected columns for the selected focus entity.

Sample template:

Populate this template with your data, ensuring that all required fields, especially the unique key fields, are filled.

Note:

Rows without a unique key will not be uploaded. If your CSV includes email ID, phone number, or date fields, ensure they are correctly formatted, as invalid data will not be uploaded.
The column that is generated can be customized in the next step.

Click Next.

Mapping Fields

After uploading your CSV file, you will be presented with a screen where you can map the columns from your CSV file to the corresponding entity fields in the system. On one side of the screen, you will see the entity fields, and on the other side, you will see the column names from your uploaded CSV file.
Select the appropriate CSV column for each entity field so that the data in the column can be saved as a record for the entity field.
You have the option to not import certain fields by selecting a "don't import" option.
You can also delete certain fields using the trash icon.
You can also add new fields during this mapping process.

Mapped Fields Validation

Once you have mapped the fields, click Validate to validate your upload. The system will check the records in your CSV file for correctness, particularly regarding the unique key.

The validation process will identify correct and incorrect records.

You can download a report detailing the incorrect records and the reasons why they were flagged (e.g., invalid unique key found).

Submission and Processing

After validation, click Submit. The system will process only the valid records from your CSV file and discard invalid records.

The processing time may vary; it might take some time (10 minutes approx) for the list to be ready for use. If you upload multiple CSV files, then it will be queued to be processed one at a time.

While the list is processing, details appear as shown below:

History Button

You can view your past CSV uploads by clicking the History button. This will open the CSV Upload History page.

Each list has the following information:

View List: Redirects to a detailed view of the list, from where you can edit list details (list name).
List Name: Indicates the name associated with the CSV upload.
Status Tag: Indicates the final status of the upload.
- Success
- Failed
- Queued
- Processing
Description: Indicates the outcome of the upload process.
Timestamp: Shows how long ago the upload occurred
Admin Info: Shows the email address of the admin who performed the upload.

Filters

The View All drop-down helps you filter uploaded records based on their current status.

View All: Displays all uploads regardless of status.
Queued: Shows uploads that are waiting to be processed.
Processing: Displays uploads that are currently being processed.
Success: Lists uploads that were successfully completed.
Failed: Lists uploads that failed due to errors.

Download Errors and Duplicate Records

If the uploaded CSV list has errors and/or duplicates, you will get an option to download the report.

Sample error report exported file:

Using Lists in Workflows

You’ll also be able to use your uploaded CSV lists within Workflows. Here’s how you’ll eventually integrate your created lists into workflows:

Creating a New Workflow

When creating a new workflow, you must select a focus entity. This focus entity should align with the type of list you intend to use. The available options for the focus entity are candidate lead or contact lead. You can refer to this guide on how to create a workflow.

You should choose the focus entity that matches the type of records (candidate or contact) in your CSV list.

Reusing an Existing List in a Workflow

Within the workflow configuration, there is an option to reuse an existing list.

Upon choosing to reuse an existing list, you will be presented with a list of your created lists.

In the given example, a CSV list—Sample, uploaded previously, is being selected in the Workflow.

Once the integration is complete, the workflow will function normally. You can link these lists to other nodes (email, etc) of workflow documentation.

Below is an example of how a CSV list can be used in the Email node in Workflows:

Untitled design (1).gif

Helpful resources:

For more details on how to create a list, you can refer to this guide