API New Lead URL: Pushing New Leads to an External System

When a new lead lands in VICIdial through the API, you often want something else to know about it: your CRM, a reporting database, a notification channel. The API New Lead URL is the setting that makes that happen. It tells VICIdial to fire off a web request every time a new lead is inserted through the add_lead API function, so an external system can react in real time.

It is a simple piece of plumbing, but it works at two levels and has one important scope rule. Get those right and you have a clean one-way sync of new leads out of the dialer.

What it fires on

The API New Lead URL is triggered specifically by the add_lead function of the Non-agent API, the part of the API (application programming interface) meant for scripts and integrations rather than for the agent screen. Every time add_lead inserts a Lead, VICIdial calls the URL you set. The request carries lead variables in the URL (in VICIdial), the same way web form fields do, so the receiving system gets the data it needs to create or match a record on its end.

Functionally this is an outbound Webhook: an event happens (a lead is added) and VICIdial pings an address you control. Your endpoint does whatever it needs to do with the payload.

List level versus system level

There is a System Setting called API New Lead URL that applies to the whole system, and there is a per-list field of the same name on the list modification page. The per-list field overrides the system setting for new API leads in that list. The defaults work like this:

• Leave the list field blank (the default) and that list defers to whatever the system-wide setting says.
• Set a valid URL on the list and it overrides the system setting for that list only.
• Set the list field to DISABLED and that list sends no request at all, even if the system setting has one.

How the resolution works

flowchart TD
  A[Lead added via add_lead API] --> B{List field set?}
  B -->|Blank| C[Use system API New Lead URL]
  B -->|DISABLED| D[Send no request]
  B -->|Valid URL| E[Call the list URL]
  C --> F[Fire request to endpoint]
  E --> F
  F --> G[External system creates or updates record]

Read that top to bottom and the precedence is clear: the list always decides for its own leads, and the system setting is the fallback only when the list field is blank.

Practical setup notes

A few things to get right so it actually works:

1. The URL cannot be a relative path. Use a full address your VICIdial server can reach over the network.
2. It fires only for the add_lead API, not for leads loaded through the web lead loader. Bulk-loaded leads do not trigger it.
3. Encrypted custom field values are not available in ADD LEAD URL variables, so do not expect to pass those through.
4. Make your receiving endpoint idempotent, so a retried or duplicated request does not create two records for one lead.

If your goal is loading leads in bulk rather than syncing them out one at a time, the lead loader is the better tool; see loading leads into VICIdial. And to find the field on the page, modifying a VICIdial list walks through every list setting.

This setting is one of several ways lists hook into outside systems. For the rest, see the lists and leads guide.

A dialer that plays nicely with your stack

Integrations are easier when you have full control of your own server and a real public address to point them at. We provision a dedicated, secured VICIdial box in under 40 seconds with a branded subdomain over HTTPS. See plans and pricing.