# Telnyx Numbers: Number Reputation — Full Documentation
> Complete page content for Number Reputation (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com).
> Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/numbers/number-reputation.txt

## Guides

### Overview

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

## Overview

**Number Reputation** lets you query the spam reputation of your outbound calling phone numbers. For each number you get:

| Field | Values | Meaning |
| :--- | :--- | :--- |
| `spam_risk` | `low` / `medium` / `high` | Overall spam likelihood. `high` means the number is likely flagged as spam by carriers. |
| `maturity_score` | 0-100 or `null` | Maturity metric for the number. |
| `connection_score` | 0-100 or `null` | Connection metric for the number. |
| `engagement_score` | 0-100 or `null` | Engagement metric for the number. |
| `sentiment_score` | 0-100 or `null` | Sentiment metric for the number. |
| `spam_category` | string or `null` | Category label assigned to the number if it 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. |

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

You can also set up automatic re-checking on a configurable schedule (`business_daily`, `daily`, `weekly`, `biweekly`, `monthly`, or `never`).

Reputation data is 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.

## How it works

1. **Register your business** as an [Enterprise](/docs/branded-calling/enterprises/index)
2. **Render, sign, and upload a Letter of Authorization (LOA)** to get a `loa_document_id` - see the [LOA guide](/docs/branded-calling/number-reputation/loa)
3. **Enable Number Reputation** with that `loa_document_id` (billable) - your details are submitted for automated vetting (takes minutes)
4. **Wait for both approval gates** - reputation `status` **and** `loa_status` must each be `approved`
5. **Associate phone numbers** for monitoring (up to 100 per request, US numbers, E.164) - billable
6. **Query reputation scores** - cached results are free, fresh (live) queries are billed
7. **Automatic monitoring** re-checks your numbers on a configurable schedule

Number Reputation is a standalone monitoring product; it reports spam reputation and does not change how your calls are placed.

  Enabling reputation, adding numbers, and forcing a fresh (live) query are
  **billable actions**. Rendering the LOA is **not** billable. See
  [Telnyx pricing](https://telnyx.com/pricing/numbers) for current pricing.

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

---

### Quickstart

> Source: https://developers.telnyx.com/docs/branded-calling/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/index) 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. See the [Enterprises overview](/docs/branded-calling/enterprises/index) 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/branded-calling/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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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/branded-calling/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.

  Adding numbers is a **billable action**. See
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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"
```

## Next steps

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

---

### Letter of Authorization

> Source: https://developers.telnyx.com/docs/branded-calling/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
      [Telnyx pricing](https://telnyx.com/pricing/numbers) 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/branded-calling/number-reputation/settings#disable-number-reputation)
  and re-enable it with the new document.

## Next steps

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

---

### Reputation Settings

> Source: https://developers.telnyx.com/docs/branded-calling/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/index) registered on your account
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/branded-calling/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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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/branded-calling/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 [Telnyx pricing](https://telnyx.com/pricing/numbers).

## 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 Number Reputation

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

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

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

## 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 and belong to your Telnyx phone-number inventory

  Adding numbers is a **billable action**. See
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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 |
| `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
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
  [Telnyx pricing](https://telnyx.com/pricing/numbers) 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"
```

---

### Reputation Remediation

> Source: https://developers.telnyx.com/docs/branded-calling/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/branded-calling/number-reputation/loa) and
  [Reputation Settings](/docs/branded-calling/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"
```

## Next steps

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

---

## 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.
- [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`…
- [Delete an enterprise](https://developers.telnyx.com/api-reference/enterprises/delete-an-enterprise.md): Soft-delete an enterprise.

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

- [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…
- [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…
- [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.
- [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…
- [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…
- [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) and belong to your Telnyx phon…
- [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…
- [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.
- [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…
- [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}`.
- [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}`.