Pulling a full lead record with lead_all_info

You have a lead ID and you want everything VICIdial knows about that contact - name, address, status, the lot - returned to your own application. Reading the database table directly is fragile and easy to get wrong. The lead_all_info function gives you the whole record in one clean call.

A Lead is a single contact record: a phone number plus name, address, status, and more. This call belongs to the Non-agent API, the back-office set that reads and writes the database rather than driving a live agent, and it returns every standard field for one lead, with custom fields optional.

What you send

The required fields are source and lead_id. The simplest call looks like this:

curl "http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=lead_all_info&lead_id=1079425"

You do not even need a lead ID. Pass a phone_number instead and the call returns every lead with that number, up to 1000, most recent first. A few options shape the output:

• custom_fields - set to Y to include the list's custom fields in the result.
• stage - the output format: csv, tab, newline, json, or pipe (the default).
• archived_lead - set to Y to read the record from the archive table instead.

Reading the result

A success response skips the word SUCCESS and prints the fields directly. In the default pipe format you get one long line, with the header naming each column - status, user, vendor_lead_code, source_id, list_id, phone_number, first_name, last_name, and so on through to the entry list ID. Pass header=YES if you want that column row included.

Two of those columns trip people up. The status is the lead's current Status (lead status), the short code for how it last ended. The vendor_lead_code is the Vendor lead code, an outside reference ID you can store when loading leads from a data supplier - handy for matching VICIdial records back to your source system.

Pick the stage format that matches how your code reads the response. JSON is the friendliest if you are parsing in an application, since you get named keys instead of having to count pipe positions. Stick with pipe or csv if you are piping the output to a quick shell script or a spreadsheet. The two error responses to handle are LIST NOT FOUND, when the lead's list no longer exists, and LEAD NOT FOUND, when the ID or phone number matches nothing.

How custom_fields changes the call

flowchart TD
  A[lead_all_info request] --> B{custom_fields set}
  B -->|N default| C[Return standard fields only]
  B -->|Y| D{force_entry_list_id set}
  D -->|No| E[Read custom data from lead's own list]
  D -->|Yes| F[Read custom data from given list]
  E --> G[Return standard plus custom fields]
  F --> G

The API user needs user_level 7 or higher with "view reports" enabled and modify_leads set to 1 through 5. Without that you get a permission error rather than data.

This call pairs naturally with lead_search. If you start from a phone number rather than an ID, run lead_search first to get the lead ID, then lead_all_info for the full record. Together they let a CRM, your customer-record system, mirror a VICIdial lead without touching the database by hand.

For the full set of back-office calls, see the VICIdial API and AGI overview. And if you would rather not run and patch the dialer yourself, VICIfast gives you a managed VICIdial box with the API ready to call - see our plans.