# FreePBX CID Superfecta source — Numbers Online caller names

- Category: PBX & softphones
- Published: June 3, 2026 · Updated: June 11, 2026
- Canonical: https://numbers.online/docs/integrations/freepbx-superfecta

Add **Numbers Online** as a caller-name (CNAM) source in FreePBX's *CID Superfecta*
module. On each inbound call, Superfecta asks Numbers Online for the caller's name
and — if you opt in — flags high-risk callers using a supplementary spam signal.
It's a single drop-in PHP file, configured entirely from the FreePBX admin UI.

> **Positioning.** Numbers Online provides an *advisory* caller name and a
> *low-confidence, supplementary* spam signal. Your PBX keeps every routing,
> labeling, and blocking decision and remains responsible for compliance. The
> source never asserts that a caller is lawful, unlawful, "safe", or "spam" — the
> spam flag is operator-opt-in and you choose the threshold.

This is different from the [Asterisk / FreePBX dialplan integration](./asterisk-freepbx.md),
which calls the older signed `inbound/lookup` endpoint from your dialplan for
routing decisions. This guide is the **caller-name display** path: a Superfecta
source backed by the JSON `GET /v1/lookup/{e164}` endpoint, with no dialplan edits.

## What you need

- FreePBX 16 or 17 with the **CID Superfecta** module installed (it ships under
  *Admin → CID Superfecta*).
- A Numbers Online API key (free tier: 60 requests/min, unbilled).
- Shell access to the PBX to drop in one file.

## 1. Get an API key

```bash
curl -sS -X POST https://numbers.online/api/v1/account/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","name":"Your Company"}'
```

The response includes your API key **exactly once** — copy it now and store it
safely. Full API reference: <https://numbers.online/docs>.

## 2. Install the source file

Download the source onto the PBX and place it in Superfecta's `sources/` directory:

```bash
cd /var/www/html/admin/modules/superfecta/sources/
curl -sSO https://numbers.online/integrations/freepbx/source-NumbersOnline.module
```

Fix ownership so the web/Asterisk user can read it. The portable way is `fwconsole`:

```bash
fwconsole chown
```

(Equivalently: `chown asterisk:asterisk source-NumbersOnline.module`. Your install
may use `apache` or `www-data` — `fwconsole chown` applies whatever your system
expects.) No service restart is needed; Superfecta discovers the file on its next
config load.

## 3. Enable and order it in your scheme

1. Go to **Admin → CID Superfecta**.
2. Pick the **scheme** used by your inbound route (often `Default`), or create one.
3. Move **NumbersOnline** into the list of *enabled* sources and order it where you
   want it tried. Superfecta queries sources top-to-bottom and uses the first name
   it gets, so place Numbers Online above generic fallbacks if you want it to win.
4. Open the **NumbersOnline** source to set its options (next section).
5. Save the scheme, then attach the scheme to your inbound route(s) if you haven't.

## 4. Configuration fields

| Field | Default | What it does |
|-------|---------|--------------|
| **API_Key** | — | Your Numbers Online key. Sent only as an `Authorization: Bearer` header over TLS — never placed in a URL and never logged. |
| **Spam_Flag** | checked | Flag high-risk callers using the supplementary spam signal. When on, Superfecta applies your scheme's spam handling to flagged calls. Uncheck to use Numbers Online for names only. |
| **Spam_Threshold** | `80` | Flag a caller only when its `spam_score` (1–99, higher = riskier) is at or above this value. `80` flags only the highest-risk callers; lower it to flag more aggressively. |
| **Ignore_Keywords** | `unavailable, unknown` | Comma-separated words. If the returned name contains any of them, it's discarded so other sources can supply a name. Useful for dropping placeholder names. |

The source sets only Superfecta's internal spam flag — **what happens to a flagged
call (prefix the name, send to a different destination, etc.) is configured in
Superfecta / your inbound route, not here.** You choose both the wording shown to
agents and the threshold, keeping the risk signal firmly operator-controlled.

## Fail-open behavior

Caller-name lookups must never delay or block call setup. The source uses tight
timeouts (2s connect, 5s total) and **fails open** on every error path — a slow or
unreachable API, a bad key (`401`), exhausted credit (`402`), or a rate limit
(`429`) all cause the source to return *no name* and let other Superfecta sources
run. An error is never rendered as a caller name. The call always proceeds.

## Pricing

Lookups against `/v1/lookup` are billed per the published rates: **$0.004** per
lookup that performs a fresh CNAM dip, **$0.002** for a cache hit or when no CNAM
supplier resolves a name, and **invalid numbers are free**. The **free tier is
unbilled** at 60 requests/min — plenty for evaluation and low-volume PBXs. Current
pricing and higher-volume tiers: <https://numbers.online/docs>.

## Troubleshooting

Superfecta has a built-in tester: **Admin → CID Superfecta → Debug** (or the
*Test/Debug* pane on a scheme). Enter a number, run it, and read the trace. The
NumbersOnline source emits lines prefixed `Numbers Online:` describing what it did
— e.g. *no API key configured*, *API returned HTTP 401*, *no name available*, or
*spam_score >= threshold*. For privacy and safety it **never** prints your API key
or the caller's number (debug output included).

Common cases:

- **No name ever appears** — confirm the source is *enabled* and ordered above your
  fallbacks in the scheme attached to the inbound route, and that the API key is
  set. Check the Debug pane for an HTTP `401` (bad key) or `402` (out of credit).
- **`HTTP 429` in debug** — you've hit the rate limit; the call still completes
  (fail-open). Raise your limit by topping up or contacting api@numbers.online.
- **A placeholder name shows through** — add it to **Ignore_Keywords**.

## "Tampered files" notice in Module Admin

FreePBX's *Module Admin* may show a **tampered / modified files** warning that lists
`source-NumbersOnline.module`. This is **expected** for any out-of-band Superfecta
source: the file isn't part of the signed upstream Superfecta package, so its
checksum isn't in FreePBX's manifest. It does not indicate a problem with your
system. (An upstream pull request to add Numbers Online to the FreePBX/superfecta
project is planned; once merged and released, the source ships signed and the
notice goes away.)

## Upgrade caveat

Updating the **CID Superfecta** module through Module Admin can **overwrite or
remove** custom files in its `sources/` directory, including this one. After any
Superfecta upgrade, re-download the file and re-run `fwconsole chown`:

```bash
cd /var/www/html/admin/modules/superfecta/sources/
curl -sSO https://numbers.online/integrations/freepbx/source-NumbersOnline.module
fwconsole chown
```

Your scheme configuration (API key, threshold, etc.) is stored separately and
survives the file being replaced.

---

For API keys, higher rate limits, or integration help: **api@numbers.online** ·
<https://numbers.online/docs>

## Keys & references

Keys are self-service at https://numbers.online/docs — shown once, stored only as a hash.
Machine-readable schema: https://numbers.online/api/spec · all guides: https://numbers.online/md/docs/integrations

- Next guide: [FreePBX & Asterisk caller ID lookup](https://numbers.online/md/docs/integrations/asterisk-freepbx)

---

Numbers Online — community-powered phone-number trust signals. Every figure on this
page is a supplementary, low-confidence signal — advisory, not a verdict on any number
or its owner.

- Canonical page (HTML): https://numbers.online/docs/integrations/freepbx-superfecta
- Report a call: https://numbers.online/report · Listed in error? Request removal: https://numbers.online/opt-out
- Machine guide to the phone-intelligence API: https://numbers.online/llms.txt · OpenAPI: https://numbers.online/api/spec