Skip to main content
Leads

Import Leads from a CSV File

Upload up to 30,000 leads at once from a CSV file: download the template, match your columns, fix any errors and import.

Written By voiceaiwrapper

Last updated 26 days ago

A CSV import is the fastest way to load a list of contacts into an outbound campaign. You upload a file, tell VoiceAIWrapper which column holds what, fix any rows it flags, and the leads are added in the background. Anything extra in your file, such as company name or last purchase, can come along as custom fields your agent can use.

A typical import takes a few minutes, plus a short wait while the leads are added.

Before you start

You'll need:

  • An outbound phone campaign that hasn't ended. The Add leads menu only appears on outbound campaigns, and it's greyed out once a campaign has ended.
  • A .csv file of up to 20 MB and 30,000 rows. Spreadsheet apps (Excel, Google Sheets, Numbers) can all save as CSV. For a bigger list, split it into several files.
  • A header row. The first row must hold the column names.
  • Two columns for each phone number: the Country Code and the Phone Number, kept separate.

How to format the two phone columns

ColumnFormatExampleRejected
Country Code1 to 4 digits, without the +1, 44, 91Letters, dashes or spaces, such as 1-684
Phone Number7 to 15 digits only, without the country code4155550123Spaces, dashes or brackets, such as (415) 555-0123 or 415 555 0123

VoiceAIWrapper joins the two into the international format, so 44 and 7700900123 becomes +447700900123. A leading 0 on the phone number, as in the UK's 07700900123, is dropped automatically.

Don't put the country code in the Phone Number column as well. A number such as 14155550123 or +14155550123 passes the checks, but with a Country Code of 1 it becomes +114155550123 and the calls fail. Keep the country code only in its own column.

Step 1: Upload your file

  1. Open your Pod (an engine or provider connection) and select Campaigns in the sidebar.
  2. Open the outbound campaign, then open the Leads tab.
  3. Click Add leads, then choose Add leads via csv. The import dialog opens on Upload a CSV file.
  4. Not sure how to lay out your file? Click Download Template. You get csv-template.csv with sample rows and these columns: First Name, Last Name, Country (Optional: Can be used as custom field), Country Code, Phone Number and Email.
  5. Drag your file onto the upload area, or click it to choose a file. You can upload one file at a time.
  6. Click Next.

The panel next to the upload area shows the limits (Max file size and Max rows) and a table of each Expected Column, its Expected Type, an Example, and whether it's Required. Only Country Code and Phone Number are required.

Step 2: Map your columns to lead fields

On Map fields, each column in your file gets a row: its name, some sample values, and a Map to Field menu.

The CSV import dialog on step 2, Map fields: the CSV Column, Sample Data and Map to Field columns, with First Name, Last Name, Country Code, Phone Number and Email matched automatically and an extra column (for example company) set to Custom Field. The Next button is visible.

Columns with common names, such as first_name, phone or email, are matched for you. Every other column starts as Custom Field. For each row, choose one of:

OptionWhat happens
A lead field (First Name, Last Name, Country Code *, Phone Number *, Email)The column fills that field. * marks a required field.
Custom FieldThe column is saved on each lead as a custom field. The column name becomes the key.
Ignore FieldThe column is left out of the import.

Each lead field can be used once. When everything is mapped, click Next.

Custom field keys come straight from your column headers, and custom fields are passed to your agent with each call. Short, clean headers such as company or city are easier to use in your agent's prompt than long ones. In the template, rename Country (Optional: Can be used as custom field) to country before you import, or set it to Ignore Field.

Step 3: Review and fix errors

On Review data, you see every row as it will be imported. Cells with a problem have a red edge on the left. Hover over one to see the error.

  • Click a cell to edit its value. The row is checked again when you click away.
  • Turn on Only show rows with errors to see only the rows that need attention.
  • Select rows and click Delete Selected Rows to drop them from this import. Your file isn't changed.
The CSV import dialog on step 3, Review data, with Only show rows with errors turned on, one row whose Phone Number cell holds a 6-digit number, has a red left edge and shows the hover message 'Error: Phone number should be 7-15 digits long', the row selected, and Delete Selected Rows and Import visible.

When no errors are left, click Import. The footer shows Total Rows so you can check the count first.

Step 4: Wait for the import to finish

The leads are added in the background. You'll see a message that the leads have been queued for import and may take a few minutes. Refresh the Leads tab after a short wait to see them all.

During the import:

  • Numbers already in the campaign are skipped. A phone number can only be in a campaign once, so duplicates are left out without an error.
  • Your leads event webhook is notified. If the campaign has a leads event webhook, it receives a Leads Added event for the imported leads, not one event per lead. See Leads Event Webhook.
  • Calling can start right away. If the campaign is active and inside its calling window, the agent starts calling the new leads. Calls on a VAW Native Pod use AI credits. Calls on a BYOK Pod (Vapi, Retell AI, ElevenLabs) are billed to your own provider account.

Import into a draft or paused campaign if you want to check the list before any calls go out. Start the campaign when you're ready.

Common import errors

MessageCauseFix
Row limit exceeded: Please upload a CSV file with a maximum of 30000 rows.The file has more than 30,000 data rows.Split the file and import each part.
File … was rejectedThe file is bigger than 20 MB or isn't a .csv file.Save it as CSV, remove columns you don't need, or split it.
Please map the required fields: Country Code, Phone NumberOne or both required fields aren't mapped to a column.Map them in Map fields. If your file has one combined number column, split it into two columns first.
Each field can only be mapped once. Duplicate mapping for: …Two columns are mapped to the same lead field.Set one of them to Custom Field or Ignore Field.
Expected number, received stringA Country Code or Phone Number cell has spaces, dashes, brackets or letters.Keep digits only.
Country code should be a valid number without the + sign (e.g., 1, 44, 91)The country code is 0 or has more than 4 digits.Enter the real country code, such as 44.
Phone number should be 7-15 digits longThe number is too short or too long.Check the digits, and leave the country code out.
Phone number must be uniqueThe same number appears more than once in the file.Delete the extra rows.
Invalid emailThe Email cell isn't a valid address.Correct it or clear the cell. Email is optional.
This field is requiredA required cell is empty.Fill it in or delete the row.

If you click Import while rows still have errors, the import stops and asks you to fix or delete those rows first.

Frequently asked questions

Remove columns you don't need, or split the file into smaller files and import them one after another. Duplicate numbers across the files are skipped, so overlapping rows are safe.

Numbers that were already in the campaign are skipped. Search the Leads tab for a missing number to check. If it's not there, check the row in your file for formatting problems and add it again.

The most common cause is a wrong country code, or the country code typed into the Phone Number column as well. Leads whose calls fail with an error are marked Invalid. See Lead Statuses Explained and CSV Import Errors and Invalid Leads.

No. Add leads only appears on outbound phone campaigns. Inbound campaigns create their leads from the people who call in.