---
title: "Caller ID Lookup Sources Module Documentation"
description: "Documentation for Caller ID Lookup"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [User Roles & Key Capabilities](#-user-roles--key-capabilities)
7. [Configuration Fields Reference](#4-configuration-fields-reference)
8. [Source Types](#5-source-types)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
11. [Limitations & Important Notes](#8-limitations--important-notes)
12. [Troubleshooting Tips](#9-troubleshooting-tips)
13. [Glossary](#10-glossary)
---

## Navigation & Access

To access the Caller ID Lookup Sources module:
1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Incoming Call Tools**, click **Caller ID Lookup Sources** (`/pbx/incoming-tools/callerid-lookup-sources`).

---

## Screenshots & Visual Interface

### Caller ID Lookup Sources Overview
Displays all configured external and internal lookup connectors, source types (HTTP, OpenCNAM, Database), cache TTL, and status.
![Caller ID Lookup Sources List View](/screenshots/pbx/incoming-tools/callerid-lookup-list.png)

### Caller ID Lookup Source Configuration Form
Configures API endpoints, authentication credentials, request method, timeout thresholds, and response JSON path mapping.
![Caller ID Lookup Source Configuration Form](/screenshots/pbx/incoming-tools/callerid-lookup-form.png)

---

## 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

```
┌─────────────────────────────────────────────────────────────────┐
│              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                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **CRM Integration**
   - Look up customer name
   - Display account status

2. **Internal Directory**
   - Match against employee list
   - Show department info

3. **OpenCNAM/CNAM**
   - Public CNAM database
   - Unknown caller identification

4. **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

```
┌─────────────────────────────────────────────────────────────────┐
│              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.

---

## 🎯 User Roles & Key Capabilities

| Role | Permissions & Responsibilities | Key Capabilities |
|---|---|---|
| **Tenant Administrator** | Full write access to Caller ID lookup sources | Create, edit, and configure HTTP/OpenCNAM/LDAP/Database CID lookup connectors, adjust timeouts, caching, and token credentials |
| **Call Center Supervisor / Operator** | Read-only access | View configured lookup sources, inspect resolution sources for incoming CRM caller ID enrichment |
| **Platform / System Engineer** | Telephony and FreeSWITCH engine access | Monitor FreeSWITCH Lua CID lookup performance, inspect cache hits/misses, troubleshoot API latencies |

---

## 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. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Caller ID Lookup Sources (CNAM & CRM Lookup)**, allowing AI Copilots, CRM automation engines, and telephony administrators to inspect external data connector endpoints, configure HTTP/OpenCNAM lookups, tune cache TTL thresholds, and provision or adjust caller enrichment connectors programmatically with domain-level isolation.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_cid_lookup_sources` | Lists all Caller ID Lookup Sources defined in the domain, displaying connector type, target URL, timeout, and enabled state. | `search` (optional string) |
| `get_cid_lookup_source_status` | Retrieves full configuration, HTTP headers, authentication tokens, timeout thresholds, and response JSON mapping of a specific lookup source. | `name` (required string) |
| `create_cid_lookup_source` | Provisions a new external caller enrichment connector querying HTTP REST APIs, OpenCNAM, or internal databases. Enforces source name uniqueness per domain. | `name`, `sourceType` (`http`, `opencnam`, `internal`, `database`, `ldap`, `custom`), `url`, `httpMethod` (`GET`, `POST`), `token`, `timeout`, `cacheTtl` |
| `update_cid_lookup_source` | Updates query endpoint URLs, API tokens, lookup timeouts, or enabled status. | `name`, `newName`, `url`, `timeout`, `enabled` |
| `delete_cid_lookup_source` | Removes a Caller ID Lookup Source connector from the PBX domain. | `name` (required string) |

### Protection Guards & Integrity
- **Name Uniqueness**: Every lookup source name must be unique within its tenant domain.
- **Latency Protection**: MCP tools enforce timeout thresholds (typically 2-3 seconds) to ensure that slow third-party CRM APIs do not degrade inbound call setup times.
- **Dynamic In-Memory Caching**: Resolved caller names are automatically persisted in `public.caller_id_lookup_cache`, eliminating redundant external API queries for recurrent callers.

### AI Agent Operational Examples

#### Querying Active Lookup Source Configuration
```json
{
  "tool": "get_cid_lookup_source_status",
  "arguments": {
    "name": "HubSpot CRM Caller Lookup"
  }
}
```

#### Provisioning an OpenCNAM Enrichment Connector
```json
{
  "tool": "create_cid_lookup_source",
  "arguments": {
    "name": "OpenCNAM Production",
    "sourceType": "opencnam",
    "url": "https://api.opencnam.com/v3/phone/{number}?format=text",
    "timeout": 2,
    "cacheTtl": 86400
  }
}
```

### Recommended Natural Language Prompts
- *"List all Caller ID lookup connectors configured in this domain."*
- *"Create an HTTP Caller ID lookup source named 'Salesforce CRM' pointing to our webhook endpoint."*
- *"Reduce the timeout on 'OpenCNAM' to 2 seconds to speed up call connection times."*
- *"Check if the OpenCNAM lookup source is currently enabled."*

---

## 8. 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

1. **Low Timeouts**: 2-3 seconds maximum
2. **Enable Caching**: Reduce repeated lookups
3. **Priority Order**: Put fastest sources first
4. **Fallback Sources**: Configure backup sources
5. **Monitor Failures**: Track lookup success rates

---

## 9. 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;
```

### Telephony Server Logs

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

---

## 10. 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 |

---

*Documentation last updated: January 2026*