Skip to content

CID Lookup / Superfecta

Both modules enrich incoming caller ID by replacing or augmenting the CID Name (CNAM) using lookups against external sources. Use them when carriers don't provide CNAM and you want callers to show up as more than just a number.

  • CallerID Lookup (cidlookup) — simpler, supports internal sources (a phonebook), HTTP-based lookups, ENUM, and a few built-in providers.
  • CID Superfecta — commercial / enhanced version with multiple sources tried in sequence (Sangoma CNAM, OpenCNAM, Google, custom HTTP, etc.) — first hit wins.

This page covers Superfecta, which is more flexible. CID Lookup setup is similar but with fewer source options.

Before You Start

  • You have at least one lookup source ready: a phonebook in UnifiedBX, an external CNAM API key, or a custom HTTP URL that returns the name.
  • You know which inbound routes should use the lookup (usually all of them).

Steps

Configure a Superfecta scheme

  1. Go to Trunk Attributes → CID Superfecta.
  2. Click + Add Scheme.
  3. Scheme Name — e.g. Default Superfecta.
  4. Add Sources in priority order. Common sources:
    • Asterisk Phonebook — built-in UnifiedBX phonebook.
    • Sangoma Connect Lookup — if you have Sangoma CNAM credits.
    • OpenCNAM — paid CNAM API. Provide your account/secret in the source's settings.
    • CallerID.com / WhitePages / Telo — paid third-party CNAM.
    • Generic HTTP — call your own URL, returning a name; use [NUMBER] substitution.
    • Cache — sources can cache results to reduce repeat-lookup cost.
  5. For each source, configure its specific options (API key, URL, header).
  6. Cache duration — how long Superfecta caches a result. Common: 30-90 days.
  7. Click Submit.
  8. Click Apply Config.

Apply to inbound routes

  1. Go to Trunk Attributes → Inbound Routes.
  2. For each route (or just the catch-all), set CID Lookup Source to your Superfecta scheme.
  3. Click Submit → Apply Config.

Verify

Call from a number that's known in your phonebook. The display on the answering phone should show the looked-up name, not just the digits.

# Watch lookups in real time:
asterisk -rvvvv
# Look for "Superfecta scheme X looked up <number> -> <name>"

Common Issues

  • No lookup happens. The inbound route's CID Lookup Source is set to --None--. Pick the scheme.
  • Lookup is slow / rings late. A source is timing out (try Generic HTTP first to test). Reorder sources, put fast/free ones first.
  • Wrong name returned. A high-priority source has stale data. Reorder, or remove that source.
  • Costs balloon. Paid CNAM is per-lookup. Enable Cache and increase cache duration; restrict lookup to specific inbound routes (don't lookup on internal extensions).
  • Extension shows blank name on internal calls. That's not Superfecta — Superfecta only runs on inbound trunk calls. Internal CID is the extension's Display Name.