Caller ID Lookup Sources Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Source Types
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Caller ID Lookup Sources?

Caller ID Lookup Sources define external data sources used to enrich incoming caller information. When a call arrives, the system queries these sources to look up the caller's name, company, or other details based on their phone number.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Caller ID Lookup Flow                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Incoming Call: +15058881234, WIRELESS CALLER                   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Lookup Sources (by priority)                      │   │
│  │                                                          │   │
│  │  Source 1: Internal Directory                            │   │
│  │    Type: internal                                        │   │
│  │    → Query public.contacts                               │   │
│  │    → Match: John Smith, ABC Company                      │   │
│  │                                                          │   │
│  │  Source 2: CRM API (fallback)                           │   │
│  │    Type: http                                            │   │
│  │    → GET https://crm.example.com/api/lookup?phone=...    │   │
│  │    → (skipped - Source 1 matched)                        │   │
│  │                                                          │   │
│  │  Source 3: OpenCNAM (last resort)                        │   │
│  │    Type: opencnam                                        │   │
│  │    → (skipped - Source 1 matched)                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Enriched Call:                                                 │
│  ├─ Caller ID Number: +15058881234                             │
│  └─ Caller ID Name: John Smith - ABC Company                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.caller_id_lookup_sources`	Lookup source configurations
`public.caller_id_lookup_cache`	Cached results (optional)

Key Files

File	Description
`admin/apps/web/src/modules/callerIdLookupSources/`	Frontend module
`admin/apps/web/src/i18n/en/callerIdLookupSources.json`	Translations

NOTE

Caller ID lookups are performed during inbound call routing using the configured sources.

---

2. Module Overview (Commercial/Business)

Business Value

Caller ID Lookup Sources enable caller identification:

Without Lookup Sources	With Lookup Sources
"WIRELESS CALLER"	Customer name from CRM
No context	Company information
Manual lookup	Automatic enrichment
Generic display	Personalized greeting

Use Cases

CRM Integration

- Look up customer name

- Display account status

Internal Directory

- Match against employee list

- Show department info

OpenCNAM/CNAM

- Public CNAM database

- Unknown caller identification

LDAP Directory

- Enterprise directory lookup

- Active Directory integration

Feature Highlights

Feature	Benefit
Multiple Sources	Fallback cascade
Source Types	HTTP, LDAP, Database, OpenCNAM
Caching	Reduce lookup time
Timeout Control	Prevent call delays
Priority Order	Control lookup sequence

---

3. Module Overview (End User/Administrator)

What Can You Do?

Configure lookup sources
Choose source types (HTTP, LDAP, Database, etc.)
Set authentication credentials
Configure timeouts
Enable caching
Prioritize sources

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating a Lookup Source                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: General                                                   │
│  ├─ Name: "CRM Customer Lookup"                                │
│  ├─ Source Type: HTTP API                                      │
│  ├─ URL: https://crm.example.com/api/caller?phone=${caller_id} │
│  ├─ HTTP Method: GET                                           │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Tab: Advanced Settings                                         │
│  ├─ Auth Username: api_user                                    │
│  ├─ Auth Password: ********                                    │
│  ├─ API Token: (optional)                                      │
│  ├─ Timeout: 3 seconds                                         │
│  └─ Cache TTL: 3600 seconds                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Cache Results: Enable caching to reduce repeated lookups and speed up call setup.

TIP

Low Timeouts: Keep timeouts under 3 seconds to avoid call delays.

CAUTION

Authentication: Secure your API credentials properly.

---

4. Configuration Fields Reference

General Fields

Field	Description	Example
Name	Source identifier	`CRM Lookup`
Source Type	Type of source	HTTP API
URL / Endpoint	Connection string	`https://api.example.com/lookup`
HTTP Method	GET or POST	GET
Enabled	Source active	On/Off

Authentication Fields

Field	Description
Auth Username	Username for auth
Auth Password	Password for auth
API Token	Token for OpenCNAM or token-based APIs

Performance Fields

Field	Description	Range
Timeout	Max wait time	1-30 seconds
Cache TTL	Cache duration	0-3600 seconds

---

5. Source Types

Internal

Look up in local database:

Setting	Description
Endpoint	Not required
Auth	Not required
Usage	Query internal contacts/directory

HTTP API

Call external REST API:

Setting	Description
URL	API endpoint with phone placeholder
Method	GET or POST
Auth	Basic auth or token
Response	JSON with caller name/info

Expected Response Format:

Json

{
  "cidname": "John Smith",
  "cidnumber": "+15058881234",
  "company": "ABC Company"
}

LDAP

Query LDAP/Active Directory:

