Adding and dialing a lead with external_add_lead

external_add_lead is the VICIdial Agent API function that adds a new Lead into the manual dial list of the campaign that a logged-in Agent is on. It is a deliberately simplified version of the full add-lead call: instead of every field the data API supports, it covers the common customer-information fields and slots the record straight into the agent's manual dial queue so they can call it next.

When you'd use it

Reach for it when an outside system has a fresh contact that a specific agent should call right now. Maybe a web form just captured a callback request and you want it in front of the agent handling that queue. Because the record lands in the agent's manual dial list rather than the general Hopper, you skip the wait for the dialer to recycle and the agent dials it on their own screen. If you instead want a lead added to the database without targeting a live agent, that's the data-side add-lead call — see how to add a lead with the add_lead API.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: external_add_lead (agent_user, phone_number, names)
  API->>V: check DNC if requested
  alt number is clean
    V->>V: insert lead into campaign manual list
    V->>Agent: lead waiting in manual dial queue
    V-->>App: SUCCESS lead added
  else number in DNC
    V-->>App: ERROR PHONE NUMBER IN DNC
  end

VICIdial reads the agent's current campaign, optionally runs the DNC (do not call) checks you asked for, and inserts the lead into that campaign's manual dial list. From there it sits in the agent's Agent session ready to be dialed.

Parameters

• agent_user — the login of the agent whose manual dial list gets the lead. Required.
• dnc_check — optional, YES to check the number against the system DNC before adding.
• campaign_dnc_check — optional, YES to check against the campaign DNC for the agent's campaign.
• Lead data — you must populate at least one. Available fields include phone_number, phone_code, first_name, last_name, middle_initial, title, address1, address2, address3, alt_phone, city, state, province, postal_code, country_code, email, comments, source_id, vendor_lead_code, gender, date_of_birth, security_phrase, gmt_offset_now, rank, and owner. Only fields you send are written.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=external_add_lead&phone_number=7275551212&phone_code=1&first_name=Bob&last_name=Smith&dnc_check=YES

On success you get SUCCESS: lead added - 7275551212|TESTCAMP|101|123456|6666, which tells you the campaign, list id, and the new lead_id. The errors are specific and worth handling: ERROR: add_lead PHONE NUMBER IN DNC - 7275551212|6666 when a DNC check blocks the number, ERROR: campaign manual dial list undefined when the campaign has no manual list set up, ERROR: lead insertion failed if the insert itself fails, and the usual ERROR: agent_user is not logged in.

Gotchas

The most common surprise is the campaign manual dial list undefined error — external_add_lead has nowhere to put the lead unless the agent's campaign has a manual dial list configured, so set that up first. Also remember the DNC checks are opt-in; if you don't pass dnc_check or campaign_dnc_check, no scrubbing happens, which matters for compliance. For how this Agent API call differs from the full data API, read Non-Agent API vs Agent API, and for the bigger map of all the endpoints see the VICIdial API and AGI overview.

external_add_lead is the quickest path from an outside event to a live agent's dial queue. If you want a managed VICIdial box that spins up in under 40 seconds so you can wire this in today, see our plans.