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

> Step-by-step guide to set up Number Reputation and start monitoring your phone numbers' spam scores.

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 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. If you skip it, **Step 5 (enable) returns `403`**.

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

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

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

## 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 theme={null}
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

Up to 100 numbers per request. 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.

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

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

## Step 8: Query reputation

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

### Cached (free, once data exists)

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

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

### Fresh - live query (billed)

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

The response includes:

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

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