Turn Phone Numbers into Lead Signals

#telnyx #ai #devrel

Subtitle: Build a Python app that combines Telnyx Number Lookup with Telnyx AI Inference to qualify leads and recommend the best follow-up channel.

A lead form usually gives you just enough information to create a question.

Someone enters a name, an email address, maybe a phone number, and maybe a note about what they want. Now the app has to decide what happens next. Does this lead go to sales? Should the first touch be SMS or voice? Is the phone number even usable?

That is the workflow behind this example:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/number-lookup-lead-enrichment-python

It is a small Python Flask app that takes a phone number, enriches it with Telnyx Number Lookup, then uses Telnyx AI Inference to score the lead and recommend a follow-up channel.

The App Shape

The app exposes three routes:

POST /enrich for one phone number
POST /enrich/bulk for up to 50 phone numbers
GET /health for app health

It uses two Telnyx APIs:

GET /v2/number_lookup/{phone}
POST /v2/ai/chat/completions

The current default model is set in .env.example:

AI_MODEL=MiniMaxAI/MiniMax-M3-MXFP8

The pattern is simple: gather phone intelligence first, then use an inference model to turn that data into a lead-quality decision.

What Goes In

The request is intentionally small:

curl -X POST http://localhost:5000/enrich \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+12125550123"
  }'

The app looks up the number and extracts fields like carrier name, carrier type, caller name, line type, country, and validity.

Then it asks the model to return JSON like:

{
  "lead_quality": "hot",
  "reasoning": "Valid mobile number with usable carrier data",
  "is_mobile": true,
  "is_voip": false,
  "recommended_channel": "sms"
}

That response is much easier to build with than a paragraph. A product can route it, store it, show it in a CRM, or use it to kick off a workflow.

Why This Is Useful

Lead enrichment usually turns into a pile of small decisions:

Is this number valid?
Is it likely mobile?
Is it VoIP?
Is there carrier context?
Should this lead be contacted by SMS, voice, or email?
Should it go into a high-priority queue?

Number Lookup gives you the underlying phone intelligence. AI Inference lets you apply a lightweight reasoning layer over that data.

That is a nice AI app pattern because the model is not doing everything. It is operating on structured context from a real API.

The Small Detail That Matters

The app asks the model to return only JSON, with no prose and no markdown fences.

It still includes a helper to strip markdown fences and parse the JSON object. I like that because AI app code should be defensive. Prompts reduce variance, but validation is what keeps the output safe to use in an application.

The example keeps everything readable in one Flask app, which makes it easy to adapt.

What I Would Add Next

For production, I would add:

E.164 normalization before lookup
Persistent storage for enriched leads
Auth on the API endpoints
Retry handling for lookup and inference calls
CRM integration
Rate limiting for bulk enrichment
More explicit schemas for lead scoring
Human review for ambiguous high-value leads

The repo is also structured to be agent-readable. Your coding agent can inspect the README, API reference, guide, environment file, and app code, then help extend it. You can ask it to add CRM writes, tests, stricter validation, or a scheduled enrichment job.