FreePBX Caller ID Lookup Sources: route, source, cache and displayed-name evidence

Attach one lookup source to the inbound route that actually matched

Create and name the lookup source first, then select it on the intended inbound route. The release/17.0 module hooks the source into the matched DID and optional caller-number route before the final destination. Preserve the received DID, caller number, exact route match, selected source ID, route precedence and destination.

A saved source that is not assigned to the route cannot change the call. A source selected on a different DID or caller-specific route is not evidence for the affected call. Use the supported GUI and Apply Config path; do not edit generated dialplan to force a lookup.

Keep the source families and their contracts distinct

The reviewed module source contains separate paths for the internal directory, ENUM through Asterisk TXTCIDNAME(), Contact Manager, OpenCNAM, HTTP or HTTPS and MySQL. Record the selected family, number format sent, credentials owner, query or group, response contract, timeout and empty-result behavior. A response from one family does not validate another.

For HTTP and HTTPS, the generated path substitutes the caller number, existing name, language and unique ID into configured path or query fields. For MySQL it invokes the module AGI with the source ID and caller number. Treat those inputs and returned names as data from a trust boundary; allow only the intended host, database, query and result shape.

Preserve caller number, caller name and presentation separately

Asterisk documents CALLERID() as the channel interface for caller identity and gives the number, name, validity, character set and presentation their own fields. Retain the inbound number and presentation state before lookup, the source request, returned text and CALLERID(name) after lookup. Do not replace a withheld or unavailable number with a guessed identity.

Caller name is passed with call setup on common SIP paths but can be delayed on some channel technologies. The name displayed on a phone can also be reformatted, truncated or replaced downstream. A correct source result therefore does not by itself prove the final device display.

Treat the optional cache as persistent state with its own owner

For eligible non-internal sources, the reviewed module can check an AstDB key under the cidname family before querying the source and can write the resulting name back after lookup. A cache hit and a live source response are different evidence. Record the exact number key, stored value, creation context and whether the affected call used it.

Asterisk describes AstDB as persistent across reloads and restarts and exposes bounded database inspection and deletion commands. Clear or correct only the demonstrated key through the supported operational path. Do not erase the entire caller-name family to conceal a normalization mismatch or one stale value.

Protect external lookup credentials and call metadata

Use HTTPS for a remote service where the source supports it, a least-privilege account, destination allow-listing and a documented retention contract. Do not place passwords, tokens, complete phonebooks or unredacted caller data in shared traces. A TLS connection protects one network leg; it does not establish the lookup provider’s data accuracy, storage policy or authority over the number.

Bound response size, characters and latency, and preserve a safe no-result path. Do not pass caller-controlled text into a shell or broad query. A caller-name enrichment dependency must not become an unrestricted execution or database boundary, and a slow lookup must not be represented as a carrier or endpoint fault.

Prove generated state, live execution and endpoint display

After one change, confirm the saved source, inbound-route assignment, generated cidlookup subroutine and loaded dialplan. Make one authorized non-emergency call and correlate the inbound identity, selected route, cache decision, external or local source result, post-lookup CALLERID(name), destination channel and endpoint display. Test empty, failed and slow responses without exposing real credentials.

Preserve the prior route assignment, source definition and cache key for rollback. This guide is derived from first-party code and documentation; no PBX, lookup service, database, call, display or privacy control was laboratory-tested.

When the displayed caller name is missing or stale

Use the FreePBX caller-name diagnostic to separate route assignment, number normalization, live source response, AstDB cache, channel identity and endpoint display.

Do not equate caller-name enrichment with dynamic routing

The Dynamic Routes guide treats a lookup value used for branching as a separate decision input. A caller-name lookup result does not by itself authorize a privileged route or prove caller identity.