Skip to main content

​
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:
  1. An Enterprise registered on your account
  2. 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.
  3. 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 Telnyx 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:
StatusMeaning
statusActivation lifecycle of the enterprise’s reputation. pending → approved / rejected.
loa_statusTelnyx’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:
FieldDescription
statusActivation lifecycle: pending, approved, or rejected. (After you disable reputation the settings are removed and GET returns 404 instead of a status.)
loa_statusLOA review gate: pending, approved, or rejected.
check_frequencyCurrent auto-refresh schedule.
loa_document_idYour uploaded LOA reference (nullable).
rejection_reasonsArray of reasons, populated when status is rejected (otherwise null).
created_at / updated_atTimestamps.

​
Auto-refresh schedules

Telnyx automatically runs fresh reputation queries on all your registered numbers based on the configured check_frequency:
FrequencySchedule
business_dailyMon-Fri (default)
dailyEvery day including weekends
weeklyOnce per week
biweeklyEvery 2 weeks
monthlyOnce per month
neverManual 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 Telnyx 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.