How to Push CRM Leads Into VICIdial via API

Use the VICIdial Non-Agent API's add_lead function to push records from any CRM into a campaign list in real time, without touching the VICIdial admin panel.

Most teams manage prospect records in a CRM — a Customer Relationship Management system that tracks contacts, deals, and history CRM. VICIdial stores its own calling data in a separate database. When a new lead comes into your CRM, you want it to start ringing in your dialer within seconds, not after a manual export-import cycle the next morning. The Non-Agent API's add_lead function — part of the set of HTTP calls that manage data outside the live agent screen Non-agent API — makes that real-time push straightforward.

How the push works

sequenceDiagram
  participant CRM as Your CRM
  participant Hook as Webhook or Scheduled Job
  participant API as non_agent_api.php
  participant DB as vicidial_list
  participant Camp as VICIdial Campaign
  CRM->>Hook: new lead created event
  Hook->>API: add_lead phone_number list_id source
  API->>DB: INSERT row with status NEW
  DB-->>API: new lead_id
  API-->>Hook: SUCCESS lead has been added
  Camp->>DB: pull next leads from hopper
  DB-->>Camp: includes new lead

Permissions and auth

Every Non-Agent API call authenticates with a user and pass parameter in the query string. The VICIdial user account you use must have modify_leads set to 1 and a user level of 8 or higher. You set both fields in the VICIdial Admin panel under Users. Without them the API returns USER DOES NOT HAVE PERMISSION TO ADD LEADS regardless of how correct the rest of the request is. Create a dedicated API-only user with exactly these permissions and nothing else — that way you can revoke it without affecting human agent accounts.

The minimum API call

The endpoint is https://your-server/vicidial/non_agent_api.php. Required parameters are function=add_lead, phone_number (6–16 digits), phone_code (country dialing prefix, defaults to 1), and list_id (the lead list, the named bucket of records a campaign dials through Lead list, that you want the record added to). A minimal call from a CRM webhook handler:

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=101\
&first_name=Maria&last_name=Santos\
&vendor_lead_code=CRM-98765"

The vendor_lead_code parameter is your CRM's own record identifier — the unique key on your side that you will use to match a VICIdial disposition back to the originating record later Vendor lead code. Always send it. The source parameter is a short label (up to 20 characters) that shows up in the API log and makes troubleshooting much easier when you have multiple integrations writing leads simultaneously.

Speeding up the dial with hopper injection

Adding a lead puts it in the list with status NEW. The campaign's auto-dialer will pick it up on its next cycle, but that can take minutes depending on how the campaign is configured. To dial the lead immediately, append add_to_hopper=Y to the same call. The hopper is the short queue of leads the dialer is actively working through right now Hopper. Injecting directly into the hopper means the next available agent gets this lead on their screen within the current dial cycle.

Two optional safeguards are worth adding to any CRM integration. Pass dnc_check=Y and the API will refuse to insert any number already on your Do Not Call list. Pass list_exists_check=Y and the API will reject a list_id that does not exist rather than silently inserting into list 999 (the default). Both catch configuration mistakes before they create hard-to-clean orphan records.

Multi-word values in URL parameters need plus signs instead of spaces. A lead named "John Smith" in Chicago must be encoded as first_name=John&last_name=Smith&city=Chicago — the last name and city happen to be single words here, but something like address1=1234+Main+St needs the plus. A URL-encoding library in your language handles this automatically.

One field that pays for itself quickly is source_id. This is a numeric identifier that maps to a lead source record in the VICIdial admin — the named origin of a batch of leads, such as 'Web Form', 'Trade Show', or a specific CRM campaign Lead source. Tagging each pushed lead with the correct source_id lets you filter the live reports by origin so you can see which CRM campaign is producing calls that convert and which ones are burning agent time.

Consider also passing call_back_status set to Y along with a callback_datetime when your CRM signals that a contact requested a follow-up at a specific time. This places the lead as a scheduled callback Scheduled callback in VICIdial rather than as a plain new record, so the dialer will only attempt it at the window the customer asked for instead of lumping it into the next available dial cycle.

If your CRM can fire a webhook the moment a record is created, wire the HTTP call directly in that webhook handler. If it cannot, a polling script that queries your CRM for records modified in the last two minutes and pushes any that are not yet in VICIdial works just as well. Store the VICIdial lead_id from the SUCCESS response back into your CRM record so you can look up status later. A response like SUCCESS: add_lead LEAD HAS BEEN ADDED - 7275551212|6666|101|193715|-4 gives you the lead ID as the fourth pipe-delimited field.

For a complete treatment of add_lead including the duplicate-check options, see how to add a lead with the add_lead API. For the full picture of Non-Agent API capabilities alongside the Agent API and AGI, see the VICIdial API and AGI overview.

If you want a VICIdial server that comes with the API already configured and reachable over HTTPS, every VICIfast plan provisions a hardened box in under 40 seconds so your CRM integration can go live the same day.