Documentation Index
Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
Use this file to discover all available pages before exploring further.
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 | How established the number is based on calling history over time. |
connection_score | 0–100 or null | How often recipients 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 want ongoing contact (based on blocking/reporting behavior). |
spam_category | string or null | Label assigned by analytics engines if the number is flagged (e.g. "Telemarketer", "Survey", "Debt Collector", "Nonprofit", "Political"). 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 powered by Hiya — AT&T’s primary spam analytics partner and the engine behind AT&T ActiveArmor. When you register numbers, Hiya registers them across all three major analytics engines (Hiya, First Orion, TNS).
How it works
- Register your business as an Enterprise
- Upload a signed LOA (Letter of Authorization) via the Documents API
- Enable Number Reputation — your details are sent to Hiya for automated vetting (takes minutes)
- Associate phone numbers for monitoring (up to 100 per request, US local, E.164)
- Query reputation scores — cached results are free, fresh (live) queries are billed
- Automatic monitoring re-checks your numbers on a configurable schedule
Constraints
| Constraint | Limit |
|---|---|
| Phone number format | E.164, US local 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 |