Changing the agent's active lead with switch_lead

When an inbound caller turns out to be a different person than the record VICIdial pulled up, the agent can lose time hunting through screens to find the right file. The switch_lead function solves that at the API level. It is part of the Agent API, the HTTP interface that controls a live agent session Agent API, and it works the same way as the SELECT action in the agent screen's lead search feature.

A Lead in VICIdial is the record attached to a phone number: the name, address, notes, and disposition history stored in vicidial_list. When you call switch_lead, VICIdial replaces the lead on the agent screen and rewires the associated call logs to the new record without dropping the call. The agent keeps talking to the same person on the line; only the data behind the screen changes.

How switch_lead works

sequenceDiagram
  participant App as Your App
  participant API as agc/api.php
  participant Session as agent_session
  participant DB as vicidial_list
  App->>API: switch_lead agent_user lead_id
  API->>Session: verify agent has a live inbound call
  API->>DB: look up lead_id or vendor_lead_code
  DB-->>API: lead record found
  API->>Session: swap lead on agent screen
  API-->>App: SUCCESS switch_lead function set

The function only fires while the agent is on a live inbound call. If the agent is not currently talking to anyone, the API returns ERROR: agent_user does not have a live call. If the active call is outbound, it returns ERROR: agent call is not inbound. This constraint keeps the function focused: it is a correction tool for inbound traffic, not a general lead-switcher.

Parameters and example calls

You must supply either lead_id or vendor_lead_code. The lead_id is any valid numeric lead ID from the system. The vendor_lead_code is your own outside identifier stored against the record, handy when your CRM tracks leads by its own key rather than VICIdial's internal ID. If you pass both, lead_id takes priority and vendor_lead_code is ignored.

The agent_user parameter identifies whose screen gets updated, and the standard user, pass, and source credentials are required on every Agent API call. The source value is a short label naming the system making the request, which shows up in the API logs and makes it easy to trace which integration triggered a switch.

# Switch by numeric lead ID
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=switch_lead&lead_id=12345"

# Switch by vendor lead code
curl "https://your-server/agc/api.php?source=crm&user=6666&pass=1234&agent_user=1000&function=switch_lead&vendor_lead_code=1234567890"

A successful response includes the agent ID, the old lead ID, the vendor lead code, the campaign ID, and the new lead ID:

SUCCESS: switch_lead function set - 6666|12345|1234567890|TESTCAMP|12346

Parse that line by splitting on the pipe character. The last field is the lead ID the screen now points at, so your integration can confirm the switch landed on the record it intended rather than assuming success from the SUCCESS prefix alone.

When you would reach for this

The classic case is screen pop correction. An inbound call arrives and VICIdial matches it to a lead by caller ID, but the number belongs to a household where several people share a line, or to a business where the original record is stale. The agent learns the caller's real identity, your CRM looks up the correct lead_id, and switch_lead repoints the screen so notes and dispositions land on the right file. A second case is deduplication: if you discover mid-call that two records describe the same person, you can switch to the canonical one before the agent saves anything.

The campaign must have inbound lead search enabled. If it does not, the API returns ERROR: campaign does not allow inbound lead search and the screen stays unchanged. Check the campaign settings before wiring your CRM to this function.

This function fits naturally into a CRM lookup flow: your system identifies the real caller by phone number, fetches the matching lead_id, and calls switch_lead before the agent even needs to think about it. The Non-agent API handles adding and updating records in the database, while functions like this one handle the live session side.

For a broader look at how the Agent API and Non-Agent API divide their responsibilities, see Non-Agent API vs Agent API. The full list of functions in context lives in the VICIdial API and AGI overview. If you want a VICIdial box with the Agent API ready to accept calls from day one, every VICIfast plan provisions a configured server in under 40 seconds.