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

# Importing Leads

> Upload large contact lists from CSV or Excel files with automatic validation, background processing, and error reporting.

Import large numbers of leads at once using CSV or Excel files. The import system validates each row, processes large files in the background, and generates a detailed error report for any rows that fail.

## What the importer supports

* CSV (`.csv`) and Excel (`.xlsx`, `.xls`) files
* Background processing for large files
* Automatic validation with error reporting
* Secondary contacts included in the same file
* Variable column mapping from your assistant's configuration

## Preparing your import file

### Required columns

| Column           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `phone_number`   | Primary contact phone number (required)              |
| Variable columns | One column per variable configured on your assistant |

### Optional columns

* Additional phone number columns for secondary contacts (e.g., `secondary_phone_1`, `secondary_phone_2`)
* Secondary contact variable columns (e.g., `secondary_1_name`, `secondary_1_role`)

### File format example

```csv theme={null}
phone_number,customer_name,company,budget_range,secondary_phone_1,secondary_phone_2
+14155551234,John Smith,ABC Corp,10k-50k,+14155551235,+14155551236
+14155557890,Jane Doe,XYZ Inc,50k-100k,+14155557891,
+14155554567,Bob Johnson,Tech Start,5k-10k,,
```

## Phone number formats

<Tabs>
  <Tab title="International format (recommended)">
    Numbers include the country code with a `+` prefix.

    **Examples:** `+40741234567`, `+14155551234`

    * No country selection needed during import
    * You can mix numbers from multiple countries in the same file
  </Tab>

  <Tab title="National format">
    Numbers without a country code prefix.

    **Examples:** `0741234567`, `7775551234`

    * You must select the country code during import setup
    * The system prepends the selected code to all numbers
    * **All numbers in the file must be from the same country**

    <Warning>
      When using national format, import one file per country. Do not mix numbers from different countries in the same file.
    </Warning>
  </Tab>
</Tabs>

## Import steps

<Steps>
  <Step title="Start the import">
    1. Navigate to the **Leads** section or a campaign's leads tab.
    2. Click **Import Leads**.
    3. Select the campaign to assign the leads to.
    4. Optionally download the sample file to see the expected format.
  </Step>

  <Step title="Configure import settings">
    Before uploading your file, set these options:

    **Secondary contacts** — Select how many secondary phone numbers per lead (0–10) are included in your file.

    **Phone number format** — Choose International or National format. If National, select the country code.
  </Step>

  <Step title="Upload your file and map columns">
    1. Select your CSV or Excel file.
    2. Map your file's columns to system fields:
       * **Phone number** (required) — Select the column with primary phone numbers
       * **Assistant variables** — Map each variable to the corresponding column
       * **Secondary contacts** — If configured, map secondary phone number and variable columns
    3. The system auto-detects mappings based on common header names. Review and adjust as needed.
    4. Click **Import** to begin processing.
  </Step>

  <Step title="Monitor and review results">
    For large files, processing runs in the background. You will receive an email notification when the import completes.

    The notification includes:

    * Number of leads successfully imported
    * Count and details of any failed rows
    * A download link for the error report
  </Step>
</Steps>

## Validation rules

### Phone numbers

* International format is preferred (`+1234567890`)
* Duplicate phone numbers are detected and prevented
* Invalid or impossible numbers are flagged and skipped

### Variables

* Variables marked as required must have values
* Text, number, and boolean fields are validated for correct data type
* Maximum character limits are enforced

### Secondary contacts

* Same phone number format validation as primary numbers
* Secondary numbers must differ from the primary number
* Each secondary contact's variables are validated independently

## Error handling

The import system is designed for partial success — valid rows are always imported, and invalid rows are reported without blocking the rest.

| Outcome         | What happens                          |
| --------------- | ------------------------------------- |
| Valid row       | Lead is added to the campaign         |
| Invalid row     | Skipped and added to the error report |
| Import complete | Email notification sent with summary  |

### Downloading the error report

After import, download the error report from the notification or the import history. The report includes:

* The original row data
* A description of each validation error
* Guidance for correcting the issue

You can fix the errors in your file and re-import the corrected rows.

### Common errors

| Error                  | Cause                                    |
| ---------------------- | ---------------------------------------- |
| Invalid phone number   | Incorrect format or an impossible number |
| Missing required field | A required variable column is empty      |
| Duplicate phone number | This number already exists in the system |
| File format issue      | Corrupted file or unsupported format     |

## Secondary contacts in your file

### Multiple phone numbers per lead

Add secondary contact phone number columns after your primary number and variables:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_phone_2,secondary_phone_3
+14155551234,John Smith,+14155551235,+14155551236,+14155551237
```

### Secondary contact variables

Add variable columns alongside secondary phone numbers:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_1_name,secondary_1_role
+14155551234,John Smith,+14155551235,Jane Smith,Decision Maker
```

Contacts are called in column order — `secondary_phone_1` is tried before `secondary_phone_2`, and so on.

## Processing times for large files

| File size      | Typical processing time |
| -------------- | ----------------------- |
| \< 100 rows    | Under 1 minute          |
| 100–1,000 rows | 2–5 minutes             |
| 1,000+ rows    | 10–30 minutes           |
| 10,000+ rows   | May take several hours  |

Large files are queued automatically and processed in the background without affecting platform performance.

## Best practices

* **Download the sample file** — Use the provided template to ensure your file matches the expected format before importing.
* **Test with a small batch** — Start with 5–10 rows to confirm column mappings and variable values are correct before importing your full list.
* **Use international format** — Phone numbers in `+country_code_number` format (no spaces or separators) avoid the most common import errors.
* **Clean your data** — Remove empty rows, fix encoding issues, and validate phone numbers before uploading.
* **Match your assistant's variables** — Make sure your column headers align with the variable names configured on the campaign's assistant.

## Next steps

* [Manage individual leads](/leads/managing-leads) — edit, update status, and organise imported leads
* [Review lead statuses](/leads/index) to understand how imported leads move through the campaign lifecycle