Phone Number Reputation

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"

​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

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