How to push a lead into VICIdial with the add_lead API

You have a phone number sitting in another system, and you want VICIdial to start calling it without anyone retyping it by hand. That is exactly what the add_lead function is for. It is part of the Non-Agent API, the set of HTTP calls that handle everything not tied to the live agent screen (Application Programming Interface) Non-agent API.

A lead is one record in your calling data: a phone number plus the name, address, and notes attached to it Lead. When you call add_lead, VICIdial inserts a new row into the vicidial_list table and tells you the new lead ID it assigned.

The fields you actually need

Four things are required. The first is phone_number (6 to 16 digits, numbers only). The second is phone_code, the country dialing code, which defaults to 1 if you leave it out. The third is list_id, which decides which list the lead lands in. A lead list is the named bucket of records a campaign dials through Lead list. It defaults to 999. The fourth is source, a short label (up to 20 characters) describing what made the call, so you can trace it later.

Everything else is optional. You can pass a first name, last name, address, email, and a vendor_lead_code, your own outside identifier for the record so you can match it back to the source system later Vendor lead code. The bare-minimum call below only needs a phone number.

curl "https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&first_name=Bob&last_name=Wilson"

A working call returns a success line that hands back the phone number, your API user, the list ID, the new lead ID, and the time-zone offset:

SUCCESS: add_lead LEAD HAS BEEN ADDED - 7275551111|6666|999|193715|-4

From request to dialable lead

sequenceDiagram
  participant App as Your App
  participant API as non_agent_api.php
  participant DB as vicidial_list
  App->>API: add_lead phone_number list_id
  API->>API: check API user permission
  API->>DB: INSERT new lead row
  DB-->>API: new lead_id
  API-->>App: SUCCESS lead has been added

Adding the lead does not make VICIdial dial it. The campaign, the named outbound job that ties agents to a list, still pulls leads on its own schedule Campaign. If you want this lead dialed sooner, pass add_to_hopper=Y to drop it straight into the hopper, the short queue of leads waiting to be dialed next Hopper.

A few optional settings earn their keep right away. dnc_check=Y screens the number against your Do Not Call list, the record of numbers you are not allowed to dial, before the lead goes in DNC (do not call). campaign_dnc_check=Y does the same against the campaign's own suppression list and needs a campaign_id to know which one to check. And list_exists_check=Y makes the call refuse to insert into a list ID that has not been defined yet, which catches typos before they create orphan records.

One more thing about formatting: any value that contains a space needs a plus sign in its place. To send an address you would write &address1=1234+Main+St.&city=Chicago+Heights rather than using raw spaces, which would break the URL. The same rule applies to first names, cities, and any other multi-word field you pass.

Two follow-ups are worth your time. To stop the same number landing twice, read the add_lead duplicate-check guide. For the bigger picture of how this call fits with every other API and AGI function, see the VICIdial API and AGI overview.

If you would rather your dialer come ready to take API pushes from day one, every VICIfast plan ships a hardened VICIdial box in under a minute, API enabled and ready for your first add_lead call.