Setting	Description
URL	`ldap://ldap.example.com:389`
Username	Bind DN
Password	Bind password
Usage	Search user by phone attribute

Database

Query external database:

Setting	Description
URL	Connection string (PostgreSQL, MySQL)
Username	Database user
Password	Database password
Usage	Execute SQL query

OpenCNAM

Public CNAM lookup service:

Setting	Description
Token	OpenCNAM API key
Timeout	Request timeout
Usage	CNAM database lookup

Custom

Lua script for custom logic:

Setting	Description
Script	Path to Lua script
Usage	Custom lookup logic

---

6. Common Scenarios & Examples

Scenario 1: CRM API Lookup

Source: "CRM Lookup"

Setting	Value
Type	HTTP API
URL	https://crm.example.com/api/caller?phone=[CIDNUM]
Method	GET
Timeout	3
Cache TTL	3600

Scenario 2: Internal Directory

Source: "Employee Directory"

Setting	Value
Type	Internal
Enabled	✓

Queries public.contacts for matching phone numbers.

Scenario 3: OpenCNAM Fallback

Source: "OpenCNAM"

Setting	Value
Type	OpenCNAM
Token	your-opencnam-api-key
Timeout	3
Cache TTL	86400

Scenario 4: LDAP/Active Directory

Source: "Corporate Directory"

Setting	Value
Type	LDAP
URL	ldap://ad.company.com:389
Username	CN=lookup,DC=company,DC=com
Password
Timeout	2

---

7. Limitations & Important Notes

Technical Notes

NOTE

Cache Saves Time: Caching reduces lookup latency on repeated calls.

WARNING

Timeout Impact: Long timeouts delay call setup. Keep under 3 seconds.

WARNING

External Dependencies: API outages can affect lookup availability.

Best Practices

Low Timeouts: 2-3 seconds maximum

Enable Caching: Reduce repeated lookups

Priority Order: Put fastest sources first

Fallback Sources: Configure backup sources

Monitor Failures: Track lookup success rates

Symptom	Possible Cause	Solution
No lookup results	Source disabled	Enable source
Timeout errors	Slow API	Reduce timeout, check API
Auth failures	Wrong credentials	Verify username/password
Empty name	No match found	Add fallback source
Slow calls	Long timeout	Reduce timeout value

---

8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
No lookup results Source disabled Enable source
Timeout errors Slow API Reduce timeout, check API
Auth failures Wrong credentials Verify username/password
Empty name No match found Add fallback source
Slow calls Long timeout Reduce timeout value
Diagnostic SQL

List lookup sources:

Sql
SELECT id, name, source_type, url, timeout, cache_ttl, enabled FROM public.caller_id_lookup_sources WHERE domain_id = [domain_id];

Check cache:

Sql
SELECT phone_number, caller_name, cached_at FROM public.caller_id_lookup_cache WHERE domain_id = [domain_id] ORDER BY cached_at DESC LIMIT 20;

FreeSWITCH Logs

Bash
# Check CID lookup operations grep "caller_id" /var/log/freeswitch/freeswitch.log grep "lookup" /var/log/freeswitch/freeswitch.log

---

9. Glossary

Term Definition
CNAM Caller Name - name associated with phone number
OpenCNAM Public CNAM lookup service
LDAP Lightweight Directory Access Protocol
Cache TTL Time-to-live for cached results
Lookup Source External system for caller info
Fallback* Backup source if primary fails
---
Lua Script Status ℹ️

Configuration Module

Component Status
Lookup Sources ℹ️ Configuration stored in public.caller_id_lookup_sources, used during inbound call processing
Caller ID lookups are performed during the inbound routing process using the configured sources. Results may be cached in public.caller_id_lookup_cache.
---

Documentation last updated: January 2026*

Term	Definition
CNAM	Caller Name - name associated with phone number
OpenCNAM	Public CNAM lookup service
LDAP	Lightweight Directory Access Protocol
Cache TTL	Time-to-live for cached results
Lookup Source	External system for caller info
Fallback*	Backup source if primary fails

Caller ID Lookup Sources Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Caller ID Lookup Sources?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

General Fields

Authentication Fields

Performance Fields

5. Source Types

Internal

HTTP API

LDAP

Database

OpenCNAM

Custom

6. Common Scenarios & Examples

Scenario 1: CRM API Lookup

Scenario 2: Internal Directory

Scenario 3: OpenCNAM Fallback

Scenario 4: LDAP/Active Directory

7. Limitations & Important Notes

Technical Notes

Best Practices

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

FreeSWITCH Logs

9. Glossary

Lua Script Status ℹ️

Configuration Module