# Telnyx Numbers: Number Reputation — Full Documentation
> Complete page content for Number Reputation (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com).
> This file: https://developers.telnyx.com/docs/development/llms/numbers-number-reputation-llms-full-txt · Root index: https://developers.telnyx.com/llms.txt

## Guides

### Overview

> Source: https://developers.telnyx.com/docs/number-reputation/overview.md

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

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

## How it works

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

  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) |
| Numbers hosted with another provider | US local only, after a one-time [ownership verification](/docs/number-reputation/non-telnyx-numbers) |
| 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
- [Numbers Hosted With Another Provider](/docs/number-reputation/non-telnyx-numbers) — monitor numbers you own outside Telnyx
- [Reputation Remediation](/docs/number-reputation/remediation) — submit flagged numbers for re-evaluation

---

### Quickstart

> Source: https://developers.telnyx.com/docs/number-reputation/quickstart.md

This guide walks you through enabling Number Reputation and querying your first spam score. You'll need a [verified or enterprise-level Telnyx account](/docs/account-setup/levels-and-capabilities) and an API key.

There are **two separate approval gates** you must clear before you can add phone numbers — don't confuse them:

1. Reputation **`status`** must be `approved` — the activation lifecycle for the enterprise.
2. **`loa_status`** must be `approved` — Telnyx reviews your signed Letter of Authorization.

Both are tracked independently, and **both must read `approved`** before `POST .../reputation/numbers` will accept numbers.

## Prerequisites

- A Telnyx account with **verified** or **enterprise** level access
- An [API key](https://portal.telnyx.com/#/app/api-keys)
- At least one US phone number on your account, in E.164 format
- A signed Letter of Authorization (LOA) — you render this from Telnyx in Step 3

## Step 1: Accept the Number Reputation Terms of Service

Read the full terms at [telnyx.com/terms/reputation-services](https://telnyx.com/terms/reputation-services).

```bash
curl -X POST https://api.telnyx.com/v2/terms_of_service/number_reputation/agree \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This is a one-time step per account. If you skip it, **Step 5 (enable) returns `403`**.

  To check whether you've already agreed, call `GET /v2/terms_of_service/status?product_type=number_reputation`.
  That endpoint **defaults to `branded_calling`**, so you must pass
  `product_type=number_reputation` to read the Number Reputation status.

## Step 2: Create an enterprise

If you don't already have an enterprise, create one. An Enterprise can serve Number Reputation, Branded Calling, or both — you don't need a separate one. See the [Enterprises overview](/docs/branded-calling/enterprises) for the full field reference.

```bash
curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Plumbing LLC",
    "doing_business_as": "Acme Plumbing",
    "organization_type": "commercial",
    "organization_legal_type": "llc",
    "country_code": "US",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://acmeplumbing.example.com",
    "fein": "12-3456789",
    "industry": "technology",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Sam",
      "last_name": "Owner",
      "email": "sam@acmeplumbing.example.com",
      "job_title": "Compliance Lead",
      "phone_number": "+13125550000"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Bill",
      "email": "billing@acmeplumbing.example.com",
      "phone_number": "+13125550001"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    }
  }'
```

Save the `id` from the response — this is your `enterprise_id`.

## Step 3: Render the Letter of Authorization (LOA)

Telnyx renders a pre-filled LOA **PDF** from your enterprise record. You do **not**
upload your own template — you render the Telnyx one, sign it, and upload the
signed copy back.

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{}'
```

The response body is the **PDF itself** (`application/pdf`); `-o loa.pdf` saves it to disk. Rendering the LOA is **not billable**.

See the [LOA guide](/docs/number-reputation/loa) for the optional `agent` (reseller) and `signature` body fields, and the full approval/replacement flow.

## Step 4: Sign the LOA and upload it to the Documents API

Sign `loa.pdf` (e-signature or wet signature), then upload the signed copy to the [Telnyx Documents API](/api-reference/documents/upload-a-document):

```bash
curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"
```

The response contains the document id:

```json
{
  "data": {
    "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
  }
}
```

Save `data.id` — you'll pass it as `loa_document_id` in the next step.

## Step 5: Enable Number Reputation

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'
```

`check_frequency` is optional and defaults to `business_daily`.

  Enabling reputation is a **billable action**. See
  [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.

## Step 6: Wait for both approval gates

Your enterprise details are submitted for automated vetting and Telnyx reviews
your signed LOA. Poll the reputation settings until **both** `status` and
`loa_status` read `approved`:

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

```json
{
  "data": {
    "status": "approved",
    "loa_status": "approved"
  }
}
```

| Field | Gate |
| :--- | :--- |
| `status` | Activation lifecycle: `pending` → `approved` (or `rejected` — see `rejection_reasons`). |
| `loa_status` | LOA review: `pending` → `approved` (or `rejected` — replace the LOA, see the [LOA guide](/docs/number-reputation/loa)). |

You **cannot add numbers** until both are `approved`.

## Step 7: Associate phone numbers

Once both gates are `approved`, add phone numbers for monitoring:

```bash
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. This is an atomic operation — all numbers succeed
or all fail. Numbers must be **US** numbers in E.164 format (`+1NPANXXXXXX`),
in-service, and belong to your Telnyx phone-number inventory. Non-US numbers are
rejected.

