ViciDial Non-Agent API Basics | Lead Injection Guide

Manually importing a CSV of leads works for a batch upload, but most real integrations — a web form,
a CRM, a lead marketplace feed — need to push leads into ViciDial the moment they arrive, and sometimes
trigger an immediate call. ViciDial’s Non-Agent API is a plain HTTP GET/POST interface
(distinct from the Asterisk AMI covered in another guide on this blog) purpose-built for exactly this: an
external system calling into ViciDial to add leads or trigger dials, without needing an agent logged in or
any Asterisk-level access.

This guide covers enabling the API, authenticating, injecting a lead, checking for duplicates first, and
triggering a call — plus the security basics for exposing this endpoint safely.

Step 1: Understand What the Non-Agent API Covers

The Non-Agent API is an HTTP script (commonly agc/api.php or non_agent_api.php depending on version) accepting URL parameters that specify a function — add_lead, update_lead, external_dial, and others — each mapping to an action ViciDial’s own database/dialer layer would otherwise perform through the admin UI or agent screen.

Understanding ViciDial Non-Agent API function scope — Understanding what the Non-Agent API covers

Step 2: Locate and Enable the API Script

Confirm the Non-Agent API script is present in your ViciDial web root and that your server’s PHP configuration allows it to run — some installs disable or restrict it by default since it’s a powerful, unauthenticated-by-default entry point until you configure credentials. Check your ViciDial version’s documentation for the exact script path, since this has moved between major versions.

Locating and enabling ViciDial Non-Agent API script — Locating and enabling the API script

Step 3: Authenticate Requests

Every API call passes user and pass parameters corresponding to a ViciDial user account — create a dedicated API user for this purpose rather than reusing an admin or agent login, so its activity is distinguishable in logs and its access can be revoked independently. That user needs the appropriate permission flag enabled on its profile to actually use the API.

Authenticating ViciDial Non-Agent API requests with dedicated user — Authenticating requests

Step 4: Inject a Lead

A basic add_lead call passes function=add_lead, the target list_id, and lead fields like phone_number, first_name, last_name. A successful call returns a plain text response confirming success and the new lead’s ID — parse this response in your integration code to confirm the insert actually worked rather than assuming a 200 HTTP status alone means success.

Injecting a lead via ViciDial Non-Agent API add_lead function — Injecting a lead

Step 5: Check for Duplicates Before Inserting

Before calling add_lead, consider calling a duplicate-check function first (or set the API call’s duplicate-checking parameter, if your version supports it inline) — blindly inserting the same phone number repeatedly from a retried webhook or a flaky upstream feed pollutes your lead lists and can result in the same person being called multiple times unnecessarily.

Checking for duplicate leads before ViciDial API insertion — Checking for duplicates first

Step 6: Trigger an Outbound Call

The external_dial (or similarly named, version-dependent) function lets an external system trigger an immediate call to a specific number through a specific logged-in agent — the click-to-call pattern used by CRM integrations where clicking a contact’s phone number in another system initiates the call through ViciDial.

Triggering outbound call via ViciDial Non-Agent API external_dial — Triggering an outbound call

Step 7: Handle Responses and Errors

The API returns plain text starting with SUCCESS or ERROR followed by a description — always check for the ERROR prefix in your integration rather than only checking HTTP status codes, since a malformed request or bad credential typically still returns HTTP 200 with an error message in the body.

Handling ViciDial Non-Agent API success and error responses — Handling responses and errors

Step 8: Secure the API Endpoint

This endpoint can insert data and trigger calls — treat it like any other authenticated write API. Restrict access at the web server or firewall level to known source IPs (your CRM’s server, not the open internet), always call it over HTTPS so credentials aren’t sent in plaintext, and use a dedicated low-privilege API user rather than an admin account, following the same least-privilege pattern as our Proxmox API tokens guide.

Securing ViciDial Non-Agent API endpoint access — Securing the API endpoint

Quick reference

GET /agc/api.php
  ?source=crm-integration
  &user=napi_user&pass=SECRET
  &function=add_lead
  &phone_number=5551234567
  &list_id=3001
  &first_name=Jane&last_name=Doe

ViciDial Non-Agent API Basics (Programmatic Lead Injection)