# 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.

URL: https://trustane.com/blog/vicidial-add-lead-api
By Trustane. Published 2026-11-05.

> **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](https://trustane.com/media/9c1f3864cd525574-1600x507.webp "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.

| 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 |

> **The silent list 999**
> Forget `list_id`, or send under three characters, and the lead goes into list 999. Nothing errors. Your loader reports success and the leads sit where no campaign dials. With `list_exists_check=Y`, an undefined list returns `ERROR: add_lead NOT A DEFINED LIST ID`.

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](https://trustane.com/media/2f852136e44bdb40-1600x272.webp "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](https://trustane.com/media/e781fb179955e3ce-1600x662.webp "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](https://trustane.com/blog/vicidial-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](https://trustane.com/guides/why-vicidial-is-not-dialing-hopper). Need a server sized for it? See [VICIdial hosting](https://trustane.com/vicidial-hosting), or [ask about a migration](https://trustane.com/migrate).

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.
