Looking up leads from your app with lead_search

How to use the lead_search non-agent API to find lead IDs by phone number from your own application or CRM.

A customer calls in, and your own system only knows their phone number. Before you can update a record or pull its history from VICIdial, you need the lead's internal ID. The lead_search function answers exactly that question: give it a phone number, get back the matching lead IDs.

A Lead is one contact record - a phone number plus name and other fields - and every lead has a numeric ID. This call from the Non-agent API, the back-office set that reads and writes the database directly, searches the active lead table by phone number and hands back the IDs it finds.

What you send

The only required search field is the phone number, and you can pass several at once, separated by commas:

phone_number - 6 to 19 digits each, multiple numbers comma-separated.
source - a short label, up to 20 characters, describing what made the call.

Two settings are worth knowing. records caps how many lead IDs come back per number, defaulting to 1000 with the most recently inserted leads first. Set archived_lead to Y to search the archive table instead of the active one. Here is a multi-number lookup:

curl "http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=lead_search&phone_number=9998885112,9998887112,9998886112,4075551212"

Reading the result

A success response does not print the word SUCCESS. Instead you get one line per searched number, in the form search_key, records_found, lead_ids:

9998885112|4|1949076-1946517-1943958-1941399
9998887112|8|1946941-1946940-1946939-1946875-1946805-1946656-1946655-1944382
9998886112|1|1946891
4075551212|0|

When a number matches more than one lead, the IDs are joined with a dash. A number with no match shows a count of 0 and an empty ID field, as the last line above shows. So a single response can mix hits and misses, and your code should parse each line on its own rather than assume the whole batch succeeded or failed together.

If you would rather get a column row labeling the output, add header=YES. And if the numbers you want live in the archive rather than the active table, set archived_lead=Y, which switches the search to the archive only. The default 1000-record cap is generous, but raise or lower it with the records field if a busy number returns a long dash-joined list you do not want to wade through.

How the call flows

sequenceDiagram
  participant App as Your CRM
  participant API as non_agent_api.php
  participant DB as Lead Table
  App->>API: lead_search phone_number list
  API->>API: Check permission
  API->>DB: Match each number
  DB-->>API: Lead IDs per number
  API-->>App: one line per number with IDs

The API user needs user_level 7 or higher with "view reports" enabled and modify_leads set to 1 through 5. If none of the searched numbers match anything, the whole call returns an error rather than rows of zeros, so handle that case in your code.

This is the call you reach for when wiring a CRM, the customer-record system your team works in, to VICIdial. A common pattern is a screen-pop: an inbound call arrives, you run lead_search on the caller's number, and you have the lead ID before the agent says hello.

lead_search only returns IDs, not the rest of the record. Once you have an ID, pull the full lead with lead_all_info - see our guide to lead_all_info. Both calls work hand in hand to keep a Lead list in sync with your own app.

For how all of this fits together, read the VICIdial API and AGI overview. If running the dialer is not how you want to spend your week, VICIfast gives you a managed box with this API live out of the gate - see our plans.