numbers.online caller names
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,
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.
curl -sS -X POST https://numbers.online/v1/account/signup \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","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.
Download the source onto the PBX and place it in Superfecta's sources/ directory:
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:
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.
Default), or create one.| 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.
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.
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.
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:
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 [email protected].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.)
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:
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: [email protected] · https://numbers.online/docs