["number-lookup"

How to Build a Caller Identity Pipeline with Node.js and the Telnyx Number Lookup API

When a customer calls your business, you have less than a second to decide how to handle them. Are they a known customer? A first-time caller? Or a potential fraud risk? Most systems punt on this question entirely -- the caller gets a generic IVR, punches through a menu tree, and eventually reaches an agent who asks them to verify their identity from scratch.

This walkthrough builds something different: a caller identity pipeline that runs a Number Lookup before the call is even answered, scores the caller's trust level, and passes the result to an AI Assistant that adapts its behaviour in real time. Trusted callers get greeted by name with full account access. Suspicious callers get a formal security flow. One codebase, one API key, four Telnyx products.

Full source: phone-identity-voice-agent-nodejs

What Does It Do

An inbound call arrives. The server immediately fires a Number Lookup request to the Telnyx API, pulling carrier data, CNAM (caller name), line type, porting history, and -- when available -- caller identity with a confidence score. A trust engine scores the result from 0 to 100, then classifies the caller as verified, standard, or suspicious.

That classification drives three things: the AI greeting, the security posture, and the account access level. All of this happens in the ~500 ms between when the phone rings and when the AI speaks its first word.

Inbound Call
    |
    v
+-------------------+     +------------------+     +------------------+
| Call Control      | --> | Number Lookup    | --> | Risk Engine      |
| (answer webhook)  |     | (carrier, CNAM,  |     | (score 0-100,    |
|                   |     |  identity, port) |     |  trust level)    |
+-------------------+     +------------------+     +------------------+
                                                          |
                                                          v
                                               +------------------+
                                               | AI Assistant     |
                                               | (dynamic vars:   |
                                               |  greeting, mode, |
                                               |  account access) |
                                               +------------------+

Telnyx Products Used

ProductRoleAPI Endpoint
Number LookupCarrier, CNAM, caller identity, porting statusGET /v2/number_lookup/{phone}
Call ControlAnswer, hang up, manage call flow via webhooksPOST /v2/calls/{id}/actions/{action}
AI AssistantsVoice agent with template variables filled per callPOST /v2/calls/{id}/actions/ai_assistant_start
Voice APIInbound call routing to your webhook endpointPortal: Call Control Application

One API key authenticates all four products.

Prerequisites

  • Node.js 22+
  • A Telnyx account with an API key
  • A Telnyx phone number with voice capability
  • A Call Control Application (webhook URL pointed at your server)
  • An AI Assistant configured with template variables

Step 1: Clone and Install

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/phone-identity-voice-agent-nodejs
npm install
cp .env.example .env

Step 2: Configure the Environment

Edit .env with your Telnyx credentials:

TELNYX_API_KEY=KEYxxxxxxxxxxxxxxxx
TELNYX_PHONE_NUMBER=+1xxxxxxxxxx
TELNYX_ASSISTANT_ID=assistant-xxxxxxxx
TELNYX_PUBLIC_KEY=xxxxx (optional, for webhook signature verification)
VariableSource
TELNYX_API_KEYPortal > API Keys
TELNYX_PHONE_NUMBERPortal > Numbers > Buy a Number
TELNYX_ASSISTANT_IDPortal > AI Assistants > Create
TELNYX_PUBLIC_KEYPortal > API Keys > Public Key

The AI Assistant needs three template variables in its instructions: {{caller_context}}, {{behavior_instructions}}, and {{greeting_text}}. These get filled dynamically on every call based on the Number Lookup result.

Step 3: The Number Lookup and Risk Engine

The core of the system lives in lookup.js. When a call arrives, the server calls the Number Lookup API with three data types:

const url = `${API}/number_lookup/${encodeURIComponent(phone)}?type=carrier&type=caller-name&type=caller-identity`;

The response includes carrier name and type, CNAM (registered caller name), caller identity with a confidence score, porting status, and postal address when available.

The risk engine starts at 100 and deducts points for red flags:

SignalDeductionExample
No identity data-40No caller identity record
Low confidence (< 60)-40Identity score below threshold
No caller name-15No CNAM registered
VoIP line type-20Non-fixed VoIP number
Ported number-10Number recently transferred
No address on file-10No postal address

The final score maps to a trust level: verified (70+), standard (40-69), or suspicious (below 40).

Step 4: Dynamic AI Behaviour

The trust level drives the AI Assistant's behaviour through dynamic variables:

Verified caller (score 70+): The AI greets the caller by first name -- "Hi, am I speaking with Sarah?" -- skips verification entirely, and grants full account access. The caller_context variable tells the AI who the caller is; the behavior_instructions variable tells it to be warm and conversational.

Standard caller (score 40-69): The AI gives a neutral greeting and asks the caller to verify through their banking app before accessing account details.

Suspicious caller (score below 40): The AI uses a formal greeting, requires full identity verification (name, date of birth, account number), and blocks sensitive operations like wire transfers and card freezes.

const aiBody = {
  assistant: {
    id: assistantId,
    dynamic_variables: {
      caller_context: vars.callerContext,
      behavior_instructions: vars.behaviorInstructions,
      greeting_text: vars.greetingText,
    },
  },
};

await fetch(`${API}/calls/${ccid}/actions/ai_assistant_start`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify(aiBody),
});

