> ## 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](/docs/number-reputation/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 |

<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.
</Note>

## 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](/api-reference/documents/upload-a-document). 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](/docs/number-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:

```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.
</Warning>

## 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.
</Note>

## Next steps

* [Phone Number Reputation](/docs/number-reputation/phone-numbers) to query scores for the numbers you added.
* [Reputation Remediation](/docs/number-reputation/remediation) to submit flagged numbers for re-evaluation.
* [Reputation Settings](/docs/number-reputation/settings) for the approval gates and refresh schedule.