Operations

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.

By Published 5 min read
Focused business analysis with charts and graphs on a laptop in a modern office setting.

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_id defaults to list 999 with no error. Send list_exists_check=Y every time.
  • Pick a duplicate_check scope on purpose: DUPLIST, DUPCAMP or DUPSYS.
  • Parse the first line of the reply: SUCCESS, ERROR or NOTICE.
Three numbers from the 1,000-row test: 1,000 rows, 5.0 seconds, 209 rows a second
One run, one server, over loopback: an order of magnitude, not a promise

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.

FieldRuleDefault if omitted
phone_numberdigits only, 6 to 16none, refused
phone_code1 to 4 digits1
list_id3 to 12 digits999
sourceup to 20 charactersnone, 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

VICIdial list page with Campaign and Active marked
A list belongs to a campaign and only dials when Active is Y
  1. Campaign (campaign_id): the campaign that will dial this list.
  2. Active (active): leave it N until the load is checked.

In the Trustane console

Trustane console Lists tab with Dialable, Load leads and Attach a list marked
Lists tab: counts to check against what you sent
  1. Dialable: the count of leads the dialer can call. Compare it with what loaded.
  2. Load leads: add a file to the list.
  3. 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 (needs campaign_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=Y rejects unreal North American area codes and needs 10 digits.
  • usacan_prefix_check=Y rejects an exchange digit below 2.
  • lookup_state=Y fills state from the area code.
  • tz_method empty uses country plus area code; POSTAL uses the postal code. A wrong zone means calls at the wrong hour, which the account holder owns.
  • dnc_check=Y and campaign_dnc_check=Y check 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

  1. VICIdial Non-Agent API documentation (add_lead, update_lead, add_list)
  2. Lead loading research, add_lead contract read from the source
  3. Lead upload test runs, 1,000-row file
  4. Cover photo by RDNE Stock project on Pexels

Trustane

Managed VICIdial hosting

Run it on cores of your own

Managed VICIdial, billed by the hour against a balance you top up.

Or try one server free for 7 days, no top-up.