Blocking a number with the add_fpg_phone API

A DNC list is the right tool for opt-outs, but it is not the only way to keep the dialer off a number. Filter Phone Groups let you build reusable block lists you can attach to a campaign's lead filter — handy for screening out known bad numbers, internal extensions, or competitor mainlines without flagging them as Do-Not-Call. The Non-Agent API gives you add_fpg_phone to populate one of these groups from your own code.

What add_fpg_phone does

It adds a phone number to a Filter Phone Group. A Filter phone group is a named bucket of numbers that a campaign's Filter can reference to exclude matching leads from dialing. Unlike a DNC (do not call) entry, an FPG number is not a compliance record — it is a dialing-logic decision, so you can build and tear down these groups freely.

The group has to exist already. add_fpg_phone fills an existing group; it does not create one. Set the group up in the admin screen first, then point the API at its ID.

Permissions you need first

The API user needs user_level 8 or higher and the "modify lists" permission enabled — the same grant used by the DNC functions. If you have not set an API account up yet, walk through VICIdial API user level and permissions first.

The required fields

• phone_number — the number to add, 6 to 20 characters
• group — 2 to 30 characters, a valid Filter Phone Group ID already in the system

Example call

http://your-server/vicidial/non_agent_api.php?source=test&function=add_fpg_phone&user=6666&pass=1234&phone_number=7275551212&group=TEST_IN_FILTER

How the call decides

flowchart TD
    A[add_fpg_phone call] --> B{user_level 8 and modify lists?}
    B -->|no| C[ERROR: NO PERMISSION]
    B -->|yes| D{group ID exists?}
    D -->|no| E[ERROR: FILTER PHONE GROUP DOES NOT EXIST]
    D -->|yes| F{number already in group?}
    F -->|yes| G[ERROR: NUMBER ALREADY EXISTS]
    F -->|no| H[insert number into group]
    H --> I[SUCCESS: NUMBER HAS BEEN ADDED]

Reading the response

A clean add returns: SUCCESS: add_fpg_phone FILTER PHONE GROUP NUMBER HAS BEEN ADDED – 6666|7275551212|TEST_IN_FILTER. The errors you should handle:

• ERROR: add_fpg_phone USER DOES NOT HAVE PERMISSION TO ADD FILTER PHONE GROUP NUMBERS - 6666|0 — the API user lacks user_level 8 or "modify lists".
• ERROR: add_fpg_phone YOU MUST USE ALL REQUIRED FIELDS - 6666|||1000 — phone_number or group is missing.
• ERROR: add_fpg_phone FILTER PHONE GROUP DOES NOT EXIST - 6666|TEST_IN_FILTER2 — the group ID is wrong or was never created.
• ERROR: add_fpg_phone FILTER PHONE GROUP NUMBER ALREADY EXISTS - 6666|7275551212|TEST_IN_FILTER — the number is already in that group, so nothing changed.

To take a number back out of a group, use the paired function in unblocking a number with delete_fpg_phone.

Run it on a hosted box

The Non-agent API is included on every VICIdial install, so add_fpg_phone is there as soon as your dialer is provisioned in under 40 seconds. VICIfast runs the API for you on every plan — see pricing.