> ## 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.

# 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](https://telnyx.com/terms/reputation-services) from Branded Calling.

<Note>
  Number Reputation is currently supported in the **US only**. Canadian numbers
  are not accepted.
</Note>

## How it works

1. **Register your business** as an [Enterprise](/docs/branded-calling/enterprises/index) — 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](/docs/number-reputation/loa).
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.                                                                                      |

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

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](/docs/number-reputation/quickstart) — get from zero to your first reputation query
* [Pricing](/docs/number-reputation/pricing) — Number Reputation pricing details
* [Letter of Authorization](/docs/number-reputation/loa) — render, sign, upload, and replace a rejected LOA
* [Reputation Settings](/docs/number-reputation/settings) — vetting lifecycle, auto-refresh schedules, and configuration
* [Phone Number Reputation](/docs/number-reputation/phone-numbers) — reputation data model, scores, and querying in depth
* [Reputation Remediation](/docs/number-reputation/remediation) — submit flagged numbers for re-evaluation