> ## 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/branded-calling/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/branded-calling/number-reputation/loa) and
  [Reputation Settings](/docs/branded-calling/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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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                 |
| `high`   | Number is likely flagged as spam by carriers |
| `null`   | Not enough data yet                          |

### Granular scores (0-100)

| Score              | Metric                           |
| :----------------- | :------------------------------- |
| `maturity_score`   | Maturity metric for the number   |
| `connection_score` | Connection metric for the number |
| `engagement_score` | Engagement metric for the number |
| `sentiment_score`  | Sentiment metric for the number  |

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

### Spam categories

If a number is flagged, `spam_category` is the category label assigned to it by the reputation feed. Treat it 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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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"
```