Stopping duplicate leads with add_lead duplication checks

You feed the same lead source into VICIdial every morning, and now the same person is getting called three times a day. The fix lives inside the call you already use to load leads: the duplicate_check setting on add_lead, part of the Non-Agent API (Application Programming Interface) Non-agent API.

A duplicate check tells VICIdial to look for a matching record before it inserts a new one Duplicate check. If it finds a match, the call returns an error instead of adding the lead, and it hands back the lead ID and list ID of the record already in the system so you know what blocked it. A lead, remember, is one calling record: a phone number plus the data attached to it Lead.

Scope: list, campaign, or whole system

The first decision is how wide to search. Three suffixes set the scope. DUPLIST checks only the same lead list, the named bucket the new lead would join Lead list. DUPCAMP checks every list tied to that list's campaign, the outbound job that dials it Campaign. DUPSYS checks the entire system.

Those three match on phone number alone. If you want a wider match, there are variants. DUPPHONEALTSYS matches the new number against both the phone number and the alt_phone field of existing leads, the secondary number stored on a record Alternate phone number. DUPNAMEPHONELIST matches on first name, last name, and phone number together. You can combine checks with a dash, like DUPLIST-DUPNAMEPHONELIST.

curl "https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&first_name=Bob&last_name=Wilson&duplicate_check=DUPLIST-DUPNAMEPHONELIST"

When a match is found, you get a line like this, with the existing lead ID and list ID at the end:

ERROR: add_lead DUPLICATE PHONE NUMBER IN SYSTEM - 7275551111|101|8765444|101

How the check decides

flowchart TD
  A[add_lead with duplicate_check] --> B{Match in chosen scope?}
  B -- No --> C[Insert new lead]
  B -- Yes --> D{X-day window set?}
  D -- No --> E[Reject as duplicate]
  D -- Yes --> F{Match loaded inside window?}
  F -- Yes --> E
  F -- No --> C

You can soften any check with a day window. Append a value like 90DAY to a scope, so DUPSYS90DAY only counts a record as a duplicate if it was loaded in the last 90 days. Older matches are ignored and the new lead goes in. Allowed windows run from 1 day up to 360. This is how you let a number back into rotation after a cool-off period.

The error you get back is not just a rejection; it is useful data. Each duplicate error ends with the lead ID and list ID of the record that blocked the insert, so your loader can decide what to do next. You might log it, update the existing lead instead, or send the new data somewhere else. The title-and-alt-phone variants, like DUPTITLEALTPHONESYS, and the name-and-phone variants give you finer control when a plain phone-number match is too broad or too narrow for the data you load.

Duplicate checking pairs naturally with a Do Not Call screen. Adding dnc_check=Y to the same call screens the number against your Do Not Call list, the set of numbers you must not dial, on the way in DNC (do not call). Together, the two stop both repeat records and numbers you are not allowed to touch, all before the lead ever reaches an agent.

Duplicate checking is one of several add_lead options. If you have not run the call before, start with how to push a lead with add_lead, and for where it sits among the rest of the functions see the VICIdial API and AGI overview.

Clean lead loading keeps your dial rates honest and your compliance team calm. Every VICIfast plan hands you an API-ready dialer in under a minute, so you can wire these checks into your loader the same day.