> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Numbers Hosted With Another Provider

> Monitor and remediate the reputation of phone numbers you own that are hosted outside Telnyx, and keep their ownership status confirmed.

## 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](https://developers.telnyx.com/docs/number-reputation/remediation.md) 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 |

> [!NOTE]
>
> 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](https://developers.telnyx.com/api-reference/documents/upload-a-document.md). Then submit them for review:

```bash theme={null}
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.

```json theme={null}
{
  "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:

```bash theme={null}
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](https://developers.telnyx.com/docs/number-reputation/settings.md). 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:

```bash theme={null}
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]`:

```bash theme={null}
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:

```bash theme={null}
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](#webhooks).

If you still own the number:

```bash theme={null}
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`.

> [!WARNING]
>
> 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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```json theme={null}
{
  "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"
  }
}
```

> [!NOTE]
>
> 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](https://developers.telnyx.com/docs/number-reputation/phone-numbers.md) to query scores for the numbers you added.
* [Reputation Remediation](https://developers.telnyx.com/docs/number-reputation/remediation.md) to submit flagged numbers for re-evaluation.
* [Reputation Settings](https://developers.telnyx.com/docs/number-reputation/settings.md) for the approval gates and refresh schedule.