Overview
The Telnyx Number Lookup API helps you know the details behind every phone number. You can use it to make each call more productive, reduce undelivered messages, and protect from spam and fraud.
Prerequisites
Before using Number Lookup, ensure you have:
A Telnyx account - Sign up at telnyx.com/sign-up
A positive account balance - Number Lookup requires funds in your account
API Key (for API access) - Generate from API Keys in Mission Control
Note: Number Lookup will not be available if your account balance is negative.
Using Number Lookup in the Portal
Sign in to the Telnyx portal
Navigate to Real-Time Communications > Identity > Number Lookup.
Enter the phone number and select a Lookup Type:
None: Basic info (LRN only).
Carrier: Adds carrier details.
Caller Name: Adds CNAM.
Both: Returns all available data.
Click Lookup Number.
Video Walk-through for Number Lookup
Lookup Types and Pricing
Service | Cost |
Local Routing Number (LRN) | $0.0015 per query |
MCC/MNC (Carrier Codes) | $0.0025 per query (mobile only) |
CNAM (Caller ID Name) | $0.003 per query |
Inbound CNAM | $0.40 per number/month |
Outbound CNAM Listing | Free |
Examples
Landline with Carrier + Caller Name: $0.0015 + $0.003 = $0.0045
Mobile with Carrier + Caller Name: $0.0015 + $0.0025 + $0.003 = $0.007
View your rates at Telco Pricing. For volume discounts, contact sales.
API Access & Documentation
Quickstart Guide: Number Lookup Quickstart
Full Reference: Number Lookup API Reference
Reviewing Your Usage
Invoice: Charges appear at the start of each month
Usage Reports: Go to Reporting > Usage Reports and select a date range
Note: Reports are not real-time. Today's lookups appear tomorrow.
Important Notes
LRN Data Access
To view full LRN data, go to Account Settings > Profile and enable Permitted NPAC User (allow ~15 mins to apply).
Limitations
Access: Restricted to Organization Owners only (no sub-accounts).
US Toll-Free: Resporg ID is not returned.
Troubleshooting
Error | Cause | Solution |
Number Lookup unavailable | Zero/negative balance | |
LRN data incomplete | NPAC User not enabled | Enable in Account Settings |
401 Unauthorized | Invalid API key | Verify key and header format |
Sub-user access denied | Owner-only feature | Use org owner credentials |