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://developers.telnyx.com/development/llms/numbers-number-reputation-llms-txt.md

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 from Branded Calling. Number Reputation is currently supported in the US only. Canadian numbers are not accepted.

How it works

Register your business as an Enterprise — an Enterprise can serve Number Reputation, Branded Calling, or both.
Accept the Number Reputation Terms of Service — a one-time step per account.
Render, sign, and upload a Letter of Authorization (LOA) to get a loa_document_id — see the LOA guide.
Enable Number Reputation with that loa_document_id (billable) — your details are submitted for automated vetting (takes minutes).
Wait for both approval gates — reputation status and loa_status must each be approved.
Associate phone numbers for monitoring (up to 100 per request, US numbers, E.164) — billable.
Query reputation scores — cached results are free, fresh (live) queries are billed.
Automatic monitoring re-checks your numbers on a configurable schedule.
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)
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 — get from zero to your first reputation query
Pricing — Number Reputation pricing details
Letter of Authorization — render, sign, upload, and replace a rejected LOA
Reputation Settings — vetting lifecycle, auto-refresh schedules, and configuration
Phone Number Reputation — reputation data model, scores, and querying in depth
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 and an API key. There are two separate approval gates you must clear before you can add phone numbers — don’t confuse them:

Reputation status must be approved — the activation lifecycle for the enterprise.
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
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.

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 for the full field reference.

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.

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

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:

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

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

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

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

You cannot add numbers until both are approved.

Step 7: Associate phone numbers

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

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

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

Fresh — live query (billed)

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

The response includes:

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

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

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

Disable Number Reputation entirely

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:

# 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 — 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 — vetting lifecycle, auto-refresh schedules, and configuration
Read the LOA guide — render, sign, upload, and replace a rejected LOA
Explore Phone Number Reputation — reputation data model, scores, and querying in depth
Submit flagged numbers for 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.

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:

Reputation status must be approved (the activation lifecycle).
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.

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:

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:

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. The Documents API returns a document id — that value is your loa_document_id.

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:

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

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 for current pricing. Telnyx reviews your uploaded LOA. Track loa_status on the reputation settings:

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

{
  "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:

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 and re-enable it with the new document.

Next steps

Enable and configure reputation
Associate 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:

An Enterprise registered on your account — an Enterprise can serve Number Reputation, Branded Calling, or both.
A signed Letter of Authorization (LOA) rendered, signed, and uploaded to the Documents API to obtain a loa_document_id — follow the LOA guide. The LOA authorizes Telnyx to register your numbers with the major call-analytics networks used by US carriers.
Agreement to the Number Reputation Terms of Service.

Enable Number Reputation

Submit your LOA document ID to enable reputation monitoring:

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 for current pricing. Enabling returns 403 if you have not agreed to the Number Reputation Terms of Service. See 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.

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:

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

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.

Disable Number Reputation

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

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) before enabling monitoring:

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 — 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 and Reputation Settings.

Associate phone numbers

Add phone numbers for reputation monitoring:

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

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:

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

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

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

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

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:

{
  "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 for current pricing. Refreshes are subject to per-enterprise rate limits.

Remove a number from monitoring

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:

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

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 and Reputation Settings.

Submit numbers for remediation

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:

{
  "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:

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:

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

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 for full detail.

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

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.

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 to see which numbers are flagged.
Reputation Settings to manage auto-refresh schedules and the activation lifecycle.
Number Reputation pricing for remediation pricing details.

API Reference (Number Reputation)

Enterprises

List enterprises: Return the enterprises you own, paginated. The default page size is 20; the maximum is 250.
Create an enterprise: Create the legal entity (enterprise) that represents your business on the Telnyx platform.
Get an enterprise: Retrieve a single enterprise by id. Returns 404 if the id does not exist or does not belong to your account.
Replace an enterprise: 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: Soft-delete an enterprise.

Terms of Service

Agree to the Phone Number Reputation Terms of Service: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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): Convenience alias for GET /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}.
Remove a phone number from reputation monitoring (no enterprise_id required): Convenience alias for DELETE /v2/enterprises/{enterprise_id}/reputation/numbers/{phone_number}.
List reputation remediation requests for an enterprise: 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: 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: Retrieve the full detail of a remediation request, including current status, per-number results (once available), and submission metadata.

​Telnyx Numbers: Number Reputation — Full Documentation

​Guides

​Overview

​Overview

​How it works

​Resource hierarchy

​Key concepts

​Reputation data

​Constraints

​Ecosystem

​Next steps

​Quickstart

​Prerequisites

​Step 1: Accept the Number Reputation Terms of Service

​Step 2: Create an enterprise

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

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

​Step 5: Enable Number Reputation

​Step 6: Wait for both approval gates

​Step 7: Associate phone numbers

​Step 8: Query reputation

​Cached (free, once data exists)

​Fresh — live query (billed)

​Step 9: Manage ongoing monitoring

​Change auto-refresh frequency

​Remove a number from monitoring

​Disable Number Reputation entirely

​Simplified endpoints

​Portal setup

​Next steps

​Pricing

​Pricing

​How billing works

​Letter of Authorization

​Overview

​LOA approval gate

​Replace a pending or rejected LOA

​Next steps

​Reputation Settings

​Overview

​Prerequisites

​Enable Number Reputation

​Two approval gates

​Vetting lifecycle

​Auto-refresh schedules

​Change the schedule

​Disable Number Reputation

​Terms of Service

​Phone Numbers

​Overview

​Associate phone numbers

​Query reputation

​Cached query (free)

​Fresh query (billed)

​Reputation data model

​Spam risk

​Granular scores (0-100)

​Spam categories

​List all monitored numbers

​Force a refresh

​Remove a number from monitoring

​Simplified endpoints

​Remediation

​Overview

​Submit numbers for remediation

​Count fields

​Get a remediation request

​Status values

​Per-number result buckets

​List remediation requests

​Pagination

​Filters

​Webhooks

​Next steps

​API Reference (Number Reputation)

​Enterprises

​Terms of Service

​Reputation

Telnyx Numbers: Number Reputation — Full Documentation

Guides

Overview

Overview

How it works

Resource hierarchy

Key concepts

Reputation data

Constraints

Ecosystem

Next steps

Quickstart

Prerequisites

Step 1: Accept the Number Reputation Terms of Service

Step 2: Create an enterprise

Step 3: Render the Letter of Authorization (LOA)

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

Step 5: Enable Number Reputation

Step 6: Wait for both approval gates

Step 7: Associate phone numbers

Step 8: Query reputation

Cached (free, once data exists)

Fresh — live query (billed)

Step 9: Manage ongoing monitoring

Change auto-refresh frequency

Remove a number from monitoring

Disable Number Reputation entirely

Simplified endpoints

Portal setup

Next steps

Pricing

Pricing

How billing works

Letter of Authorization

Overview

LOA approval gate

Replace a pending or rejected LOA

Next steps

Reputation Settings

Overview

Prerequisites

Enable Number Reputation

Two approval gates

Vetting lifecycle

Auto-refresh schedules

Change the schedule

Disable Number Reputation

Terms of Service

Phone Numbers

Overview

Associate phone numbers

Query reputation

Cached query (free)

Fresh query (billed)

Reputation data model

Spam risk

Granular scores (0-100)

Spam categories

List all monitored numbers

Force a refresh

Remove a number from monitoring

Simplified endpoints

Remediation

Overview

Submit numbers for remediation

Count fields

Get a remediation request

Status values

Per-number result buckets

List remediation requests

Pagination

Filters

Webhooks

Next steps

API Reference (Number Reputation)

Enterprises

Terms of Service

Reputation