How to Import Leads from a CSV

Use Case

CSV import is the batch path for loading leads into a
schedule or an offer. Common use cases include bulk
loading a purchased list, re-engaging a dormant audience,
and migrating leads from an external system.

Preparing the CSV

The file must include one row per lead and one column
that holds the phone number. The phone column must be
named caller_id. This is the only phone column the
import wizard's CSV parser will recognize without manual
column mapping. The on-screen instructions on the upload
step state this explicitly:

One of the columns must be named caller_id. This
column is expected to contain the lead's callerID.

All other columns are processed as tokens and applied to
calls that come from this caller_id on the chosen
Offer or Schedule. The exceptions are email,
expires_in, and remote_ip, which map to dedicated
Lead columns rather than tokens.

Example CSV:

caller_id,email,lead_priority,country,interest,debt_amount
+19518761336,john@gmail.com,0,us,cars,2500
+16785177520,mary@gmail.com,1,au,houses,500
+19519184730,phil@gmail.com,20,uk,bikes,7500

Save the file as UTF-8.

Running the Import

1. In the sidebar open Leads -> Submit Leads. The page (/leads/import_type) shows five tiles: File Upload, Manual Test, Typeform Integration, Instapage Guide, and API Usage.
2. Click File Upload. You land on /lead_imports/new. The page is titled with an auto-generated import name like Cheryll Bogisich @ 26/04/17; you can rename it in the Import Details section below.
3. Configure Import Details:
   • Name: rename the import if desired.
   • Upload Leads To: choose either Schedule - SMS, Call, and Email leads. or Offer - Inbound calls will have lead data.
   • Select Schedule (or Select Offer): pick the specific destination.
4. Configure Scrub Import to exclude leads already touched. Scrub Scope is either Company - Exclude matching leads from your whole company. or Offer - Exclude matching leads from the import offer only. Optional checkboxes let you exclude leads where a buyer was dialed, connected, or converted, or leads that opted out. You may also exclude leads with specific previous Call Dispositions.
5. In Select A CSV File, click CSV File and choose your file.
6. Configure Lead Management Options if needed:
   • Expire Existing Leads: live schedule leads matching the lead_token and caller_id will exit their schedule, then new leads will be created.
   • Manage Schedule radios: Stop Schedule, Start Schedule, Restart Schedule, Do Nothing.
   • Apply Opt-Out / Opt-In, Apply Blocked / UnBlock, Move To Another Schedule, Add To Schedule, Copy To This Schedule, Hours Until Expiration, Max Contact Attempts.
7. Configure Default Attributes to apply when a row omits the value: Traffic Source, Buyers, Lead Priority (lower = called sooner), Sub ID.
8. Configure Additional Data, Optional Validations, and Schedule Leads? as needed.
9. Click Next Step.

The wizard advances to a column-mapping and preview
step where the importer's row processing is enqueued
for background processing. Progress and any per-row
errors are visible on the import detail page.

What Happens for Each Row

For each row the importer:

1. Normalizes the phone number from caller_id.
2. Looks up or creates a Contact for the number.
3. Creates a Lead record tied to the chosen owner (Schedule or Offer).
4. Stamps the non-reserved CSV columns onto the Lead as tokens in Redis.
5. Enrolls the Lead into the owner's first schedule action (when the owner is a Schedule).

Rows that fail validation (missing or malformed phone
number, number on the company blacklist, scrub scope
match) are logged on the import detail page for review.

Reference

The CSV upload wizard is at /lead_imports/new. Note
that the API endpoint accepts alternate phone column
names (such as phone_number, telephone, phone_1),
but the CSV importer requires the literal column name
caller_id.