To monitor numbers you own that are hosted with another provider, see
[Numbers Hosted With Another Provider](/docs/number-reputation/non-telnyx-numbers).

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

  A freshly added number has `reputation_data: null` until Telnyx collects its
  first refresh. Querying it (Step 8) triggers an immediate lookup. Because the
  number has no cached data yet, that first query performs a **live (billed)**
  lookup even from the "Cached" endpoint; cached reads are free only once data exists.

## Step 8: Query reputation

URL-encode the leading `+` of the phone number in the path as **`%2B`**.

### Cached (free, once data exists)

The **first** query on a number with no cached reputation data triggers a live, **billed** lookup regardless of this endpoint; only subsequent reads are free.

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

### Fresh — live query (billed)

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

The response includes:

```json
{
  "data": {
    "id": "8a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62",
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "phone_number": "+12025551234",
    "reputation_data": {
      "spam_risk": "low",
      "spam_category": null,
      "maturity_score": 82,
      "connection_score": 75,
      "engagement_score": 68,
      "sentiment_score": 90,
      "last_refreshed_at": "2026-04-26T18:09:24.785211Z"
    },
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z"
  }
}
```

Every field in `reputation_data` is nullable, and the whole object is `null`
until the first refresh has been collected.

## Step 9: Manage ongoing monitoring

### Change auto-refresh frequency

```bash
curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/frequency \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_frequency": "daily"}'
```

The enterprise's reputation `status` must be `approved`; a request made while it
is still `pending` returns `400 Bad Request`.

### Remove a number from monitoring

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

### Disable Number Reputation entirely

```bash
curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Simplified endpoints

If your account has only one enterprise, you can use simplified endpoints without the `enterprise_id`:

```bash
# List all monitored numbers
curl https://api.telnyx.com/v2/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

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

# Remove a number from monitoring (URL-encode the leading + as %2B in the path)
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Portal setup

