Skip to main content

​
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 Telnyx 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 Telnyx 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

ValueMeaning
lowNumber has a clean reputation
mediumSome risk indicators present
highNumber is likely flagged as spam by carriers
nullNot enough data yet

​
Granular scores (0-100)

ScoreMetric
maturity_scoreMaturity metric for the number
connection_scoreConnection metric for the number
engagement_scoreEngagement metric for the number
sentiment_scoreSentiment 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

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 Telnyx 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:
MethodSimplified 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"