> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Number Reputation Settings

> Enable, configure, and manage Number Reputation monitoring for your enterprise.

## 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 theme={null}
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**.

<Note>
  Enabling reputation is a **billable action**. See
  [Telnyx pricing](https://telnyx.com/pricing/numbers) for current pricing.
</Note>

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

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

<Warning>
  `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).
</Warning>

## 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 theme={null}
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 theme={null}
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"}'
```

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

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 theme={null}
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 theme={null}
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.

<Note>
  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.
</Note>