Step 5: Run and Test

node server.js

Expose your local server with ngrok:

ngrok http 3000

Update your Call Control Application webhook URL in the Telnyx portal to https://YOUR-NGROK.ngrok.app/webhooks/call-events, then call your Telnyx number. The dashboard at http://localhost:3000 shows the identity card, trust score, risk signals, and live transcription in real time.

You can also test the Number Lookup independently:

curl http://localhost:3000/lookup/+15125551234

Production Considerations

  • Webhook signature verification is built in -- set TELNYX_PUBLIC_KEY to enable Ed25519 signature checks on every incoming webhook.
  • 24-hour lookup cache prevents redundant API calls for repeat callers. The cache is in-memory with automatic eviction at 500 entries.
  • Edge deployment is supported -- the app includes Telnyx Edge Compute scripts for deploying to the carrier edge with sub-10ms webhook latency.
  • Graceful degradation -- if Number Lookup fails, the system falls back to standard verification mode rather than blocking the call.

The Same Pattern Drives More Than Banking

The identity-first call flow is a template. Swap the bank account data for:

  • Healthcare -- verify patient identity before sharing test results
  • Insurance -- pre-populate claim details for known policyholders
  • E-commerce -- skip order verification for recognised phone numbers
  • Property management -- route tenants directly to their building's maintenance team

The trust scoring logic and dynamic variable injection work the same way regardless of the vertical.

Related Examples

Frequently Asked Questions

What data does Number Lookup return?

Number Lookup returns carrier name and type (mobile, landline, VoIP), CNAM (registered caller name), caller identity with a confidence score (0-100), porting status and history, and postal address when available. The data comes from carrier-level sources, not web scraping.

How fast is the Number Lookup?

Typical response time is 200-800 ms depending on the carrier and data types requested. The demo runs the lookup in parallel with answering the call, so the AI has identity data ready before it speaks its first word.

Can I use this without an AI Assistant?

Yes. The Number Lookup and trust scoring work independently. You could route the call to different queues based on trust level, play different hold music, or display the identity card to a human agent -- the AI Assistant is just one way to act on the data.

How does the trust scoring work?

The engine starts at 100 and deducts points for risk signals: no identity data (-40), low confidence (-25 or -40), no CNAM (-15), VoIP line type (-20), ported number (-10), no address (-10). The final score maps to trusted (70+), standard (40-69), or suspicious (below 40). You can adjust the weights and thresholds for your use case.

Does this work with international numbers?

Number Lookup supports international numbers, but data coverage varies by country and carrier. Carrier and porting data are generally available worldwide; CNAM and caller identity are strongest for US numbers.

What happens if the Number Lookup fails?

The system falls back to standard verification mode -- the AI treats the caller as unverified and follows the full security flow. The call is never blocked by a lookup failure.

Can I deploy this to production?

The example includes Telnyx Edge Compute deployment scripts for carrier-edge hosting. For production, enable webhook signature verification, connect a real customer database, and adjust the trust scoring weights based on your fraud patterns. The in-memory lookup cache should be replaced with Redis or a similar store for multi-instance deployments.

Ready to build with low-latency voice AI?

Join developers building the future of real-time conversations