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

# Phone Number Reputation

> Associate phone numbers for monitoring, query spam scores and risk levels, and manage ongoing reputation tracking.

## Overview

Once your enterprise is [approved for Number Reputation](/docs/number-reputation/settings) — both reputation `status` **and** `loa_status` read `approved` — you can associate phone numbers for monitoring. Each number gets its own reputation data with spam risk levels and granular scores.

<Note>
  Both approval gates must be `approved` before numbers are accepted. If you
  haven't cleared them yet, start with the
  [LOA guide](/docs/number-reputation/loa) and
  [Reputation Settings](/docs/number-reputation/settings).
</Note>

## Associate phone numbers

Add phone numbers for reputation monitoring:

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"]
  }'
```

* Up to **100 numbers** per request
* **Atomic operation** — all numbers succeed or all fail
* Numbers must be **US** numbers in **E.164 format** (`+1NPANXXXXXX`) — non-US numbers are rejected
* Numbers must be in-service and belong to your Telnyx phone-number inventory

<Note>
  Adding numbers is a **billable action**. See
  [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.
</Note>

<Note>
  In the request body, phone numbers are JSON string values, so the leading `+`
  is written literally (`"+12025551234"`). In **path parameters** (the
  get/delete-by-number endpoints below) URL-encode the `+` as **`%2B`**.
</Note>

A freshly added number has `reputation_data: null` until Telnyx collects its first refresh. Query it (below) to trigger an immediate lookup.

## Query reputation

URL-encode the leading `+` of the phone number in the path as **`%2B`** —
e.g. `+12025551234` becomes `%2B12025551234`.

### Cached query (free)

Returns the most recent stored reputation data:

```bash theme={null}
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Fresh query (billed)

Fetches live data from the reputation feed:

```bash theme={null}
curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234?fresh=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

If no cached data exists for a number, a fresh query is automatically triggered regardless of the `fresh` parameter — so a brand-new number always returns live data on its first GET (and counts as a billed query). If the analytics networks don't have data for the number yet, `reputation_data` will still be `null`.

<Note>
  Live (fresh) queries are billable. See
  [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.
</Note>

## Reputation data model

Each number returns a `reputation_data` object. The object is **`null` until the
first refresh has been collected**, and every field inside it is nullable:

```json theme={null}
{
  "data": {
    "id": "16286ab3-038a-4a5c-9792-309026cf6b9e",
    "phone_number": "+12025551234",
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "reputation_data": {
      "spam_risk": "low",
      "spam_category": null,
      "maturity_score": 82,
      "connection_score": 75,
      "engagement_score": 68,
      "sentiment_score": 90,
      "last_refreshed_at": "2026-03-24T12:00:00Z"
    },
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z"
  }
}
```

### Spam risk

| Value    | Meaning                                                                                    |
| :------- | :----------------------------------------------------------------------------------------- |
| `low`    | Number has a clean reputation                                                              |
| `medium` | Some risk indicators present — the number may have been labeled as spam in the recent past |
| `high`   | Number is likely flagged as spam by carriers                                               |
| `null`   | Not enough data yet                                                                        |

### Granular scores (0-100)

| Score              | What it measures                                                                                                  |
| :----------------- | :---------------------------------------------------------------------------------------------------------------- |
| `maturity_score`   | How established the number is — based on call volume history over time. Available immediately after registration. |
| `connection_score` | Whether recipients choose to answer calls from this number.                                                       |
| `engagement_score` | Whether recipients stay on the call after answering.                                                              |
| `sentiment_score`  | Whether recipients complain about or block calls from this number.                                                |

A `null` score means there isn't enough data to make a determination.

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

### Spam categories

If a number is flagged, `spam_category` is the category label assigned to it by the reputation feed. Known values include:

| Category         | Description                                         |
| :--------------- | :-------------------------------------------------- |
| `Telemarketer`   | Number is flagged as a telemarketing caller         |
| `Survey`         | Number is flagged as a survey/polling caller        |
| `Debt Collector` | Number is flagged as a debt collection caller       |
| `Nonprofit`      | Number is flagged as a nonprofit/fundraising caller |
| `Political`      | Number is flagged as a political campaign caller    |

Treat the field as an opaque string — the set may grow over time. It is `null` when the number is not flagged.

## List all monitored numbers

```bash theme={null}
curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Supports pagination with `page[number]` and `page[size]` query parameters. Page
numbering is **1-based**; for this enterprise-scoped endpoint `page[size]`
**defaults to 10** and is capped at 250. You can also filter by phone number with
`filter[phone_number][contains]` (partial match) or `filter[phone_number][eq]`
(exact match).

```bash theme={null}
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers?page[number]=1&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Note>
  The [simplified](#simplified-endpoints) list endpoint (`/v2/reputation/numbers`)
  defaults to a `page[size]` of **20**, while this enterprise-scoped endpoint
  defaults to **10**. Pass `page[size]` explicitly if you depend on a specific
  page size.
</Note>

## Force a refresh

Refresh the stored reputation data for specific numbers immediately, in addition to the scheduled `check_frequency`:

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234"]
  }'
```

Up to 100 numbers per call. The response reports the per-number outcome:

```json theme={null}
{
  "data": {
    "results": [
      { "phone_number": "+12025551234", "success": true, "error": null }
    ],
    "total_requested": 1,
    "total_successful": 1,
    "total_failed": 0
  }
}
```

<Note>
  Forcing a refresh performs live reputation lookups, which are billable. See
  [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.
  Refreshes are subject to per-enterprise rate limits.
</Note>

## Remove a number from monitoring

```bash theme={null}
curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Simplified endpoints

If your account has only one enterprise, you can skip the `enterprise_id` path parameter:

| Method | Simplified path                         |
| :----- | :-------------------------------------- |
| GET    | `/v2/reputation/numbers`                |
| GET    | `/v2/reputation/numbers/{phone_number}` |
| DELETE | `/v2/reputation/numbers/{phone_number}` |

Remember to URL-encode the `+` as `%2B` in the `{phone_number}` path:

```bash theme={null}
# List all monitored numbers (simplified)
curl https://api.telnyx.com/v2/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get reputation for a specific number (simplified)
curl https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a specific number (simplified)
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"
```