Numbers Hosted With Another Provider

Overview

Number Reputation can monitor phone numbers that you own but that are hosted with another provider. They get the same reputation data, refreshes, and remediation as numbers in your Telnyx inventory. Because Telnyx cannot see when such a number leaves your control, two things are different:

You prove ownership once per enterprise before adding any.
Telnyx checks every day that each number is still with the carrier it was on when you added it, and asks you to confirm ownership if that changes.

	Telnyx numbers	Numbers hosted elsewhere
`source`	`telnyx`	`external`
Requirement to add	In-service in your inventory	Approved ownership verification
Number types	US local and toll-free	US local only
Ownership tracking	Automatic through your inventory	Daily carrier check, with confirmation when the carrier changes

You must own, or be licensed to use, every number you register, and tell Telnyx when that stops being true. See the Reputation Services Terms of Service and your Letter of Authorization.

Step 1: Verify ownership (once per enterprise)

Upload one or more documents that show the enterprise owns its numbers, such as a carrier invoice or account statement, to the Documents API. Then submit them for review:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/external_verification \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["2a7e8337-e803-4057-a4ae-26c40eb0bc6c"],
    "phone_numbers": ["+13125550142"]
  }'

phone_numbers is optional: it tells the reviewer which numbers the documents cover. You can still add numbers that are not listed; each one is checked on its own.

{
  "data": {
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "status": "pending",
    "document_ids": ["2a7e8337-e803-4057-a4ae-26c40eb0bc6c"],
    "phone_numbers": ["+13125550142"],
    "rejection_reason": null,
    "submitted_at": "2026-10-05T09:12:44Z",
    "reviewed_at": null
  }
}

Check the review at any time:

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

`status`	Meaning
`pending`	Awaiting review. You can submit again to replace the documents.
`approved`	You can add numbers hosted with another provider. The documents can no longer be changed.
`rejected`	See `rejection_reason`, then submit new documents.

The same status is returned as external_verification_status on the enterprise’s reputation settings. It is null until you submit documents.

Step 2: Add the numbers

Use the same endpoint as for Telnyx numbers. You can mix both kinds in one request:

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": ["+13125550142"]
  }'

A number that is not in your Telnyx inventory is treated as hosted elsewhere and returned with source: "external". The request is atomic: if any number is rejected, none are added.

Rejection	Cause
`detail` contains `external_verification_required`	The enterprise’s ownership verification is not approved yet. Complete Step 1.
Only US local numbers are supported	The number is toll-free, not a US number, or not valid.
The carrier of this number could not be verified	No carrier record was found for the number.
Not eligible for association	The number cannot be registered by this account.
Reported as permanently disconnected	The number was reported as disconnected by its previous holder.

A 503 means ownership could not be verified at that moment. Nothing was added; retry the request.

Ownership checks

Each number carries an ownership_status:

`ownership_status`	Meaning
`verified`	The number is with the carrier on record.
`pending_confirmation`	The number moved to a different carrier, or its periodic ownership re-verification is due. Confirm you still own it before `confirm_by`.
`flagged`	A periodic re-verification went unanswered. The number stays monitored and is not removed; confirm ownership to return it to `verified`.
`removed`	The number is no longer monitored. Returned by `ownership_confirm` with `still_own: false`, and when you list numbers with `filter[ownership_status]=removed`.

Filter either list endpoint by filter[source] or filter[ownership_status]:

curl -G https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter[ownership_status]=pending_confirmation"

For one number, get when it was last checked, the carrier on record, and its history:

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

Confirm ownership after a carrier change

Porting your own number to a new carrier is normal, so a carrier change does not remove the number. It sets ownership_status to pending_confirmation with a confirm_by deadline three business days later, and Telnyx notifies you by email and webhook. If you still own the number:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B13125550142/ownership_confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"still_own": true}'

The number returns to verified and its new carrier becomes the one on record. You can attach supporting proof with evidence_document_id.

After a carrier change (flag_reason: carrier_changed), a number you do not confirm before confirm_by is removed from Number Reputation and de-registered; you can add it again afterwards. A periodic re-verification (flag_reason: reverification_due) left unanswered does not remove the number: it becomes flagged and stays monitored until you confirm it.

Report a number you no longer own

Tell Telnyx as soon as a number is ported away from you, disconnected, or otherwise stops being yours. Send still_own: false at any time, whatever the number’s status:

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers/%2B13125550142/ownership_confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"still_own": false}'

The number is removed immediately and returned with ownership_status: "removed".

Removed numbers

Removed numbers are not returned by the list endpoints unless you ask for them:

curl -G https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "filter[ownership_status]=removed"

Each one has a removed_at timestamp and a removal_reason:

`removal_reason`	Meaning
`unconfirmed_ownership`	A carrier change was not confirmed before the deadline.
`ported_away`	You answered a carrier-change confirmation with `still_own: false`.
`reassigned`	The number was reported as permanently disconnected.
`customer_reported`	You reported that you no longer own the number.
`customer_removed`	You removed the number from monitoring.

Webhooks

Set one HTTPS URL per enterprise to receive ownership events. Send null to stop receiving them.

curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/webhook \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://example.com/webhooks/telnyx"}'

Event	Sent when
`number_reputation.number.flagged`	A number needs ownership confirmation: its carrier changed (`flag_reason: carrier_changed`) or its periodic re-verification is due (`reverification_due`). Includes `confirm_by`.
`number_reputation.number.removed`	A number was removed for an ownership reason. Includes `removal_reason` and `removed_at`.
`number_reputation.external_verification.status_changed`	Your ownership verification was approved or rejected.

The full payload schemas are in the API reference under Ownership Webhooks. Each delivery wraps the event in the standard Telnyx envelope; the number’s details are under data.payload. Example number_reputation.number.flagged request body:

{
  "data": {
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2026-10-05T07:00:12.521992Z",
    "event_type": "number_reputation.number.flagged",
    "payload": {
      "record_type": "reputation_phone_number",
      "phone_number": "+13125550142",
      "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
      "source": "external",
      "ownership_status": "pending_confirmation",
      "flag_reason": "carrier_changed",
      "confirm_by": "2026-10-08T07:00:00+00:00"
    }
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhooks/telnyx"
  }
}

Removing a number yourself with DELETE does not send a number_reputation.number.removed event. Your endpoint must be publicly accessible and respond with 200 to acknowledge receipt.

Next steps

Phone Number Reputation to query scores for the numbers you added.
Reputation Remediation to submit flagged numbers for re-evaluation.
Reputation Settings for the approval gates and refresh schedule.

Guides

Enterprises API

Reputation Settings API

Phone Number Reputation API

Remediation API

Ownership Webhooks

For AI Agents

Numbers Hosted With Another Provider

Overview

Step 1: Verify ownership (once per enterprise)

Step 2: Add the numbers

Ownership checks

Confirm ownership after a carrier change

Report a number you no longer own

Removed numbers

Webhooks

Next steps

​Overview

​Step 1: Verify ownership (once per enterprise)

​Step 2: Add the numbers

​Ownership checks

​Confirm ownership after a carrier change

​Report a number you no longer own

​Removed numbers

​Webhooks

​Next steps

Overview

Step 1: Verify ownership (once per enterprise)

Step 2: Add the numbers

Ownership checks

Confirm ownership after a carrier change

Report a number you no longer own

Removed numbers

Webhooks

Next steps