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

Register your business as an Enterprise — an Enterprise can serve Number Reputation, Branded Calling, or both.
Accept the Number Reputation Terms of Service — a one-time step per account.
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 status and loa_status must each be approved.
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.
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

​Overview

​How it works

​Resource hierarchy

​Key concepts

​Reputation data

​Constraints

​Ecosystem

​Next steps

Overview

How it works

Resource hierarchy

Key concepts

Reputation data

Constraints

Ecosystem

Next steps