Loading leads into VICIdial with add_lead: fields and speed
The add_lead API call in practice. Required fields, the duplicate_check values, the replies to parse, and the speed we measured loading 1,000 rows.

To the point
add_lead is VICIdial's own API call for putting one lead into one list. In our runs it loaded a 1,000-row file in 5.0 seconds, about 209 rows a second, with four loops at once on the dialer itself.
- Four required fields:
phone_number,phone_code,list_id,source. - A missing
list_iddefaults to list 999 with no error. Sendlist_exists_check=Yevery time. - Pick a
duplicate_checkscope on purpose:DUPLIST,DUPCAMPorDUPSYS. - Parse the first line of the reply:
SUCCESS,ERRORorNOTICE.

The file was synthetic: 970 unique numbers, 10 repeats, 5 numbers too short, 5 with a non-existent area code and 10 blanks.
One call, one lead
There is no batch form of add_lead. The stock web loader and the command-line loader move many rows per request. We use add_lead because it returns a reason for every row.
https://YOUR-SERVER/vicidial/non_agent_api.php?source=myload&user=APIUSER&pass=APIPASS&function=add_lead&list_id=1001&list_exists_check=Y&phone_code=1&phone_number=8135550100
Send it as a POST and URL-encode every value. A password in a query string lands in the web server's access log.
| Field | Rule | Default if omitted |
|---|---|---|
phone_number | digits only, 6 to 16 | none, refused |
phone_code | 1 to 4 digits | 1 |
list_id | 3 to 12 digits | 999 |
source | up to 20 characters | none, refused |
Optional field limits: vendor_lead_code 20, source_id 50, first_name and last_name 30, address1 to address3 100, city 50, state 2, postal_code 10, alt_phone 12, email 70, comments 255, owner 20. gender is U, M or F; date_of_birth is YYYY-MM-DD.
The documentation asks you to avoid ', " and & in values. We turn & into "and" and a pipe into a slash, since replies are pipe-delimited. A&B "Corp" was stored as A and B Corp. There is no status parameter: every lead arrives as NEW. For dispositioned leads use update_lead, which can upsert with insert_if_not_found=Y.
Set it up, step by step
Create the list first with add_list, leaving active at its default N, and switch it on when the load finishes. The pictures use our test server and its demo list 4001, Sunline Solar October.
In VICIdial's admin

- Campaign (
campaign_id): the campaign that will dial this list. - Active (
active): leave itNuntil the load is checked.
In the Trustane console

- Dialable: the count of leads the dialer can call. Compare it with what loaded.
- Load leads: add a file to the list.
- Attach a list: connect an existing list to the campaign.
The permission gate
The API user fails until all of these hold: API access enabled, user level above 7, Modify Leads set, user active, and add_lead in its allowed functions (or ALL_FUNCTIONS). Make a dedicated loader user with exactly that.
Ten bad passwords lock an API user for 15 minutes. Call function=version once before any loop and stop on the first authentication ERROR.
Duplicates: choose the scope on purpose
DUPLIST: the number exists in this list.DUPCAMP: it exists in any list of the campaign (needscampaign_id).DUPSYS: it exists anywhere on the system.
Add a window with a suffix, for example DUPSYS90DAY; documented windows run from 1DAY to 360DAY. Options can be combined with a hyphen, as in DUPLIST-DUPTITLEALTPHONELIST. The reply gives the match:
ERROR: add_lead DUPLICATE PHONE NUMBER IN LIST - 8135550100|1001|2752920
Parallel loops race: two can both hear "not found" for the same number, because the check is a read then a write, not a lock. Remove repeats from the file first (first copy wins) and split rows between loops by the last two digits of the phone. That caught 10 repeats in our file. A second run of the same file with DUPLIST loaded 0 and flagged 980 duplicates.
Reading the reply
Parse the first line with ^(SUCCESS|ERROR|NOTICE): (\w+) (.*?) - (.*)$, then split the rest on the pipe.
SUCCESS: add_lead LEAD HAS BEEN ADDED - 8135550100|APIUSER|1001|2752921|-5.00
That is phone, user, list, new lead ID and the time zone offset. A NOTICE: after it may say the lead was not added to the hopper because it is outside local call time. That is normal. Anything unclassified, including an empty reply, is a transport problem: retry once, then reject the row with the raw reply.
Checks worth switching on
usacan_areacode_check=Yrejects unreal North American area codes and needs 10 digits.usacan_prefix_check=Yrejects an exchange digit below 2.lookup_state=Yfillsstatefrom the area code.tz_methodempty uses country plus area code;POSTALuses the postal code. A wrong zone means calls at the wrong hour, which the account holder owns.dnc_check=Yandcampaign_dnc_check=Ycheck the internal and campaign lists (DNC lists).
What we did not test
Custom fields, which need custom_fields=Y; the test server had them off. Files over a few thousand rows: 100,000 rows at 200 a second is about eight minutes, and it competes with agents for write locks, so we held it to four loops.
Questions people ask
Can I send leads in a batch?
Not through add_lead. Use the web or command-line loader for bulk files.
Why did my leads vanish?
Check for list 999, and for a list that was never created.
Next steps
Load 200 rows, open the list and look at five leads before the rest. If loaded leads still do not dial, read why VICIdial is not dialing. Need a server sized for it? See VICIdial hosting, or ask about a migration.
VICIdial is a trademark of its owner. Trustane is an independent hosting provider.
Sources
- VICIdial Non-Agent API documentation (add_lead, update_lead, add_list)
- Lead loading research, add_lead contract read from the source
- Lead upload test runs, 1,000-row file
- Cover photo by RDNE Stock project on Pexels
Managed VICIdial hosting


