# FreePBX Blacklist and Caller ID Blocking: Stop Junk Calls (Tested)

Source: https://srvscripts.com/guides/freepbx-blacklist-block-caller-id/
Updated: 2026-11-02
Publisher: srvScripts (https://srvscripts.com/)

**Short answer:** In FreePBX 17, use the FreePBX Blacklist (Admin > Blacklist) for single numbers, and turn on Block Unknown/Blocked Caller ID for anonymous calls. The Blacklist only matches the exact caller ID string your trunk delivers (2125550199 is not +12125550199), and it answers blocked calls before hanging up. To block a whole range, such as one prefix, add an inbound route with a caller ID pattern like `_1800NXXXXXX` and the destination Terminate Call (on the DID, or for any DID with **CID Priority Route** ticked); in our test that rejected the call with 603 Decline without answering it. (Reviewed October 2026.)

In short: In FreePBX 17, use the FreePBX Blacklist (Admin > Blacklist) for single numbers, and turn on Block Unknown/Blocked Caller ID for anonymous calls. The Blacklist only matches the exact caller…

Robocalls and repeat junk callers are one of the most common FreePBX forum questions, and the two built-in tools behave differently in ways the GUI does not show. We sent inbound calls with chosen caller IDs into a FreePBX 17 lab server with SIPp, posing as the SIP trunk, and recorded what each caller received and where Asterisk sent the call.

## Which tool to use

| Goal | Use | Matching | What the caller gets |
| --- | --- | --- | --- |
| Block one known number | Blacklist | Exact caller ID number or caller ID name | Call answered, then hung up (200 OK, then BYE) |
| Block anonymous, private or withheld calls | Blacklist setting Block Unknown/Blocked Caller ID | Caller ID number empty or unknown, unavailable, anonymous, private, restricted, blocked (any case) | Answered, then hung up |
| Block a prefix or range | Inbound route with a caller ID pattern | Asterisk pattern, e.g. _1800NXXXXXX | Rejected without answer (603 Decline with Terminate Call: Hangup) |

The Blacklist applies to every inbound route; an inbound route with a caller ID only applies to the DID it is set on. For ranges on several DIDs, add one route per DID, or leave the DID empty (“any DID”) and tick **CID Priority Route** on that route. Without that option, our DID route won and calls from the blocked range still went to the extension (details below).

## Block a single number with the FreePBX Blacklist

Open **Admin > Blacklist**, click **Blacklist Number**, enter it in **Number/CallerID**, add a description and save. The module writes the entry to the Asterisk database straight away; no Apply Config is needed for numbers. The same entry from the command line, useful for scripts:

```
asterisk -rx 'database put blacklist 2125550199 "repeat junk caller"'
asterisk -rx "database show blacklist"
asterisk -rx "database del blacklist 2125550199"   # remove it again
```

Results from our lab with `2125550199` on the list:

| Caller ID number sent by the trunk | Result |
| --- | --- |
| 2125550199 | Blocked: answered, then hung up |
| 12125550199 | Not blocked: reached the route to extension 1001 |
| +12125550199 | Not blocked: reached the route to extension 1001 |
| 3105550111 (not on the list) | Not blocked |

The match is a plain string comparison. Before adding numbers, look at how your trunk presents caller ID: place a test call from a mobile and check the CDR `src` column or the `From` header in a SIP trace. If your provider sends E.164 with a plus, add numbers with the plus; if it sends 10 digits, add 10 digits. If your inbound route normalises caller ID (for example with Set CallerID or a caller ID prefix), the Blacklist sees whatever is set by the time it runs.

The Blacklist also matched on the caller ID **name**: an entry `SPAM LIKELY` blocked a call from `4155550123` whose name was SPAM LIKELY. That is handy when a carrier labels spam in the name field, but be careful with generic names such as WIRELESS CALLER, which would block every caller with that label.

## Block anonymous and withheld caller ID

In **Admin > Blacklist > Settings**, set **Block Unknown/Blocked Caller ID** to Yes, save and press **Apply Config**. Apply Config matters: FreePBX only writes the anonymous checks into the dialplan when it regenerates it. When we set the flag directly in the Asterisk database without a reload, an anonymous call still went to the extension; after `fwconsole reload` it was blocked.

```
asterisk -rx "database put blacklist blocked 1"
fwconsole reload
grep -n -A9 "^\[app-blacklist-check\]" /etc/asterisk/extensions_additional.conf
```

After the reload, calls with caller ID number `anonymous`, `Restricted` and `unknown` were all blocked, and a normal number still got through. The generated dialplan lowercases the number and compares it with unknown, unavailable, anonymous, private, restricted and blocked, and also catches an empty number.

If your carrier sends the real number in `P-Asserted-Identity` with `Privacy: id`, what Asterisk uses as the caller ID depends on the trunk’s trust settings, so test with a withheld call from a mobile before relying on this. Some legitimate callers withhold their number (hospitals, some businesses), so consider sending blocked calls to a voicemail or an announcement instead of hanging up.

## Choose where blocked calls go

**Destination for BlackListed Calls** in the same Settings tab sets the destination; the default is Terminate Call: Hangup. Whatever you pick, the dialplan runs `Answer` first. In our test the caller received `200 OK` and then a hang-up, so the call shows as answered in your CDR, and for the caller it is a connected call, which their carrier may charge for. We did not check how any carrier bills it. If you would rather reject calls without answering, use an inbound route as described next.

## Block a range of numbers with an inbound route

Under **Connectivity > Inbound Routes**, add a route with your DID in **DID Number**, the pattern in **CallerID Number** (patterns start with an underscore), and **Terminate Call: Hangup** as the destination. FreePBX turns it into a caller ID match on the DID extension:

```
exten => 15550100/_1800NXXXXXX,1,Set(__DIRECTION=INBOUND)
```

| Caller ID | Route matched | Result |
| --- | --- | --- |
| 18005550123 | DID + _1800NXXXXXX | Rejected with 603 Decline, not answered |
| 18885550123 | DID only | Reached the route to extension 1001 |
| 2125550100 | DID only | Reached the route to extension 1001 |

For the same DID, Asterisk prefers the route with the caller ID match, so it did not matter that the DID-only route already existed. Pattern letters follow normal Asterisk rules: `X` is any digit, `N` is 2–9, `[2-5]` is a range and `.` matches one or more characters; see [Asterisk dialplan pattern matching](https://srvscripts.com/guides/asterisk-dialplan-pattern-matching/). As with the Blacklist, the pattern has to match the format your trunk sends.

### One pattern for every DID: CID Priority Route

A route with an empty DID Number and a caller ID pattern matches calls to any DID, but by default a route for the called DID is preferred over it. On our lab, with the DID route to extension 1001 in place, we added a second route with no DID, `_1800NXXXXXX` and Terminate Call:

| CID Priority Route on the any-DID route | Call from 18005550123 | Call from 2125550100 |
| --- | --- | --- |
| Off (default) | Reached the route to extension 1001: not blocked | Reached the route to extension 1001 |
| On | Rejected with 603 Decline, not answered | Reached the route to extension 1001 |

So tick CID Priority Route on any caller-ID-only blocking route, apply the config, and test one blocked and one normal number afterwards.

## Test your rules with SIPp

Testing with your own mobile only covers one number. We used SIPp to place one call from the trunk’s IP address with any caller ID we wanted. The scenario sends an INVITE with a `From` header built from a CSV file and handles 200, 4xx/5xx and 6xx answers:

```
printf 'SEQUENTIAL\n18005550123;Toll Free Junk\n' > cid.csv
sipp 203.0.113.10:5060 -sf inbound-cid.xml -inf cid.csv -s 15550100 \
  -i 198.51.100.20 -p 5091 -m 1 -trace_msg
```

The CSV starts with `SEQUENTIAL`, then one `number;name` line per call. The scenario file `inbound-cid.xml` we used:

```

  ;tag=[pid]cid[call_number]
To:
Call-ID: [call_id]
CSeq: 1 INVITE
Contact:
Max-Forwards: 70
Content-Type: application/sdp
Content-Length: [len]

v=0
o=carrier 53655765 2353687637 IN IP[local_ip_type] [local_ip]
s=-
c=IN IP[media_ip_type] [media_ip]
t=0 0
m=audio [media_port] RTP/AVP 0 8
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
]]>

  ;tag=[pid]cid[call_number]
To: [peer_tag_param]
Call-ID: [call_id]
CSeq: 1 ACK
Max-Forwards: 70
Content-Length: 0

]]>

  ;tag=[pid]cid[call_number]
To: [peer_tag_param]
Call-ID: [call_id]
CSeq: 2 BYE
Max-Forwards: 70
Content-Length: 0

]]>

  ;tag=[pid]cid[call_number]
To: [peer_tag_param]
Call-ID: [call_id]
CSeq: 1 ACK
Max-Forwards: 70
Content-Length: 0

]]>

```

The source address must be one your PBX accepts as the trunk (the PJSIP identify match), so run this only on a lab server or from a host you control that is listed as the trunk. Check where each call went in `/var/log/asterisk/full`: a blocked call passes through `app-blackhole`. For why a `200 OK` alone proves little, see [a 200 OK is not proof the carrier got the call](https://srvscripts.com/guides/sipp-200-ok-not-proof-carrier/).

## How we tested

- Server: FreePBX 17.0.33.2 with Asterisk 22.11.0 on Debian 12, Blacklist module 17.0.1.2, 19–20 October 2026.

- Calls: SIPp 3.6 sending INVITEs from the lab trunk’s address to DID 15550100 (inbound route to extension 1001), one call per caller ID. Outcome read from the SIP response and the dialplan steps in the Asterisk full log. Extension 1001 was not registered, so “reached the route to extension 1001” in the tables means the call passed every blocking rule, matched that route and then ended with 503 from the unregistered endpoint; no phone rang.

- Not tested: the Bulk Handler CSV import for the Blacklist, the *30/*31/*32 feature codes, caller ID in P-Asserted-Identity with privacy, and carriers that send caller ID in other formats.

- 21 October 2026: a caller-ID-only route (no DID) tested with CID Priority Route off and on, with the DID route in place.

- The lab was returned to its original state afterwards (Blacklist entries, the blocked flag and the test route removed).

## FAQ

### Why is the FreePBX Blacklist not blocking a number?

Usually because the stored number does not match the caller ID string the trunk delivers, for example 2125550199 on the list and +12125550199 on the call. Check the CDR `src` value of a real call from that number and add it in exactly that form.

### Do I need Apply Config after adding a Blacklist number?

Not for numbers; they are read from the Asterisk database on every call. You do need Apply Config (or `fwconsole reload`) after changing Block Unknown/Blocked Caller ID.

### Can the FreePBX Blacklist block a whole area code?

No, it matches exact values. Use an inbound route with a caller ID pattern such as `_1212NXXXXXX` and Terminate Call as the destination, on each DID or once with no DID and CID Priority Route ticked.

### Why do blocked callers show as answered calls?

The Blacklist dialplan answers the call before sending it to the blocked-call destination. An inbound route with Terminate Call: Hangup rejected the call without answering in our test.

Related: [STIR/SHAKEN in Asterisk and FreePBX](https://srvscripts.com/guides/stir-shaken-asterisk-freepbx/) and [toll fraud prevention](https://srvscripts.com/guides/asterisk-freepbx-toll-fraud-prevention/). Official reference: [Sangoma: Blacklist module](https://sangomakb.atlassian.net/wiki/spaces/PG/pages/20775031/Blacklist+Module).
