> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vozagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing Contacts from CSV

> Step-by-step guide to importing contacts from a CSV file into VozAgent, including column mapping, validation, and duplicate handling.

If you have a list of contacts in a spreadsheet or CRM export, you can import them all at once using a CSV file. VozAgent walks you through a guided process: upload, map columns, preview, and import.

## Before You Start

* Your file must be a **.csv** or **.txt** file.
* Each contact needs at least a **name** and a **phone number**.
* Phone numbers should include a country code (e.g., +1 for US numbers) for best results.

## Step 1: Upload Your File

1. Go to **Contacts** and click **Add Contact**.
2. Select the **Import from CSV** tab.
3. Either drag and drop your file onto the upload area, or click **Select File** to browse your computer.
4. VozAgent parses the file and tells you how many rows were detected.

**Need a template?** Click the **Download Template** button to get a pre-formatted CSV file with example data. The template includes these columns:

| Column         | Required |
| -------------- | -------- |
| `first_name`   | Yes      |
| `last_name`    | No       |
| `phone_number` | Yes      |
| `email`        | No       |
| `company`      | No       |
| `job_title`    | No       |
| `tags`         | No       |
| `notes`        | No       |

## Step 2: Map Your Columns

After uploading, you will see the **Match fields** screen. This is where you tell VozAgent what each column in your CSV represents.

* VozAgent auto-detects common column names (like "Name", "Phone", "Email") and maps them automatically.
* For each column, a preview of the first three rows is shown so you can verify the data.
* Use the dropdown to assign each CSV column to a VozAgent field, or choose **Skip this column** to ignore it.

### Available Field Mappings

Fields are organized into groups:

**Required Fields:**

* Phone Number
* Name (first name)

**Contact Information:**

* Last name
* Email
* Company
* Job Title

**Additional Information:**

* Tags
* Notes
* Preferred Contact Time
* Time Zone
* Status

A green confirmation message appears when both required fields (Name and Phone Number) are mapped. You cannot proceed without these.

Click **Continue to Preview** when your mappings look right.

## Step 3: Preview and Validate

The preview screen shows you exactly what will be imported:

* **Valid contacts** -- Contacts that passed validation and are ready to import.
* **Duplicates** -- Contacts whose phone numbers already exist in your account. These will be skipped automatically.
* **Errors** -- Rows that failed validation, with the specific error for each (e.g., "Invalid phone number format", "First name is required").

### Validation Rules

VozAgent checks each row for:

* **First name** is present
* **Phone number** is present and in a valid format
* **Email** (if provided) is in a valid format

Rows that fail validation are listed with the row number and error. These rows are excluded from the import but do not block the rest.

### Duplicate Handling

Duplicate detection is handled server-side by phone number. If a phone number already exists in your contacts, that row is automatically skipped during import. The final result shows how many were skipped.

## Step 4: Import

1. Review the preview and click **Import \[N] Contacts**.
2. A progress bar shows the import status.
3. When complete, you will see a summary: how many contacts were imported, how many duplicates were skipped, and how many failed.

Your contacts list refreshes automatically after the import finishes.

## Tips for a Smooth Import

* **Clean your data first.** Remove blank rows and fix obvious phone number formatting issues in your spreadsheet before exporting to CSV.
* **Use the template.** If you are building a contact list from scratch, start with the downloadable template to get the column names right.
* **Tags with commas.** If a contact has multiple tags, wrap them in quotes in your CSV (e.g., `"vip,customer"`).
* **Large imports.** VozAgent handles large files -- the upload and processing happen efficiently regardless of file size.
* **Start over anytime.** If something does not look right at the mapping or preview step, click **Start Over** or **Cancel** to go back to the upload step.