Number Reputation Settings

Enable, configure, and manage Number Reputation monitoring for your enterprise.

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 — an Enterprise can serve Number Reputation, Branded Calling, or both.
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 Number Reputation 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:

Status	Meaning
status	Activation lifecycle of the enterprise’s reputation. pending → approved / rejected.
loa_status	Telnyx’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:

Field	Description
status	Activation lifecycle: pending, approved, or rejected. (After you disable reputation the settings are removed and GET returns 404 instead of a status.)
loa_status	LOA review gate: pending, approved, or rejected.
check_frequency	Current auto-refresh schedule.
loa_document_id	Your uploaded LOA reference (nullable).
rejection_reasons	Array of reasons, populated when status is rejected (otherwise null).
created_at / updated_at	Timestamps.

Auto-refresh schedules

Telnyx automatically runs fresh reputation queries on all your registered numbers based on the configured check_frequency:

Frequency	Schedule
business_daily	Mon-Fri (default)
daily	Every day including weekends
weekly	Once per week
biweekly	Every 2 weeks
monthly	Once per month
never	Manual 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 Number Reputation 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.