Skip to main content

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.

​
Overview

Once your enterprise is approved for Number Reputation, you can associate phone numbers for monitoring. Each number gets its own reputation data with spam risk levels and granular scores.

​
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 local in E.164 format
  • Numbers must be in-service and belong to your account

​
Query reputation

​
Cached query (free)

Returns the most recent stored reputation data: 
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/+12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Fresh query (billed)

Fetches live data from Hiya: 
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/+12025551234?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 Hiya doesn’t have data for the number yet, reputation_data will still be null.

​
Reputation data model

Each number returns a reputation_data object. For newly-added numbers, reputation_data may be null until the first reputation check completes (either via auto-refresh schedule or a manual refresh). 
{
  "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

​
Granular scores (0–100)

ScoreWhat it measures
maturity_scoreHow established the number is based on calling history over time
connection_scoreHow often recipients answer calls from this number
engagement_scoreWhether recipients stay on the call after answering
sentiment_scoreWhether recipients want ongoing contact (blocking/reporting behavior)
A null score means there isn’t enough data to make a determination.

​
Spam categories

If a number is flagged, spam_category indicates the label assigned by analytics engines (e.g. “Telemarketer”, “Survey”, “Debt Collector”, “Nonprofit”, “Political”). The set is determined by the upstream analytics feed and may grow over time — treat it as an opaque string.

​
List all monitored numbers

curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"
Query parameterDescription
page[number]Page number, starts at 1. Defaults to 1.
page[size]Items per page. Defaults to 10, max 250.
phone_numberFilter to a specific number (E.164, URL-encode the leading + as %2B).
Example with filter: 
curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers?phone_number=%2B12025551234" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Force a refresh on demand

The check_frequency schedule runs automatically, but you can also ask Telnyx to refresh one or more numbers immediately — useful right after registering a new number, or when you suspect a reputation change. 
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", "+12025555678"]
  }'
  • 1–100 numbers per request.
  • All listed numbers must already be associated with the enterprise.
  • The call is synchronous: Telnyx fans out to the reputation feed and returns a per-number result.
Response shape: 
{
  "data": {
    "results": [
      { "phone_number": "+12025551234", "success": true,  "error": null },
      { "phone_number": "+12025555678", "success": false, "error": "Number not associated" }
    ],
    "total_requested": 2,
    "total_successful": 1,
    "total_failed": 1
  }
}
Each successful refresh counts as a billed query per number.

​
Remove a number from monitoring

curl -X DELETE https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/+12025551234 \
  -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}
# 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/+12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"