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.

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.

​
Prerequisites

  • A Telnyx account with verified or enterprise level access
  • An API key
  • At least one US local phone number on your account
  • A signed Letter of Authorization (LOA) from the business entity

​
Step 1: Accept Terms of Service

curl -X POST https://api.telnyx.com/v2/terms_of_service/number_reputation/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Step 2: Create an enterprise

If you don’t already have an enterprise, create 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: Upload a Letter of Authorization

Upload a signed LOA via the Documents page in the Telnyx Portal. The LOA authorizes Telnyx to register your numbers with third-party analytics providers on your behalf. After uploading, note the document ID — you can find it in the document list on the same page. You’ll need it in the next step.

​
Step 4: 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": "YOUR_DOCUMENT_ID",
    "check_frequency": "business_daily"
  }'
Your enterprise details are sent for automated vetting. The reputation status starts at pending and transitions to approved (success) or rejected (failure, with reasons in rejection_reasons). check_frequency is optional; if omitted it defaults to business_daily. See Reputation Settings for all options. Poll the status with: 
curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
  -H "Authorization: Bearer YOUR_API_KEY"
Use a sensible cadence (e.g. once every 30–60 seconds). Don’t poll in a tight loop. If status is rejected, fix the underlying issue (see rejection_reasons) and call POST /v2/enterprises/{enterprise_id}/reputation again. Trying to add phone numbers (Step 5) before the enterprise reaches approved returns 400 — wait for vetting to finish.

​
Step 5: Associate phone numbers

Once your enterprise is 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 local in E.164 format.

​
Step 6: Query reputation

​
Cached (free)

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

​
Fresh — live query (billed)

curl "https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/+12025551234?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"
  }
}

​
Step 7: 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"}'

​
Force a refresh on demand

If you don’t want to wait for the next scheduled refresh, ask Telnyx to refresh up to 100 numbers immediately: 
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"]}'
The response includes a per-number success/failure breakdown.

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

​
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/+12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a number from monitoring
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/+12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Next steps