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. 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 Telnyx 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 Telnyx 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"

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

​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

​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

Next steps