Number Reputation Quickstart

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. There are two separate approval gates you must clear before you can add phone numbers — don’t confuse them:

Reputation status must be approved — the activation lifecycle for the enterprise.
loa_status must be approved — Telnyx reviews your signed Letter of Authorization.

Both are tracked independently, and both must read approved before POST .../reputation/numbers will accept numbers.

Prerequisites

A Telnyx account with verified or enterprise level access
An API key
At least one US phone number on your account, in E.164 format
A signed Letter of Authorization (LOA) — you render this from Telnyx in Step 3

Step 1: Accept the Number Reputation Terms of Service

Read the full terms at telnyx.com/terms/reputation-services.

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. If you skip it, Step 5 (enable) returns 403.

To check whether you’ve already agreed, call GET /v2/terms_of_service/status?product_type=number_reputation. That endpoint defaults to branded_calling, so you must pass product_type=number_reputation to read the Number Reputation status.

Step 2: Create an enterprise

If you don’t already have an enterprise, create one. An Enterprise can serve Number Reputation, Branded Calling, or both — you don’t need a separate 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: Render the Letter of Authorization (LOA)

Telnyx renders a pre-filled LOA PDF from your enterprise record. You do not upload your own template — you render the Telnyx one, sign it, and upload the signed copy back.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{}'

The response body is the PDF itself (application/pdf); -o loa.pdf saves it to disk. Rendering the LOA is not billable. See the LOA guide for the optional agent (reseller) and signature body fields, and the full approval/replacement flow.

Step 4: Sign the LOA and upload it to the Documents API

Sign loa.pdf (e-signature or wet signature), then upload the signed copy to the Telnyx Documents API:

curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"

The response contains the document id:

{
  "data": {
    "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
  }
}

Save data.id — you’ll pass it as loa_document_id in the next step.

Step 5: 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": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
    "check_frequency": "business_daily"
  }'

check_frequency is optional and defaults to business_daily.

Enabling reputation is a billable action. See Number Reputation pricing for current pricing.

Step 6: Wait for both approval gates

Your enterprise details are submitted for automated vetting and Telnyx reviews your signed LOA. Poll the reputation settings until both status and loa_status read approved:

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

{
  "data": {
    "status": "approved",
    "loa_status": "approved"
  }
}

Field	Gate
`status`	Activation lifecycle: `pending` → `approved` (or `rejected` — see `rejection_reasons`).
`loa_status`	LOA review: `pending` → `approved` (or `rejected` — replace the LOA, see the LOA guide).

You cannot add numbers until both are approved.

Step 7: Associate phone numbers

Once both gates are 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 numbers in E.164 format (+1NPANXXXXXX), in-service, and belong to your Telnyx phone-number inventory. Non-US numbers are rejected.

Adding numbers is a billable action. See Number Reputation pricing for current pricing.

A freshly added number has reputation_data: null until Telnyx collects its first refresh. Querying it (Step 8) triggers an immediate lookup. Because the number has no cached data yet, that first query performs a live (billed) lookup even from the “Cached” endpoint; cached reads are free only once data exists.

Step 8: Query reputation

URL-encode the leading + of the phone number in the path as %2B.

Cached (free, once data exists)

The first query on a number with no cached reputation data triggers a live, billed lookup regardless of this endpoint; only subsequent reads are free.

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

Fresh — live query (billed)

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

Every field in reputation_data is nullable, and the whole object is null until the first refresh has been collected.

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

The enterprise’s reputation status must be approved; a request made while it is still pending returns 400 Bad Request.

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"

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/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove a number from monitoring (URL-encode the leading + as %2B in the path)
curl -X DELETE https://api.telnyx.com/v2/reputation/numbers/%2B12025551234 \
  -H "Authorization: Bearer YOUR_API_KEY"

Portal setup

You can also set up Number Reputation from the Telnyx Portal — the full workflow (accept ToS, create enterprise, render LOA, enable monitoring, add numbers, query scores) is available in the UI. The API and Portal are fully interchangeable.

Next steps

Learn about Reputation Settings — vetting lifecycle, auto-refresh schedules, and configuration
Read the LOA guide — render, sign, upload, and replace a rejected LOA
Explore Phone Number Reputation — reputation data model, scores, and querying in depth
Submit flagged numbers for Reputation Remediation

​Prerequisites

​Step 1: Accept the Number Reputation Terms of Service

​Step 2: Create an enterprise

​Step 3: Render the Letter of Authorization (LOA)

​Step 4: Sign the LOA and upload it to the Documents API

​Step 5: Enable Number Reputation

​Step 6: Wait for both approval gates

​Step 7: Associate phone numbers

​Step 8: Query reputation

​Cached (free, once data exists)

​Fresh — live query (billed)

​Step 9: Manage ongoing monitoring

​Change auto-refresh frequency

​Remove a number from monitoring

​Disable Number Reputation entirely

​Simplified endpoints

​Portal setup

​Next steps

Prerequisites

Step 1: Accept the Number Reputation Terms of Service

Step 2: Create an enterprise

Step 3: Render the Letter of Authorization (LOA)

Step 4: Sign the LOA and upload it to the Documents API

Step 5: Enable Number Reputation

Step 6: Wait for both approval gates

Step 7: Associate phone numbers

Step 8: Query reputation

Cached (free, once data exists)

Fresh — live query (billed)

Step 9: Manage ongoing monitoring

Change auto-refresh frequency

Remove a number from monitoring

Disable Number Reputation entirely

Simplified endpoints

Portal setup

Next steps