What the API source parameter is for

You keep seeing source=test in every VICIdial API example and wonder whether it matters. It does, just not in the way the function name does. The source parameter is a label that says who or what made the call. The examples use test only as a placeholder, and copying that placeholder into production is a small habit worth breaking.

It belongs to the same family as user, pass, and function — the parameters nearly every call carries. The difference is that the others change what happens, while source changes only what you can see about it afterward.

It describes the caller

In the Non-agent API, source is a short description of what originated the API call, with a limit of 20 characters. It does not change what a function returns. A campaigns_list call gives you the same Campaign rows whether source says test or crm_nightly_sync.

Why bother filling it in

VICIdial can log API requests, and your source value is what makes those logs readable. When several systems hit the same server — a nightly importer, a website call-me button, an CRM push — a generic test on every line tells you nothing. A distinct label per integration tells you exactly which app added a Lead or queried a report.

Picture the day something goes wrong. A batch of contacts shows up in the wrong place, and you need to know which system put them there. If every call used test, you are stuck guessing. If the importer used crm_sync and the web form used web_callme, the log answers the question for you. That is the whole value of the field: it turns an anonymous pile of requests into an audit trail you can actually read.

# Each integration gets its own source label
curl "https://server/vicidial/non_agent_api.php?source=crm_sync&function=add_lead&user=6666&pass=1234&..."
curl "https://server/vicidial/non_agent_api.php?source=web_callme&function=add_lead&user=6666&pass=1234&..."

How source flows through a call

flowchart TD
    A[Your app sets source label] --> B[API call sent]
    B --> C[Function runs and returns data]
    C --> D[Request recorded with source]
    D --> E[Later you filter logs by source]
    E --> F[See which app made each call]

Keep in mind the field is required on most functions and capped at 20 characters, so plan a short naming scheme up front rather than padding it with detail it cannot hold. A scheme like crm_sync, web_callme, and billing_export stays well under the limit and still reads clearly months later. Some functions even echo your label back inside their response, which makes correlating a reply with the right caller easier still. So treat source as free documentation: it costs nothing to set and saves real time when you read a response that confused you — see how to read VICIdial API responses.

For where source fits among the other API (application programming interface) parameters, read the VICIdial API and AGI overview. Managed VICIfast servers keep request logging ready to go, so a clear source pays off the first time you go hunting — see the pricing page.