Overview
Number Reputation lets you query the spam reputation of your outbound calling phone numbers. For each number you get:| Field | Values | Meaning |
|---|---|---|
spam_risk | low / medium / high | Overall spam likelihood. high means the number is likely flagged as spam by carriers. |
maturity_score | 0-100 or null | Maturity metric for the number. |
connection_score | 0-100 or null | Connection metric for the number. |
engagement_score | 0-100 or null | Engagement metric for the number. |
sentiment_score | 0-100 or null | Sentiment metric for the number. |
spam_category | string or null | Category label assigned to the number if it is flagged. Treat as an opaque string - the set may grow over time. null means the number is not flagged. |
last_refreshed_at | ISO 8601 timestamp or null | When the reputation data was last updated. null if no check has been performed yet. |
null score means there isn’t enough data to make a determination.
You can also set up automatic re-checking on a configurable schedule (business_daily, daily, weekly, biweekly, monthly, or never).
Reputation data is sourced from the major call-analytics networks used by US carriers. When you register numbers, Telnyx registers them across that reputation feed on your behalf.
How it works
- Register your business as an Enterprise
- Render, sign, and upload a Letter of Authorization (LOA) to get a
loa_document_id- see the LOA guide - Enable Number Reputation with that
loa_document_id(billable) - your details are submitted for automated vetting (takes minutes) - Wait for both approval gates - reputation
statusandloa_statusmust each beapproved - Associate phone numbers for monitoring (up to 100 per request, US numbers, E.164) - billable
- Query reputation scores - cached results are free, fresh (live) queries are billed
- Automatic monitoring re-checks your numbers on a configurable schedule
Enabling reputation, adding numbers, and forcing a fresh (live) query are
billable actions. Rendering the LOA is not billable. See
Telnyx pricing for current pricing.
Constraints
| Constraint | Limit |
|---|---|
| Phone number format | E.164 (+1NPANXXXXXX), US numbers only |
| Numbers per request | 100 (atomic - all-or-nothing) |
| Score range | 0-100 (null = insufficient data) |
| Account access | Verified and enterprise-level accounts only |
| Approval gates | Both reputation status and loa_status must be approved before numbers can be added |