You can also set up Number Reputation from the [Telnyx Portal](https://portal.telnyx.com) — the full workflow (accept ToS, create enterprise, render LOA, enable monitoring, add numbers, query scores) is available in the UI. The API and Portal are fully interchangeable.

## Next steps

- Learn about [Reputation Settings](/docs/number-reputation/settings) — vetting lifecycle, auto-refresh schedules, and configuration
- Read the [LOA guide](/docs/number-reputation/loa) — render, sign, upload, and replace a rejected LOA
- Explore [Phone Number Reputation](/docs/number-reputation/phone-numbers) — reputation data model, scores, and querying in depth
- Submit flagged numbers for [Reputation Remediation](/docs/number-reputation/remediation)

---

### Pricing

> Source: https://developers.telnyx.com/docs/number-reputation/pricing.md

## Pricing

Number Reputation pricing has three components:

| Component | Cost | Description |
| :--- | :--- | :--- |
| **Reputation monitoring** | $100/month per Enterprise | Recurring monthly fee to enable reputation monitoring on an enterprise. |
| **Reputation check** | $0.10 per check | Charged per reputation query. Cached reads are free; fresh (live) queries and auto-refreshes are billed. |
| **Remediation check** | $1.00 per check | Charged per number submitted for reputation remediation (re-evaluation). |

  Rendering the LOA is **not billable**. You only pay once you enable reputation
  monitoring and add numbers.

For the full pricing details, see the [Telnyx Numbers pricing page](https://telnyx.com/pricing/numbers).

## How billing works

| Action | Billed? |
| :--- | :--- |
| Render LOA PDF | No |
| Enable reputation monitoring | Yes ($100 MRC) |
| Add phone numbers | Yes ($0.10 per number per check) |
| Cached reputation query | No (free once data exists) |
| Fresh reputation query (`?fresh=true`) | Yes ($0.10 per check) |
| Forced refresh | Yes ($0.10 per check) |
| Auto-refresh (scheduled) | Yes ($0.10 per check per number) |
| Submit remediation request | Yes ($1.00 per number) |

Enterprise registration is free. An Enterprise can serve Number Reputation, Branded Calling, or both.

---

### Letter of Authorization

> Source: https://developers.telnyx.com/docs/number-reputation/loa.md

## Overview

Before Telnyx can register your phone numbers with the major call-analytics networks used by US carriers, you must provide a signed **Letter of Authorization (LOA)**. The LOA authorizes Telnyx to manage your numbers' reputation on your behalf.

The LOA is the **#1 thing customers get stuck on**, so follow these steps in order. There are two separate approval gates you must clear before you can add phone numbers:

1. Reputation `status` must be `approved` (the activation lifecycle).
2. `loa_status` must be `approved` (Telnyx reviews the signed LOA).

Both must be `approved`. They are tracked independently.

    Telnyx renders a pre-filled LOA from your enterprise record. The enterprise
    identity, address, and authorized-representative contact are read from the
    enterprise you created — you do **not** pass them again here.

    ```bash
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{}'
    ```

    The response body is the **PDF itself** (`application/pdf`). The `-o loa.pdf`
    flag saves it to disk.

      Rendering the LOA is **not billable**. You only pay once you enable
      reputation and add numbers.

    **Optional body fields** (both optional):

    | Field | Description |
    | :--- | :--- |
    | `agent` | A third-party reseller / partner block, used only when a partner manages the enterprise's numbers. Omit when the enterprise works directly with Telnyx. |
    | `signature` | Embeds a signature image in the rendered PDF. When omitted, the PDF is returned **unsigned** for you to sign manually. |

    To render with the agent (reseller) block:

    ```bash
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{
        "agent": {
          "legal_name": "Reseller LLC",
          "dba": "Reseller",
          "street_address": "500 Market St",
          "extended_address": "Suite 200",
          "city": "San Francisco",
          "administrative_area": "CA",
          "postal_code": "94105",
          "country": "US",
          "contact_name": "Pat Partner",
          "contact_title": "Account Manager",
          "contact_email": "pat@reseller.com",
          "contact_phone": "+13125550000"
        }
      }'
    ```

    To embed a signature at render time instead of signing the PDF by hand:

    ```bash
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{
        "signature": {
          "image_base64": "BASE64_ENCODED_SIGNATURE_IMAGE",
          "signer_name": "Jane Smith"
        }
      }'
    ```

    If you did not embed a `signature` at render time, open `loa.pdf` and sign it
    (e-signature or wet signature). Save the signed copy.

    Upload the signed PDF to the [Telnyx Documents API](/api-reference/documents/upload-a-document). The
    Documents API returns a document `id` — that value is your `loa_document_id`.

    ```bash
    curl -X POST https://api.telnyx.com/v2/documents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@loa.pdf"
    ```

    The response contains the document id:

    ```json
    {
      "data": {
        "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
      }
    }
    ```

    Save `data.id` — you'll pass it as `loa_document_id` in the next step.

    Enable Number Reputation, passing the document id and a refresh frequency.

    ```bash
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "check_frequency": "business_daily"
      }'
    ```

      Enabling reputation is a **billable action**. See
      [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.

    Telnyx reviews your uploaded LOA. Track `loa_status` on the reputation
    settings:

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

    ```json
    {
      "data": {
        "status": "approved",
        "loa_status": "pending"
      }
    }
    ```

    `loa_status` moves `pending` → `approved` (or `rejected`). You **cannot add
    phone numbers** until `loa_status` is `approved` **and** reputation `status`
    is `approved`.

## LOA approval gate

| `loa_status` | Meaning |
| :--- | :--- |
| `pending` | Telnyx is reviewing the uploaded LOA. Numbers cannot be added yet. |
| `approved` | LOA accepted. Combined with reputation `status` = `approved`, you can add numbers. |
| `rejected` | LOA was not accepted. Replace it (see below) to retry. |

  Reputation `status` and `loa_status` are **two separate gates**. Both must read
  `approved` before `POST .../reputation/numbers` will accept numbers.

## Replace a pending or rejected LOA

If your LOA is `rejected` — or it is still `pending` and you need to upload a
corrected document — render a fresh PDF, sign and upload it to the Documents API
to get a new `loa_document_id`, then point your reputation settings at it:

```bash
curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "NEW_DOCUMENT_ID"
  }'
```

Replacing the LOA **resets `loa_status` back to `pending`**. The new document
must be approved again before more numbers can be added. This is the recovery
path for a rejected LOA.

  You can only replace the LOA while `loa_status` is `pending` or `rejected`.
  Once `loa_status` is `approved`, the document is locked in and this `PATCH`
  returns **`400 Bad Request`** ("The authorization document cannot be changed
  after it has been approved."). To start over with a different LOA after
  approval, [disable Number Reputation](/docs/number-reputation/settings#disable-number-reputation)
  and re-enable it with the new document.

## Next steps

- [Enable and configure reputation](/docs/number-reputation/settings)
- [Associate phone numbers](/docs/number-reputation/phone-numbers) once both gates are `approved`

---

### Reputation Settings

> Source: https://developers.telnyx.com/docs/number-reputation/settings.md

## Overview

Number Reputation Settings control the monitoring lifecycle for your enterprise. You enable reputation monitoring, configure how often numbers are checked, and manage the vetting status.

## Prerequisites

Before enabling Number Reputation, you need:

1. An [Enterprise](/docs/branded-calling/enterprises) registered on your account — an Enterprise can serve Number Reputation, Branded Calling, or both.
2. A signed **Letter of Authorization (LOA)** rendered, signed, and uploaded to the
   Documents API to obtain a `loa_document_id` — follow the
   [LOA guide](/docs/number-reputation/loa). The LOA authorizes
   Telnyx to register your numbers with the major call-analytics networks used by
   US carriers.
3. Agreement to the Number Reputation [Terms of Service](#terms-of-service).

## Enable Number Reputation

Submit your LOA document ID to enable reputation monitoring:

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'
```

`check_frequency` is optional and defaults to `business_daily`.

Your enterprise details are submitted for automated vetting. This typically takes **minutes**.

  Enabling reputation is a **billable action**. See
  [Number Reputation pricing](/docs/number-reputation/pricing) for current pricing.

  Enabling returns **`403`** if you have not agreed to the Number Reputation
  Terms of Service. See [Terms of Service](#terms-of-service) below.

## Two approval gates

Two statuses must each read `approved` before you can add phone numbers — they are tracked independently:

| Status | Meaning |
| :--- | :--- |
| `status` | Activation lifecycle of the enterprise's reputation. `pending` → `approved` / `rejected`. |
| `loa_status` | Telnyx's review of the signed LOA. `pending` → `approved` / `rejected`. |

  `status` and `loa_status` are **two separate gates**. Both must be `approved`
  before `POST .../reputation/numbers` will accept numbers. A `rejected`
  `loa_status` is recoverable — replace the LOA per the
  [LOA guide](/docs/number-reputation/loa).

## Vetting lifecycle

```
pending ──► approved    (activation approved)
pending ──► rejected    (check rejection_reasons in the response)
approved ──► (removed)   (reputation disabled via DELETE)
```

Once you disable reputation, the settings are removed: a subsequent
`GET .../reputation` returns **`404 Not Found`** rather than a readable status.

Check your current status:

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

The response includes:

| Field | Description |
| :--- | :--- |
| `status` | Activation lifecycle: `pending`, `approved`, or `rejected`. (After you disable reputation the settings are removed and `GET` returns `404` instead of a status.) |
| `loa_status` | LOA review gate: `pending`, `approved`, or `rejected`. |
| `check_frequency` | Current auto-refresh schedule. |
| `loa_document_id` | Your uploaded LOA reference (nullable). |
| `rejection_reasons` | Array of reasons, populated when `status` is `rejected` (otherwise `null`). |
| `created_at` / `updated_at` | Timestamps. |

## Auto-refresh schedules

Telnyx automatically runs fresh reputation queries on all your registered numbers based on the configured `check_frequency`:

| Frequency | Schedule |
| :--- | :--- |
| `business_daily` | Mon-Fri **(default)** |
| `daily` | Every day including weekends |
| `weekly` | Once per week |
| `biweekly` | Every 2 weeks |
| `monthly` | Once per month |
| `never` | Manual only — use `?fresh=true` or a forced refresh |

### Change the schedule

```bash
curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/frequency \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"check_frequency": "daily"}'
```

  The enterprise's reputation `status` must be `approved`. A frequency change
  requested while `status` is still `pending` is rejected with **`400 Bad
  Request`**.

Choose a frequency that balances data freshness with cost. Each auto-refresh counts as a billed query per number — see [Number Reputation pricing](/docs/number-reputation/pricing).

## Disable Number Reputation

To stop monitoring entirely and remove the enterprise from reputation tracking:

```bash
curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This de-registers your numbers from the reputation feed and removes the
reputation settings. A subsequent `GET .../reputation` returns `404 Not Found`;
to monitor again you must re-enable with a fresh LOA.

## Terms of Service

You must accept the Number Reputation Terms of Service ([read the full terms](https://telnyx.com/terms/reputation-services)) before enabling monitoring:

```bash
curl -X POST https://api.telnyx.com/v2/terms_of_service/number_reputation/agree \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This is a one-time step per account.

  To check ToS status, call
  `GET /v2/terms_of_service/status?product_type=number_reputation`. This endpoint
  **defaults to `branded_calling`**, so you must pass `product_type=number_reputation`.
  Likewise, `GET /v2/terms_of_service/agreements` also **defaults to
  `branded_calling`** — pass `?product_type=number_reputation` to scope the
  list to Number Reputation.

---

### Phone Numbers

> Source: https://developers.telnyx.com/docs/number-reputation/phone-numbers.md

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

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

## Associate phone numbers

Add phone numbers for reputation monitoring:

```bash
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 in your Telnyx phone-number inventory, or be numbers you own with another provider once your enterprise's [ownership verification](/docs/number-reputation/non-telnyx-numbers) is approved

Every number is returned with a `source` (`telnyx` or `external`) and an `ownership_status`. Both list endpoints accept `filter[source]` and `filter[ownership_status]`.

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

  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`**.

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

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

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

  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.

### 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
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
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers?page[number]=1&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

  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.

## Force a refresh

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

```bash
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
{
  "data": {
    "results": [
      { "phone_number": "+12025551234", "success": true, "error": null }
    ],
    "total_requested": 1,
    "total_successful": 1,
    "total_failed": 0
  }
}
```

  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.

## Remove a number from monitoring

```bash
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
# 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"
```

---

### Non-Telnyx Numbers

> Source: https://developers.telnyx.com/docs/number-reputation/non-telnyx-numbers.md

## Overview

Number Reputation can monitor phone numbers that you own but that are hosted with another provider. They get the same reputation data, refreshes, and [remediation](/docs/number-reputation/remediation) as numbers in your Telnyx inventory.

Because Telnyx cannot see when such a number leaves your control, two things are different:

- You prove ownership once per enterprise before adding any.
- Telnyx checks every day that each number is still with the carrier it was on when you added it, and asks you to confirm ownership if that changes.

| | Telnyx numbers | Numbers hosted elsewhere |
| :--- | :--- | :--- |
| `source` | `telnyx` | `external` |
| Requirement to add | In-service in your inventory | Approved ownership verification |
| Number types | US local and toll-free | US local only |
| Ownership tracking | Automatic through your inventory | Daily carrier check, with confirmation when the carrier changes |

  You must own, or be licensed to use, every number you register, and tell
  Telnyx when that stops being true. See the Reputation Services Terms of
  Service and your Letter of Authorization.

## Step 1: Verify ownership (once per enterprise)

Upload one or more documents that show the enterprise owns its numbers, such as a carrier invoice or account statement, to the [Documents API](/api-reference/documents/upload-a-document). Then submit them for review:

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/external_verification \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["2a7e8337-e803-4057-a4ae-26c40eb0bc6c"],
    "phone_numbers": ["+13125550142"]
  }'
```

`phone_numbers` is optional: it tells the reviewer which numbers the documents cover. You can still add numbers that are not listed; each one is checked on its own.

```json
{
  "data": {
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "status": "pending",
    "document_ids": ["2a7e8337-e803-4057-a4ae-26c40eb0bc6c"],
    "phone_numbers": ["+13125550142"],
    "rejection_reason": null,
    "submitted_at": "2026-10-05T09:12:44Z",
    "reviewed_at": null
  }
}
```

Check the review at any time:

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

| `status` | Meaning |
| :--- | :--- |
| `pending` | Awaiting review. You can submit again to replace the documents. |
| `approved` | You can add numbers hosted with another provider. The documents can no longer be changed. |
| `rejected` | See `rejection_reason`, then submit new documents. |

The same status is returned as `external_verification_status` on the enterprise's [reputation settings](/docs/number-reputation/settings). It is `null` until you submit documents.

## Step 2: Add the numbers

Use the same endpoint as for Telnyx numbers. You can mix both kinds in one request:

```bash
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": ["+13125550142"]
  }'
```

A number that is not in your Telnyx inventory is treated as hosted elsewhere and returned with `source: "external"`. The request is atomic: if any number is rejected, none are added.

| Rejection | Cause |
| :--- | :--- |
| `detail` contains `external_verification_required` | The enterprise's ownership verification is not approved yet. Complete Step 1. |
| Only US local numbers are supported | The number is toll-free, not a US number, or not valid. |
| The carrier of this number could not be verified | No carrier record was found for the number. |
| Not eligible for association | The number cannot be registered by this account. |
| Reported as permanently disconnected | The number was reported as disconnected by its previous holder. |

A `503` means ownership could not be verified at that moment. Nothing was added; retry the request.

## Ownership checks

Each number carries an `ownership_status`:

| `ownership_status` | Meaning |
| :--- | :--- |
| `verified` | The number is with the carrier on record. |
| `pending_confirmation` | The number moved to a different carrier, or its periodic ownership re-verification is due. Confirm you still own it before `confirm_by`. |
| `flagged` | A periodic re-verification went unanswered. The number stays monitored and is not removed; confirm ownership to return it to `verified`. |
| `removed` | The number is no longer monitored. Returned by `ownership_confirm` with `still_own: false`, and when you list numbers with `filter[ownership_status]=removed`. |

Filter either list endpoint by `filter[source]` or `filter[ownership_status]`:

```bash
curl -G https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter[ownership_status]=pending_confirmation"
```

For one number, get when it was last checked, the carrier on record, and its history:

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

## Confirm ownership after a carrier change

Porting your own number to a new carrier is normal, so a carrier change does not remove the number. It sets `ownership_status` to `pending_confirmation` with a `confirm_by` deadline three business days later, and Telnyx notifies you by email and [webhook](#webhooks).

If you still own the number:

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B13125550142/ownership_confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"still_own": true}'
```

The number returns to `verified` and its new carrier becomes the one on record. You can attach supporting proof with `evidence_document_id`.

  After a carrier change (`flag_reason: carrier_changed`), a number you do not
  confirm before `confirm_by` is removed from Number Reputation and
  de-registered; you can add it again afterwards. A periodic re-verification
  (`flag_reason: reverification_due`) left unanswered does not remove the
  number: it becomes `flagged` and stays monitored until you confirm it.

## Report a number you no longer own

Tell Telnyx as soon as a number is ported away from you, disconnected, or otherwise stops being yours. Send `still_own: false` at any time, whatever the number's status:

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B13125550142/ownership_confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"still_own": false}'
```

The number is removed immediately and returned with `ownership_status: "removed"`.

## Removed numbers

Removed numbers are not returned by the list endpoints unless you ask for them:

```bash
curl -G https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter[ownership_status]=removed"
```

Each one has a `removed_at` timestamp and a `removal_reason`:

| `removal_reason` | Meaning |
| :--- | :--- |
| `unconfirmed_ownership` | A carrier change was not confirmed before the deadline. |
| `ported_away` | You answered a carrier-change confirmation with `still_own: false`. |
| `reassigned` | The number was reported as permanently disconnected. |
| `customer_reported` | You reported that you no longer own the number. |
| `customer_removed` | You removed the number from monitoring. |

## Webhooks

Set one HTTPS URL per enterprise to receive ownership events. Send `null` to stop receiving them.

```bash
curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/webhook \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://example.com/webhooks/telnyx"}'
```

| Event | Sent when |
| :--- | :--- |
| `number_reputation.number.flagged` | A number needs ownership confirmation: its carrier changed (`flag_reason: carrier_changed`) or its periodic re-verification is due (`reverification_due`). Includes `confirm_by`. |
| `number_reputation.number.removed` | A number was removed for an ownership reason. Includes `removal_reason` and `removed_at`. |
| `number_reputation.external_verification.status_changed` | Your ownership verification was approved or rejected. |

The full payload schemas are in the API reference under **Ownership Webhooks**.

Each delivery wraps the event in the standard Telnyx envelope; the number's details are under `data.payload`. Example `number_reputation.number.flagged` request body:

```json
{
  "data": {
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2026-10-05T07:00:12.521992Z",
    "event_type": "number_reputation.number.flagged",
    "payload": {
      "record_type": "reputation_phone_number",
      "phone_number": "+13125550142",
      "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
      "source": "external",
      "ownership_status": "pending_confirmation",
      "flag_reason": "carrier_changed",
      "confirm_by": "2026-10-08T07:00:00+00:00"
    }
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks/telnyx"
  }
}
```

  Removing a number yourself with `DELETE` does not send a
  `number_reputation.number.removed` event. Your endpoint must be publicly
  accessible and respond with `200` to acknowledge receipt.

## Next steps

- [Phone Number Reputation](/docs/number-reputation/phone-numbers) to query scores for the numbers you added.
- [Reputation Remediation](/docs/number-reputation/remediation) to submit flagged numbers for re-evaluation.
- [Reputation Settings](/docs/number-reputation/settings) for the approval gates and refresh schedule.

---

### Remediation

> Source: https://developers.telnyx.com/docs/number-reputation/remediation.md

## Overview

When one of your monitored numbers is flagged with an elevated `spam_risk`, you can submit it for **reputation remediation** — a request to the call-analytics networks to re-evaluate the number's classification. You submit a batch of numbers, Telnyx forwards the request on your behalf, and you poll the request to track its status and per-number outcome.

Remediation is **asynchronous**. The submit call returns `202 Accepted` with a request id; the request then moves through processing states until it completes. Use the GET endpoints to poll status and per-number results.

  Submitting a remediation request does **not** guarantee a number will be
  removed from any spam or block list. Remediation is a **re-evaluation
  request** to the call-analytics networks — the outcome may be that the number
  remains flagged (`requires_review` or `refused`).

  Even after a number is successfully remediated, calls from it can **still be
  blocked or labeled** by downstream spam filters and carriers. Those systems
  are outside Telnyx's control, and a successful remediation does not override
  them.

  Both Number Reputation approval gates must be cleared (reputation `status`
  **and** `loa_status` both `approved`) and the Number Reputation Terms of
  Service accepted before you can submit remediation requests. See the
  [LOA guide](/docs/number-reputation/loa) and
  [Reputation Settings](/docs/number-reputation/settings).

## Submit numbers for remediation

```bash
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"],
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation"
  }'
```

| Field | Required | Description |
| :--- | :--- | :--- |
| `phone_numbers` | yes | Phone numbers in E.164 format. **1 to 2,000** per request. Must belong to this enterprise. |
| `call_purpose` | yes | Free-text description of how the numbers are used (1 to 2,000 chars). |
| `contact_email` | no | A contact email for this remediation request, used for tracking and any follow-up (max 255 chars). |
| `webhook_url` | no | Optional `https://` URL to receive status notifications (max 2,048 chars). |

The endpoint returns **`202 Accepted`** with the persisted request and its initial `status` of `pending`:

```json
{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "pending",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T18:06:51.940749Z",
    "tier1_completed_at": null,
    "tier2_completed_at": null,
    "results": null
  }
}
```

  A number that already has an in-flight remediation request cannot be submitted
  again — the request returns **`409 Conflict`**. Numbers that do not belong to
  this enterprise return **`422 Unprocessable Entity`**.

### Count fields

| Field | Meaning |
| :--- | :--- |
| `phone_numbers_count` | Total numbers in the batch, including any later cancelled. May exceed the sum of the per-category result buckets. |
| `phone_numbers_submitted` | Numbers accepted for remediation (not rejected as ineligible). Counts numbers still queued as well as processed ones. |
| `phone_numbers_ineligible` | Numbers rejected before submission (for example, in a cooldown window). |

## Get a remediation request

Retrieve full detail for one request, including per-number results once they are available:

```bash
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation/9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A completed request includes the populated `results` object:

```json
{
  "data": {
    "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
    "status": "completed",
    "phone_numbers_count": 2,
    "phone_numbers_submitted": 2,
    "phone_numbers_ineligible": 0,
    "call_purpose": "Outbound appointment reminders for our dental clinic.",
    "contact_email": "ops@example.com",
    "webhook_url": "https://example.com/hooks/remediation",
    "created_at": "2026-06-07T18:06:51.940749Z",
    "updated_at": "2026-06-07T19:42:10.112233Z",
    "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
    "tier2_completed_at": "2026-06-07T19:42:10.000000Z",
    "results": {
      "remediated": ["+12025551234"],
      "not_flagged": [],
      "requires_review": ["+12025555678"],
      "ineligible": [],
      "refused": []
    }
  }
}
```

A request that is not found — or does not belong to this enterprise — returns **`404 Not Found`**.

### Status values

`status` is the customer-facing meta-status:

| `status` | Meaning |
| :--- | :--- |
| `pending` | Request accepted and queued; not yet forwarded for review. |
| `in_progress` | Forwarded and under review by the call-analytics networks. |
| `completed` | Review finished. Inspect `results` for the per-number outcome. |
| `failed` | The request could not be processed. |
| `cancelled` | The request was cancelled. |

`results` is `null` while the request is still pending and is populated once results are available.

### Per-number result buckets

When `results` is populated, each number falls into exactly one bucket. Empty buckets are returned as empty arrays (never omitted), so you can iterate without null-checking each key:

| Bucket | Meaning |
| :--- | :--- |
| `remediated` | The number's classification was successfully re-evaluated and cleared. |
| `not_flagged` | The number was not flagged, so no remediation was needed. |
| `requires_review` | The number needs further review and remains flagged for now. |
| `ineligible` | The number was rejected before submission (for example, in a cooldown window). |
| `refused` | The re-evaluation request was declined; the number remains flagged. |

  A number landing in the `remediated` bucket means the analytics networks
  re-evaluated and cleared it — it does **not** guarantee the number is removed
  from every spam list, and downstream carriers and spam filters may still
  block or label calls from it.

## List remediation requests

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

List items are a **slim shape** — they omit `results`, `webhook_url`, and the count breakdown. Call [get by id](#get-a-remediation-request) for full detail.

```json
{
  "data": [
    {
      "id": "9f1c8a2e-5b3d-4e7a-9c11-2a6f0d3b4c55",
      "status": "completed",
      "phone_numbers_count": 2,
      "call_purpose": "Outbound appointment reminders for our dental clinic.",
      "created_at": "2026-06-07T18:06:51.940749Z",
      "updated_at": "2026-06-07T19:42:10.112233Z",
      "tier1_completed_at": "2026-06-07T19:10:04.000000Z",
      "tier2_completed_at": "2026-06-07T19:42:10.000000Z"
    }
  ],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_results": 1,
    "total_pages": 1
  }
}
```

### Pagination

Pagination is JSON:API. Page numbering is **1-based**; `page[size]` **defaults to 20** and is capped at **250**.

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

### Filters

| Filter | Description |
| :--- | :--- |
| `filter[status]` | Filter by customer-facing status: `pending`, `in_progress`, `completed`, `failed`, or `cancelled`. |
| `filter[created_at][gte]` | Created on or after this ISO 8601 timestamp. |
| `filter[created_at][lte]` | Created on or before this ISO 8601 timestamp. |

```bash
curl -g "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/remediation?filter[status]=completed&filter[created_at][gte]=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Webhooks

When you provide a `webhook_url` in the remediation request, Telnyx sends status notifications to that URL as the request progresses. The webhook events are:

| Event | Description |
| :--- | :--- |
| `number_reputation.remediation.tier1_complete` | First-tier review complete. The request continues to tier 2. |
| `number_reputation.remediation.completed` | Remediation finished. Inspect `results` for the per-number outcome. |
| `number_reputation.remediation.failed` | The request could not be processed. |

  Webhook payloads include the remediation request `id`, `status`, and
  `results` (when populated). Ensure your webhook endpoint is publicly
  accessible and responds with `200` to acknowledge receipt.

## Next steps

- [Query reputation scores](/docs/number-reputation/phone-numbers) to see which numbers are flagged.
- [Reputation Settings](/docs/number-reputation/settings) to manage auto-refresh schedules and the activation lifecycle.
- [Number Reputation pricing](/docs/number-reputation/pricing) for remediation pricing details.

---

## API Reference (Number Reputation)

### Enterprises

- [List enterprises](https://developers.telnyx.com/api-reference/enterprises/list-enterprises.md): Return the enterprises you own, paginated. The default page size is 20; the maximum is 250.
- [Create an enterprise](https://developers.telnyx.com/api-reference/enterprises/create-an-enterprise.md): Create the legal entity (enterprise) that represents your business on the Telnyx platform.
- [Delete an enterprise](https://developers.telnyx.com/api-reference/enterprises/delete-an-enterprise.md): Soft-delete an enterprise.
- [Get an enterprise](https://developers.telnyx.com/api-reference/enterprises/get-an-enterprise.md): Retrieve a single enterprise by id. Returns `404` if the id does not exist or does not belong to your account.
- [Replace an enterprise](https://developers.telnyx.com/api-reference/enterprises/replace-an-enterprise.md): Replace the enterprise's mutable fields. Only mutable fields may be sent. Server-assigned and immutable fields (`id`, `record_type`, `created_at`, `updated_at`…

### Terms of Service

- [Agree to the Phone Number Reputation Terms of Service](https://developers.telnyx.com/api-reference/terms-of-service/agree-to-the-phone-number-reputation-terms-of-service.md): Records the authenticated user's agreement to the current Phone Number Reputation ToS. No body required. Idempotent.

### Reputation

- [Disable phone-number reputation for an enterprise](https://developers.telnyx.com/api-reference/reputation/disable-phone-number-reputation-for-an-enterprise.md): Disable Phone Number Reputation. All registered numbers are de-registered as a cascade. The enterprise itself is unaffected. Returns `204` on success, `404` if…
- [Get phone-number reputation settings for an enterprise](https://developers.telnyx.com/api-reference/reputation/get-phone-number-reputation-settings-for-an-enterprise.md): Phone Number Reputation tracks how your outbound caller-IDs are perceived (spam risk, engagement, etc.) across the call-screening ecosystem. This endpoint read…
- [Enable phone-number reputation for an enterprise](https://developers.telnyx.com/api-reference/reputation/enable-phone-number-reputation-for-an-enterprise.md): Activate Phone Number Reputation for the given enterprise. Requires an uploaded Letter of Authorization document (the `loa_document_id` references the Telnyx D…
- [Change the reputation refresh frequency](https://developers.telnyx.com/api-reference/reputation/change-the-reputation-refresh-frequency.md): Update how often Telnyx refreshes the reputation data for this enterprise's registered numbers. The new frequency takes effect on the next scheduled refresh.
- [Replace the reputation Letter of Authorization document](https://developers.telnyx.com/api-reference/reputation/replace-the-reputation-letter-of-authorization-document.md): Point the enterprise's reputation settings at a new signed LOA document. This resets LOA approval to `pending`; the new document must be approved before additi…
- [Render a phone-number reputation Letter of Authorization](https://developers.telnyx.com/api-reference/reputation/render-a-phone-number-reputation-letter-of-authorization.md): Render the LOA for this enterprise as a PDF. The enterprise identity, address, and authorized-representative contact are taken from the enterprise record; the…
- [Set the number-ownership webhook URL](https://developers.telnyx.com/api-reference/reputation/set-the-number-ownership-webhook-url.md): Set the HTTPS URL that receives number-ownership events for this enterprise: `number_reputation.number.flagged`, `number_reputation.number.removed` and `number…
- [Get the ownership-proof review status](https://developers.telnyx.com/api-reference/reputation/get-the-ownership-proof-review-status.md): Get the review status of the enterprise's ownership proof for phone numbers hosted with another provider. Returns 404 when no proof has been submitted.
- [Submit ownership proof for numbers hosted elsewhere](https://developers.telnyx.com/api-reference/reputation/submit-ownership-proof-for-numbers-hosted-elsewhere.md): Request permission to add phone numbers that the enterprise owns but that are hosted with another provider. Submit one or more uploaded documents proving owner…
- [List reputation-monitored phone numbers for an enterprise](https://developers.telnyx.com/api-reference/reputation/list-reputation-monitored-phone-numbers-for-an-enterprise.md): Paginated list of phone numbers registered for reputation monitoring under this enterprise. The response includes the latest reputation snapshot per number whe…
- [Register phone numbers for reputation monitoring](https://developers.telnyx.com/api-reference/reputation/register-phone-numbers-for-reputation-monitoring.md): Add up to 100 phone numbers to reputation monitoring on this enterprise. Each must be in E.164 format (`+1NPANXXXXXX` for US/CA). A number in your Telnyx phone…
- [Remove a phone number from reputation monitoring](https://developers.telnyx.com/api-reference/reputation/remove-a-phone-number-from-reputation-monitoring.md): Stop tracking the reputation of this phone number. The number itself remains in your inventory; only the reputation registration is removed.
- [Get a single reputation-monitored phone number](https://developers.telnyx.com/api-reference/reputation/get-a-single-reputation-monitored-phone-number.md): Retrieve one registered number with its latest reputation snapshot. The `phone_number` path parameter is in E.164 format and must be URL-encoded (e.g. `%2B1949…
- [Get a phone number's ownership tracking detail](https://developers.telnyx.com/api-reference/reputation/get-a-phone-numbers-ownership-tracking-detail.md): Get the ownership status of a phone number, when it was last checked, the carrier recorded as its baseline, and the history of ownership events.
- [Confirm or give up ownership of a phone number](https://developers.telnyx.com/api-reference/reputation/confirm-or-give-up-ownership-of-a-phone-number.md): Answer an ownership question about a phone number hosted with another provider.
- [List reputation-monitored phone numbers across all enterprises](https://developers.telnyx.com/api-reference/reputation/list-reputation-monitored-phone-numbers-across-all-enterprises.md): Convenience alias for `GET /v2/enterprises/{enterprise_id}/reputation/numbers` that returns numbers across every enterprise you own. Useful when you don't want…
- [Remove a phone number from reputation monitoring (no enterprise_id required)](https://developers.telnyx.com/api-reference/reputation/remove-a-phone-number-from-reputation-monitoring-no-enterprise_id-required.md): Convenience alias for `DELETE /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}`.
- [Get a reputation-monitored number (no enterprise_id required)](https://developers.telnyx.com/api-reference/reputation/get-a-reputation-monitored-number-no-enterprise_id-required.md): Convenience alias for `GET /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}`.
- [List reputation remediation requests for an enterprise](https://developers.telnyx.com/api-reference/reputation/list-reputation-remediation-requests-for-an-enterprise.md): Paginated list of remediation requests for this enterprise. List items omit per-number results and webhook URLs to keep the response small; call GET by id for…
- [Submit phone numbers for reputation remediation](https://developers.telnyx.com/api-reference/reputation/submit-phone-numbers-for-reputation-remediation.md): Submit a batch of phone numbers belonging to this enterprise for reputation remediation. The request is accepted asynchronously: this endpoint returns `202` wi…
- [Get a reputation remediation request](https://developers.telnyx.com/api-reference/reputation/get-a-reputation-remediation-request.md): Retrieve the full detail of a remediation request, including current status, per-number results (once available), and submission metadata.

### Phone Numbers

- [Number ownership needs confirmation](https://developers.telnyx.com/api-reference/phone-numbers/number-ownership-needs-confirmation.md): A monitored number hosted with another provider changed carrier, or its periodic ownership re-verification is due. Confirm ownership before `confirm_by` with `…
- [Number removed for an ownership reason](https://developers.telnyx.com/api-reference/phone-numbers/number-removed-for-an-ownership-reason.md): A monitored number was removed from reputation monitoring because its ownership could not be kept verified. Removing a number yourself with `DELETE` does not s…
- [Ownership verification reviewed](https://developers.telnyx.com/api-reference/phone-numbers/ownership-verification-reviewed.md): The ownership proof submitted for numbers hosted with another provider was approved or rejected.