Number Reputation

Monitor the spam reputation of your outbound calling phone numbers with Telnyx Number Reputation.

Overview

Number Reputation lets you query the spam reputation of your outbound calling phone numbers. For each number you get a reputation snapshot with spam risk level, granular scores, and a category label when the number is flagged.

Number Reputation is a standalone monitoring product. It reports spam reputation and does not change how your calls are placed. It is governed by separate Terms of Service from Branded Calling.

Number Reputation is currently supported in the US only. Canadian numbers are not accepted.

How it works

1. Register your business as an Enterprise — an Enterprise can serve Number Reputation, Branded Calling, or both.
2. Accept the Number Reputation Terms of Service — a one-time step per account.
3. Render, sign, and upload a Letter of Authorization (LOA) to get a loa_document_id — see the LOA guide.
4. Enable Number Reputation with that loa_document_id (billable) — your details are submitted for automated vetting (takes minutes).
5. Wait for both approval gates — reputation status and loa_status must each be approved.
6. Associate phone numbers for monitoring (up to 100 per request, US numbers, E.164) — billable.
7. Query reputation scores — cached results are free, fresh (live) queries are billed.
8. Automatic monitoring re-checks your numbers on a configurable schedule.
9. Remediate flagged numbers — submit numbers for re-evaluation when spam risk is elevated.

Resource hierarchy

Enterprise (your organization, registered once — shared with Branded Calling)
├── Number Reputation Settings (per-enterprise monitoring configuration)
│   ├── LOA Document (Letter of Authorization)
│   ├── Auto-refresh Schedule (business_daily, daily, weekly, biweekly, monthly, never)
│   └── Reputation Phone Numbers
│       └── Phone Number (+1NPANXXXXXX)
│           └── Reputation Data (spam_risk, scores, spam_category, last_refreshed_at)
├── Remediation Requests (batch re-evaluation of flagged numbers)
│   └── Remediation Phone Numbers (up to 2,000 per request)
└── Terms of Service Agreement (Number Reputation)

• An Enterprise can serve Number Reputation, Branded Calling, or both — you don’t need to create a separate Enterprise for each product.
• Number Reputation Settings are per-enterprise: one LOA, one auto-refresh schedule, one activation lifecycle.
• Each Phone Number gets its own reputation data with spam risk levels and granular scores.
• Remediation Requests are batch submissions of flagged numbers for re-evaluation.

Key concepts

Term	Description
Enterprise	Your top-level business registration. Shared with Branded Calling. Required before enabling reputation monitoring.
Letter of Authorization (LOA)	A signed document authorizing Telnyx to manage your numbers’ reputation with call-analytics networks.
Reputation data	Per-number snapshot: spam_risk, spam_category, four granular scores, and last_refreshed_at.
Auto-refresh	Scheduled re-checking of your numbers’ reputation data. Configurable frequency.
Remediation	A request to call-analytics networks to re-evaluate a flagged number’s classification.
Terms of Service	Separate from Branded Calling. Must be accepted before enabling monitoring.

Reputation data

Each registered number returns a reputation_data object with the following fields:

Field	Values	Meaning
spam_risk	low / medium / high / null	Overall spam-risk classification from the call-analytics networks used by US carriers.
maturity_score	0-100 or null	How established the number is — based on call volume history over time. Available immediately after registration.
connection_score	0-100 or null	Whether recipients choose to answer calls from this number.
engagement_score	0-100 or null	Whether recipients stay on the call after answering.
sentiment_score	0-100 or null	Whether recipients complain about or block calls from this number.
spam_category	string or null	Category label assigned by the reputation feed when the number 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.

maturity_score is available immediately after registration because it uses pre-existing call traffic data. The other three scores start as null and populate after the number has sufficient call volume (minimum 4 hours, longer for low-volume numbers). Scores are updated hourly.

Known spam_category values include: Telemarketer, Survey, Debt Collector, Nonprofit, Political, and others. The set is not exhaustive and may grow over time.

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
Terms of Service	Must be accepted before enabling (separate from Branded Calling ToS)

Ecosystem

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. You interact only with the Telnyx API.

Next steps

• Quickstart guide — get from zero to your first reputation query
• Pricing — Number Reputation pricing details
• Letter of Authorization — render, sign, upload, and replace a rejected LOA
• Reputation Settings — vetting lifecycle, auto-refresh schedules, and configuration
• Phone Number Reputation — reputation data model, scores, and querying in depth
• Reputation Remediation — submit flagged numbers for re-evaluation