CSV Import

Import contacts in bulk from a CSV file using a 3-step wizard. Navigate to Contacts and click the Import button.

Limits

• Maximum rows: 10,000 per file
• Maximum file size: 50 MB
• File format: .csv files only

Step 1: Upload

Configure the import settings and select your CSV file.

Import Purpose

Deduplication Settings

• Identifier — The field used to match existing contacts: email, phone, or contactId
• Lookup Scope — Where to search for matches:
  • Within Playbook — Only match contacts in the same playbook
  • Across All Playbooks — Match contacts across your entire organization

Fallback Playbook

If a row's playbook ID is missing or invalid, the contact is assigned to the Contact Pool by default. You can change this to any active playbook.

After configuring settings, drag and drop your CSV file or click to browse. The file is uploaded directly to secure storage via a presigned URL.

Step 2: Mapping

Map CSV columns to VayaFlow fields. The wizard auto-suggests mappings based on common header names (e.g., "First Name" maps to firstName, "Email Address" maps to email).

Required Fields

These fields must be mapped before proceeding:

• playbook.playbookId — The playbook to assign the contact to
• firstName
• lastName
• email
• phone

Column Mapping

For each CSV column, select the corresponding VayaFlow field from the dropdown. Fields are organized by the field library and include:

• Contact fields (name, email, phone, address)
• Questionnaire fields (questionnaire.<key>)
• Attribution fields
• Custom fields

Do Not Overwrite

When updating existing contacts, you can protect specific fields from being overwritten. Check Do Not Overwrite for any field that should keep its current value if the contact already exists.

Batch Tag

Each import is tagged with an auto-generated batch identifier (format: imported_YYYYMMDD_HHMMSS). This lets you filter and identify imported contacts later.

Step 3: Review

Review the import configuration before submitting:

• Total rows to be processed
• Estimates — Predicted counts for new, updated, and skipped contacts
• Warnings — Any validation issues detected (missing required fields, invalid data)

Click Start Import to queue the import job. The import runs asynchronously in the background — you can navigate away and check progress later.

After Import

Imported contacts are created with:

• Status set to new
• The wasImported flag set to true
• The importedAt timestamp recorded
• The batch tag stored for filtering

Imported contacts are not automatically submitted to the qualification engine. To process them, you can manually deliver individual contacts or use bulk actions.