# Telnyx Numbers: Porting — Full Documentation
> Complete page content for Porting (Numbers section) of the Telnyx developer docs (https://developers.telnyx.com).
> Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx.com/llms/numbers/porting.txt

## Port In

### Port in orders

> Source: https://developers.telnyx.com/docs/numbers/porting/getting-started.md

## Overview

Port-in orders allow you to transfer existing phone numbers from another carrier to Telnyx. The porting process involves creating a draft order, providing required information and documents, and submitting the order for processing with the losing carrier.

Port orders are processed asynchronously through coordination between Telnyx and the losing carrier. Processing times vary based on carrier, country, and phone number type—ranging from same-day for FastPort-eligible numbers to several weeks for international ports.

For general information about the porting process, timelines, and international requirements, see the [porting support articles](https://support.telnyx.com/en/collections/133126-porting-articles-and-guides).

```mermaid
flowchart LR
    A[Check Portability] --> B[Create Draft Order]
    B --> C[Fulfill Order]
    C --> D[Submit Order]
    D -->|in-process| E[Monitor Progress]
    E --> F{Carrier Review}
    F -->|approved| G[Port Complete]
    F -->|rejected| H[Exception]
    H -->|fix & resubmit| D
```

## Constraints

- Phone numbers must pass a portability check before creating a port order. Non-portable numbers will result in API errors.
- Port orders may be automatically split into multiple orders based on country, number type, SPID (for US/CA), and FastPort eligibility.
- Each split order must be updated and submitted independently.
- A Letter of Authorization (LOA) and recent invoice are required for most port orders.
- Requested FOC dates are not guaranteed—the losing carrier determines the actual activation date.

## Order splitting

When you create a port order with multiple phone numbers, the API may split them into separate orders. Numbers are grouped based on:

- **Country**: Numbers from different countries are split into separate orders.
- **Number type**: Local, toll-free, and mobile numbers are processed separately.
- **SPID**: For US and CA numbers, numbers with different Service Provider IDs are split.
- **FastPort eligibility**: FastPort-eligible numbers are separated from standard port orders.

If your order is split, the API returns multiple port order IDs. You must complete and submit each order individually.

## How it works

### Step 1: Check portability

Use the [Portability check endpoint](https://developers.telnyx.com/api-reference/phone-number-porting/run-a-portability-check) to verify your numbers can be ported to Telnyx before creating an order. Phone numbers must be submitted in E.164 format.

The response indicates whether each number is `portable` and includes additional details like `fast_portable` eligibility and `messaging_capable` status. If a number is not portable, the `not_portable_reason` field explains why.

### Step 2: Create a draft port order

Use the [Create porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-a-porting-order) to create a draft order with your phone numbers.

The API validates the numbers and may split them into multiple orders. Each order is created in `draft` status, allowing you to add required information before submission.

### Step 3: Fulfill the porting order

Use the [Edit porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order) to provide the required information:

- **End user information**: The name and account details of the current account holder with the losing carrier.
- **Service address**: The address associated with the phone numbers being ported.
- **Regulatory requirements**: Documents and information required for the port, such as a Letter of Authorization (LOA) and recent invoice. See the [port-in requirements guide](https://developers.telnyx.com/docs/numbers/porting/port-in-requirements) for details.
- **Phone number configuration**: Optionally assign a `connection_id`, `messaging_profile_id`, or `emergency_address_id` to apply settings to all ported numbers.
- **FOC date**: Select your requested firm order commitment (FOC) date—the date your numbers will port to Telnyx. See the [allowed FOC dates guide](https://developers.telnyx.com/docs/numbers/porting/allowed-foc-dates) for details on retrieving available windows and setting your preferred date.

### Step 4: Submit the port order

Use the [Submit porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/submit-a-porting-order) to submit your order.

The order transitions from `draft` to `in-process` status. Telnyx validates the submission and coordinates with the losing carrier to complete the port.

### Step 5: Monitor order progress

Track your order status using the [Retrieve porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order) or configure webhooks to receive status change notifications.

If the order enters `exception` status, check the order comments for details about the rejection. Update the required information and resubmit.

## Notifications

Configure webhooks to receive real-time updates about your port orders. The `porting_order.status_changed` event fires whenever an order transitions to a new status.

For more information about configuring notifications and viewing event history, see the [port-in notifications guide](https://developers.telnyx.com/docs/numbers/porting/port-in-notifications) and [port-in events guide](https://developers.telnyx.com/docs/numbers/porting/port-in-events).

## Comments

Comments allow you to communicate directly with Telnyx Porting Operations during the porting process. Use the [Create comment endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-a-comment-for-a-porting-order) to send messages or respond to requests from the porting team.

Monitor your port orders for new comments using the [List comments endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-comments-of-a-porting-order). Porting Operations may add comments to request additional information or provide updates about your order. Subscribe to the `porting_order.new_comment` webhook event to receive notifications when new comments are added.

## Additional resources

- [Port-in requirements](https://developers.telnyx.com/docs/numbers/porting/port-in-requirements) - View and fulfill regulatory requirements on your port orders.
- [Allowed FOC dates](https://developers.telnyx.com/docs/numbers/porting/allowed-foc-dates) - Request and set a specific date for your port order to complete.
- [On-demand activations](https://developers.telnyx.com/docs/numbers/porting/on-demand-activations) - Take control of your port order with FastPort on-demand activations.
- [Cancel port order](https://developers.telnyx.com/docs/numbers/porting/cancel-port-order) - Cancel a port order before it completes.

---

### Port-in requirements

> Source: https://developers.telnyx.com/docs/numbers/porting/port-in-requirements.md

## Overview

All port-in orders have regulatory requirements that must be fulfilled before the port can be completed. These requirements vary based on the country and phone number type you are porting.

## How it works

### Step 1: View requirements on your port order

When you create a port order, the `requirements` array is automatically populated based on the country and phone number type being ported. Each requirement includes a `requirement_type_id` that identifies what information is needed.

Use the `GET /v2/porting_orders/{id}/requirements` endpoint to view detailed information about all requirements on your port order, including descriptions and acceptance criteria.

### Step 2: Fulfill requirements

To fulfill a requirement, submit the appropriate `field_value` for each `requirement_type_id` using the [PATCH /v2/porting_orders/{id} endpoint](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order).

The value you provide depends on the requirement type:

- **Document**: Provide a document ID from the [Documents API](https://developers.telnyx.com/api-reference/documents/upload-a-document).
- **Textual**: Provide a string value that meets the acceptance criteria.
- **Address**: Provide an address ID from the [Addresses API](https://developers.telnyx.com/api-reference/addresses/creates-an-address).

For detailed fulfillment instructions for each type, see the [regulatory requirements guide](https://developers.telnyx.com/docs/numbers/phone-numbers/regulatory-requirements).

## Requirement statuses

Each requirement on a port order has a status that indicates its current state:

| Status                         | Description                                                                                                       |
| :----------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| `requirement-info-pending`     | Awaiting user submission. You need to provide information to fulfill the requirement.                             |
| `requirement-info-under-review`| Information has been submitted and is awaiting review by Telnyx Porting Operations.                               |
| `requirement-info-exception`   | The submitted information does not meet the acceptance criteria. You need to resubmit with corrected information. |
| `approved`                     | The requirement has been reviewed and validated by Telnyx Porting Operations.                                     |

## Order-level requirements status

For a high-level view of whether all requirements have been fulfilled and approved, check the `requirements_status` field on the port order:

- `true`: All requirements on the port order have been fulfilled and approved.
- `false`: One or more requirements have not been fulfilled or have not been approved yet.

Use the [GET /v2/porting_orders/{id} endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order) to check this status.

---

### Allowed FOC dates

> Source: https://developers.telnyx.com/docs/numbers/porting/allowed-foc-dates.md

## Overview

The firm order commitment (FOC) date is when the losing carrier agrees to release phone numbers to Telnyx. This is the date your port will actually complete and your numbers will become active on your Telnyx account.

When creating or updating a port order, you can request a specific FOC date using the `foc_datetime_requested` field. This gives you control over when your numbers port, allowing you to coordinate the transition with your business operations.

Once Telnyx receives FOC confirmation from the losing carrier, the order transitions to `foc-date-confirmed` status. The `foc_datetime_actual` field then reflects the confirmed date, which may differ from your requested date depending on carrier availability.

## Constraints

- Requested FOC dates are not guaranteed. The losing carrier ultimately determines the actual FOC date.
- The requested date and time must fall within one of the allowed FOC windows returned by the API.
- FOC windows vary based on the losing carrier and the phone numbers in your order.

## How it works

### Step 1: Retrieve allowed FOC windows

Use the [List allowed FOC dates endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-allowed-foc-dates) to view the available FOC windows for your port order.

The response contains an array of allowed windows, each with `start_time` and `end_time` fields indicating the valid date and time range. All times are in UTC format.

For example, a window with `start_time` of `2024-03-15T15:00:00Z` and `end_time` of `2024-03-15T23:00:00Z` means you can request any time between 15:00 and 23:00 UTC on March 15th.

### Step 2: Set your requested FOC date

Use the [Edit porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order) to set your preferred FOC date.

Update the `activation_settings.foc_datetime_requested` field with a timestamp that falls within one of the allowed windows. The timestamp must be in ISO 8601 format (for example, `2024-03-15T15:00:00Z`).

### Step 3: Monitor FOC confirmation

After submitting your port order, Telnyx works with the losing carrier to confirm the FOC date. When confirmed, the order status changes to `foc-date-confirmed` and the `foc_datetime_actual` field updates with the confirmed date and time.

Monitor your order status through the [Retrieve porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order) or configure webhooks to receive notifications when the status changes.

## Notifications

You can receive webhook notifications when the port order status changes. Configure webhooks to receive `porting_order.status_changed` events when the order transitions to `foc-date-confirmed` status.

For more information about porting webhooks, see the [port-in events guide](https://developers.telnyx.com/docs/numbers/porting/port-in-events).

---

### Cancel port order

> Source: https://developers.telnyx.com/docs/numbers/porting/cancel-port-order.md

## Overview

Canceling a port order allows you to stop a port-in request before it completes. This is useful when business requirements change, the port was submitted in error, or you no longer need to transfer the phone numbers to Telnyx.

When you cancel a port order, it first transitions to a `cancel-pending` status while the Porting Operations team reviews and processes the cancellation request. Once processed, the order moves to `cancelled` status and the port-in will not proceed.

## Constraints

- You cannot cancel a port order via the API within **48 hours of the FOC (Firm Order Commitment) date/time**. If you need to cancel within this window, contact [Telnyx support](https://support.telnyx.com) directly.
- Cancellation requests require review by the Porting Operations team before taking effect.
- Once a port order reaches `cancelled` status, it cannot be reactivated. You would need to submit a new port order.

## Cancellation statuses

When you cancel a port order, it progresses through the following statuses:

| Status           | Description                                                                                        |
| :--------------- | :------------------------------------------------------------------------------------------------- |
| `cancel-pending` | The cancellation request has been submitted and is awaiting review by the Porting Operations team. |
| `cancelled`      | The port order has been successfully cancelled and will not proceed.                               |

## How it works

### Step 1: Cancel the port order

Use the [POST /v2/porting_orders/{id}/actions/cancel endpoint](https://developers.telnyx.com/api-reference/porting-orders/cancel-a-porting-order) to request cancellation of a port order. Provide the port order ID in the request path.

The port order will transition to `cancel-pending` status upon successful submission.

If the port order's FOC date is within 48 hours, the API will return an error. In this case, contact [Telnyx support](https://support.telnyx.com) to request cancellation.

### Step 2: Monitor cancellation status

You can check the status of the cancellation using the [GET /v2/porting_orders/{id} endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order).

The port order will remain in `cancel-pending` status until the Porting Operations team processes the request. Once complete, the status will change to `cancelled`.

## Notifications

You can receive webhook notifications when the port order status changes. Configure webhooks to receive `porting_order.status_changed` events when the order transitions to `cancel-pending` and `cancelled` statuses.

For more information about porting webhooks, see the [port-in events guide](https://developers.telnyx.com/docs/numbers/porting/port-in-events).

---

### On-demand activations

> Source: https://developers.telnyx.com/docs/numbers/porting/on-demand-activations.md

## Overview

On-demand activations give you control over when your ported phone numbers activate. Rather than having numbers activate automatically at a carrier-assigned time, you can trigger the activation yourself within a designated window on the FOC (Firm Order Commitment) date.

This differs from scheduled activations where numbers automatically port at the exact FOC date and time assigned by the carrier. With on-demand activation, you choose the precise moment within the activation window that works best for your business operations.

If you don't initiate the activation during the window, the numbers will automatically port at the end of the window. This ensures your port order completes even if you miss the manual activation opportunity.

## Constraints

- On-demand activation is only available for orders where `fast_port_eligible` is `true`.
- Currently available for phone numbers in the **US** and **Canada** only.
- You can only initiate activation after the order reaches `foc-date-confirmed` status.
- Activation must occur within the designated activation window on the FOC date.

## Activation windows

Each country has a specific window during which you can initiate on-demand activation. The window defines the earliest and latest times you can trigger the port.

| Country | Window start | Window end | Duration |
| :------ | :----------- | :--------- | :------- |
| US      | 6:00 AM CT   | 8:00 PM CT | 14 hours |
| Canada  | 8:00 AM CT   | 3:00 PM CT | 7 hours  |

When your order reaches `foc-date-confirmed` status, an activation job is created. The `activation_windows` array in the activation job response shows the exact start and end times for your specific order.

The `activate_at` field indicates when the port will occur. By default, this is set to the end of the activation window. When you initiate on-demand activation, this field updates to reflect when you triggered the request.

## Activation job statuses

Each activation job has a status indicating its current state:

| Status      | Description                                                                 |
| :---------- | :-------------------------------------------------------------------------- |
| `created`   | The activation job exists and is waiting for the activation window to open. |
| `in-process`| The activation has been initiated and numbers are being ported.             |
| `completed` | The activation finished successfully and numbers have been ported.          |

## How it works

### Step 1: Enable on-demand activation

By default, all porting orders use scheduled activation (`activation_type: scheduled`). To enable on-demand activation, update the order's activation settings using the [Edit porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order).

Set `activation_settings.activation_type` to `on-demand`. The order must have `fast_port_eligible` set to `true` for this to succeed.

### Step 2: View the activation window

Once your order reaches `foc-date-confirmed` status, retrieve the activation job to see your activation window. Use the [List porting activation jobs endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-activation-jobs) to view the `activation_windows` array containing your window's `start_at` and `end_at` times.

### Step 3: Initiate activation

When the FOC date arrives and you're within the activation window, trigger the port using the [Activate porting order endpoint](https://developers.telnyx.com/api-reference/porting-orders/activate-every-number-in-a-porting-order-asynchronously).

The `activate_at` field updates to reflect the time you submitted the request, and the activation process begins.

### Step 4: Monitor activation progress

Track the activation job status to monitor progress. Use the [List porting activation jobs endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-activation-jobs) or [Retrieve a porting activation job endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-activation-job) to check the current `status`.

The job progresses from `created` to `in-process` to `completed`. Once the status reaches `completed`, your numbers have finished porting and are active on your Telnyx account.

For real-time updates, configure [porting notifications](https://developers.telnyx.com/docs/numbers/porting/port-in-notifications) to receive webhooks as the activation progresses.

---

### Port-in order notifications

> Source: https://developers.telnyx.com/docs/numbers/porting/port-in-notifications.md

We understand the importance of being able to track the progress and status of your port orders. That is why we offer port-in notifications for the following events:

1. Port order status changes
2. New comments
3. Split port orders
4. Messaging activation
5. Deleted "draft" porting orders

Notifications can be emitted to either email or webhook addresses.

The following sections will cover how to enable notification settings for port-in events and provide example responses to various webhook notification events.

## How to setup notifications via the Portal for all port orders (email and webhook)

If you are adding port-in notification settings in the portal, they will apply for all port orders that you create. Here is how to get started: 

1. Sign in to the Telnyx Portal
2. Go to your `Account Settings` and click on the `Advanced Features` section. Then select Notifications.
3. Click on the `New Profile` button to create a new `Notification Profile`
4. Click on the `New Channel` button to specify which email or webhook URL to send notifications to. Add as many notification channels as you would like!
5. Click on the `New Setting` button, select `Port In Notifications` and select the profile and channel that you would like Telnyx to send port-in notifications to.

If you have further questions, check out this support article or contact our customer support team.

## How to setup notifications on specific port orders (webhook only)

If your use case or integration requires each port order to have its own webhook URL for port-in notifications, you can specify a unique URL as the value for the `webhook_url` parameter in the port order form. This will allow you to receive notifications of updates to the specified order at the webhook URL you provided.

An example PATCH request is shown below:

```bash
curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{{id}}' \
--header 'Authorization: Bearer [REDACTED] \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhook_url": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
}'
```

## Example webhook notification events:

### Transition to `in-process` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "8179f546-d479-42be-822b-8c78e1e89a59",
    "occurred_at": "2023-01-11T16:08:31.804886Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "f6e10519-4664-4119-bb03-bbe73cf26ed3",
      "status": {
        "details": [],
        "value": "in-process"
      },
      "support_key": "sr_ac8c24",
      "updated_at": "2023-01-11T16:08:31.804886Z",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `submitted` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "12ae614e-ed37-4a19-9fe3-2b69bf33d429",
    "occurred_at": "2021-01-19T19:52:13.874635Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "submitted"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:52:13+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `exception` status

A port-in order can have multiple underlying exception reasons. When resolved, the order will transition back to a `submitted` status (and you will receive the same webhook outlined in the previous section). 

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "72322cb3-b6c6-46a4-a571-21a759c02da0",
    "occurred_at": "2021-01-19T19:51:37.844234Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [
          {
            "code": "ACCOUNT_NUMBER_MISMATCH",
            "description": "Account number does not match that on the CSR"
          },
          {
            "code": "PORTING_ORDER_SPLIT_REQUIRED",
            "description": "The OSP requires this Porting Order to be split map_exception_detail and submitted as separate orders"
          },
          {
            "code": "LOA_ILLEGIBLE",
            "description": "The LOA is illegible"
          }
        ],
        "value": "exception"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:51:37+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `foc-date-confirmed` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "80227461-b684-4e89-a1a9-5055a2b4d8ef",
    "occurred_at": "2021-03-19T19:48:58.261079Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "foc-date-confirmed"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:48:57+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `ported` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "334e12a2-a016-489e-a2b6-7abb46637327",
    "occurred_at": "2021-03-19T19:48:58.261079Z",
    "payload": {
      "customer_reference": "1-alpha-2-bravo-3-charlie",
      "id": "3594c6c3-51a7-4306-b715-ca3765f13464",
      "status": {
        "details": [],
        "value": "ported"
      },
      "support_key": "sr_98f022",
      "updated_at": "2021-03-19T19:48:57+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `cancel-pending` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "4f0c225d-3892-4e0e-9524-7625dfc20b19",
    "occurred_at": "2022-04-11T15:50:53.869432Z",
    "payload": {
      "customer_reference": "Test1234",
      "id": "f17074cb-72ee-48b4-bb45-64894e756f01",
      "status": {
        "details": [],
        "value": "cancel-pending"
      },
      "support_key": "sr_602ae7",
      "updated_at": "2022-04-11T15:50:52+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `cancelled` status

```json
{
  "data": {
    "event_type": "porting_order.status_changed",
    "id": "6cac3a83-dc30-45a9-ab51-32e1882f4d04",
    "occurred_at": "2022-04-11T15:52:52.596025Z",
    "payload": {
      "customer_reference": "Test1234",
      "id": "f17074cb-72ee-48b4-bb45-64894e756f01",
      "status": {
        "details": [],
        "value": "cancelled"
      },
      "support_key": "sr_602ae7",
      "updated_at": "2022-04-11T15:52:47+00:00",
      "webhook_url": "https://example.com/porting_webhooks"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### New Comment

```json
{
  "data": {
    "event_type": "porting_order.new_comment",
    "id": "6cafaed2-05f4-4791-9bcf-2392a0c912ef",
    "occurred_at": "2021-11-04T17:37:43.145988Z",
    "payload": {
      "comment": {
        "body": "Testing Webhooks 123",
        "id": "ca4b9cf6-d840-4ba9-ba38-95f4bc971164",
        "inserted_at": "2021-11-04T17:37:42Z",
        "user_id": null,
        "user_type": "admin"
      },
      "porting_order_id": "b3d55519-25c8-4af4-a50a-c92a9ddf7da4",
      "support_key": "sr_acdabe"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Split port-in order

You will receive one webhook for each number that is split from a port order and added to another port order. For example, if you originally submitted a port order with 5 numbers, and 3 numbers were split away from the original port order, then you would receive 3 split port order event notifications.

```json
{
  "data": {
    "event_type": "porting_order.split",
    "id": "a98be460-2d1e-42b7-8c0d-d516c352efd2",
    "occurred_at": "2021-11-15T19:37:37.131727Z",
    "payload": {
      "from": {
        "id": "a6efe074-0a3a-4522-8512-d0e004cf6c7d"
      },
      "to": {
        "id": "ef245340-da3d-4212-8769-1fa7672a675f"
      }
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

## Messaging activation

We recently introduced a new [messaging activation feature](/docs/numbers/porting/messaging-porting) to the V2 porting order API. Enabling this feature for your port order will make you eligible to receive the following webhook events.

If there is an issue with the messaging activation when the phone numbers port in, then you will receive the following webhook:

```json
{
  "id": "626110d0-fab6-4a13-9183-3b331c41ccac",
  "event_type": "porting_order.messaging_changed",
  "occurred_at": "2022-01-01T00:00:00Z",
  "urls": ["https://testing.com/callback"],
  "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
  "format": "v2",
  "payload": {
    "id": "ce2f4509-d166-4834-a0b9-e3ecb469a537",
    "customer_reference": "my_ref_001",
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "exception"
    },
    "support_key": "sr_abc123"
  }
} 
```

Once Telnyx validates that messaging successfully ported for all phone numbers on the port order, then you will receive the following webhook:

```json
{
  "id": "626110d0-fab6-4a13-9183-3b331c41ccac",
  "event_type": "porting_order.messaging_changed",
  "occurred_at": "2022-01-01T00:00:00Z",
  "urls": ["https://testing.com/callback"],
  "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
  "format": "v2",
  "payload": {
    "id": "ce2f4509-d166-4834-a0b9-e3ecb469a537",
    "customer_reference": "my_ref_001",
    "messaging": {
      "messaging_capable": true,
      "enable_messaging": true,
      "messaging_port_status": "ported"
    },
    "support_key": "sr_abc123"
  }
} 
```

## Porting order deletion

A `draft` porting order may be deleted in two ways:

1. The user issues a `DELETE /porting_orders/{id}` [API request](/api-reference/porting-orders/delete-a-porting-order)
2. The `draft` porting order is deleted automatically when it fails to be submitted within 30 days

In either case, Telnyx will emit a webhook notification to communicate that the `draft` porting order has been deleted. An example of this webhook notification is shown below:

```json
{
      "id": "4da7b0e3-1a3c-4111-8335-dc436f6a0a00",
      "event_type": "porting_order.deleted",
      "occurred_at": "2023-01-01T00:00:00Z",
      "urls": ["https://example.com/webhook"],
      "organization_id": "dbdbc891-dc82-4c39-b9a1-e51e830c4352",
      "format": "v2",
      "payload": {
            "id": "74cc03c8-ab01-4887-bc31-9563e482d1e3",
            "customer_reference": "my_ref_123",
            "deleted_at": "2023-01-01T00:00:00Z"
      }
}
```

---

### Port-in events

> Source: https://developers.telnyx.com/docs/numbers/porting/port-in-events.md

## Overview

Port-in events provide a detailed record of everything that happens during the port-in process. Each time a status changes, a comment is added, or an order is split, the system creates an event that you can query and track.

This differs from [port-in notifications](https://developers.telnyx.com/docs/numbers/porting/port-in-notifications), which push updates to your webhook or email as they occur. The Events API gives you on-demand access to view your complete event history and republish notifications for specific events if needed.

With the Port-in Events API, you can:

- View all events across your port-in orders.
- Filter events by port-in order, event type, or date range.
- Republish notifications for specific events to your configured webhook or email.

## Event types

The following event types are generated during the port-in lifecycle:

| Event type                        | Description                                                                 |
| :-------------------------------- | :-------------------------------------------------------------------------- |
| `porting_order.status_changed`    | The port-in order transitioned to a new status.                             |
| `porting_order.new_comment`       | A new comment was added to the port-in order.                               |
| `porting_order.split`             | One or more phone numbers were split into a separate order.                 |
| `porting_order.messaging_changed` | The messaging activation status changed for the port-in order.              |
| `porting_order.deleted`           | A draft port-in order was deleted.                                          |

## How it works

### Step 1: List port-in events

Use the [GET /v2/porting/events endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-events) to retrieve a list of events for your port-in orders.

You can filter results by `porting_order_id` to view events for a specific order, or retrieve all events across your account with pagination support.

### Step 2: Republish event notifications

If you need to resend notifications for a specific event, use the [POST /v2/porting/events/{id}/republish endpoint](https://developers.telnyx.com/api-reference/porting-orders/republish-a-porting-event) where `{id}` is the event ID.

This endpoint republishes notifications only to channels you are currently subscribed to. To configure your notification settings, see [how to set up port-in notifications](https://developers.telnyx.com/docs/numbers/porting/port-in-notifications#how-to-setup-notifications-via-the-portal-for-all-port-orders-email-and-webhook).

Republishing an event resends the notifications but does not create a new event in the system. Email notifications may take a few minutes to be delivered.

---

### Porting additional steps

> Source: https://developers.telnyx.com/docs/numbers/porting/porting-additional-steps.md

## Overview

After you create and populate a porting order, Telnyx may require additional steps depending on the phone numbers being ported and the details provided. These steps must be completed before you can submit the order.

Additional steps differ from [supplemental port order requirements](https://developers.telnyx.com/docs/numbers/porting/port-in-requirements), which cover documents and textual information needed for specific countries or number types. Additional steps involve actions or decisions that affect other phone numbers on your losing carrier's account.

## Checking for additional steps

The `additional_steps` array on a porting order indicates whether any additional steps are required.

| Value | Meaning |
| :---- | :------ |
| `[]` (empty array) | No additional steps required. You can proceed with submission. |
| `["associated_phone_numbers"]` | You must provide a list of phone numbers on your losing carrier's account that are not porting to Telnyx, and specify whether each should remain active or be deactivated after the port completes. |

Retrieve the porting order using the [GET /v2/porting_orders/{id} endpoint](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order) and check the `additional_steps` field in the response.

## Associated phone numbers

This additional step applies to partial ports of GB local phone numbers. When porting only some phone numbers from an account, you must specify what happens to the remaining phone numbers on the losing carrier's account.

### When this step is required

The `associated_phone_numbers` step appears when both conditions are met:

- The porting order is for `GB` `local` phone numbers.
- The `port_type` is set to `partial_port`.

### How it works

You must provide a list of phone numbers on your losing carrier's account that are not being ported to Telnyx. For each phone number or range, you must indicate one of two outcomes:

- **Keep**: The phone number remains active with the losing carrier after the port completes.
- **Disconnect**: The phone number is disconnected from the losing carrier after the port completes.

If the billing telephone number (BTN) is included in the port, all remaining number ranges can only be disconnected.

### Completing this step

Use the [POST /v2/porting_orders/{id}/associated_phone_numbers endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-an-associated-phone-number) to specify ranges of phone numbers and their intended outcome (`keep` or `disconnect`). You can associate multiple number ranges by sending separate requests for each range.

The phone numbers you specify in this step are not being ported to Telnyx. This endpoint communicates what should happen to other phone numbers on the losing carrier's account. Without this information, the losing carrier will reject the porting order.

### Managing associated phone numbers

You can manage the phone numbers associated with your porting order using these endpoints:

| Action | Endpoint |
| :----- | :------- |
| List associated phone numbers | [GET /v2/porting_orders/{id}/associated_phone_numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-associated-phone-numbers) |
| Remove an associated phone number | [DELETE /v2/porting_orders/{id}/associated_phone_numbers/{associated_phone_number_id}](https://developers.telnyx.com/api-reference/porting-orders/delete-an-associated-phone-number) |

---

### Extensions

> Source: https://developers.telnyx.com/docs/numbers/porting/extensions.md

## Overview

Phone number extensions allow multiple phone lines to branch off from a single direct inward dialing (DID) number or main line. This setup is common in offices or call centers where individual desks or employees need unique extensions.

The system has two components:

- **Route number**: The primary phone number (also called the "main" number) that serves as the gateway for incoming calls before they are directed to specific extensions.
- **Extended numbers**: Short digit sequences appended to the route number that connect callers directly to specific endpoints like departments or individuals.

For example, if the route number is `+49 20 12345678`, extensions might include `+49 20 123456780` or `+49 20 1234567806`.

When porting extended numbers, you first create a porting order with the route number, then attach the extensions to that order before submission.

## Constraints

- Extended number porting is currently only available for German port orders.
- Extensions can only be added while the porting order is in `draft`, `in-process`, or `exception` status.
- The maximum extension range is `0` to `999`.
- Activation ranges must be equal to or a subset of the extension range.
- Activation ranges cannot overlap.

## Extension range and activation ranges

Extensions are created in blocks defined by two parameters:

- **`extension_range`**: Represents the full range of extensions available for the route number. This typically covers 10 numbers (`0`-`9`), 100 numbers (`0`-`99`), or 1000 numbers (`0`-`999`). All extensions within this range will port with the route number.
- **`activation_ranges`**: Specifies which extensions within the `extension_range` should be active immediately upon port completion. Extensions not included in `activation_ranges` will port but remain inactive on your account.

For example, if your route number is `+49 20 12345678` and you want to activate only extension `+49 20 123456784`:

- Set `extension_range` to `0`-`9` (covering `+49 20 123456780` through `+49 20 123456789`).
- Set `activation_ranges` to `4`-`4` (activating only `+49 20 123456784`).

For multiple non-contiguous extensions like `+49 20 1234567804`, `+49 20 1234567819`, `+49 20 1234567820`, and `+49 20 1234567842`:

- Set `extension_range` to `0`-`99`.
- Set `activation_ranges` to include `4`-`4`, `19`-`20`, and `42`-`42`.

## How it works

### Step 1: Create a porting order with the route number

Create a porting order that includes the route number (the main DID). Do not include the extended numbers in the initial order.

### Step 2: Retrieve the porting phone number ID

Use the [List all porting phone numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-phone-numbers) endpoint to retrieve the `porting_phone_number_id` for your route number. You will need this ID to attach extensions.

### Step 3: Add extensions to the porting order

Use the [Create a phone number extension](https://developers.telnyx.com/api-reference/porting-orders/create-a-phone-number-extension) endpoint to attach extensions to your porting order. Provide the `porting_phone_number_id`, `extension_range`, and `activation_ranges` in your request.

### Step 4: Submit the porting order

Once extensions are attached, submit your porting order through the standard porting workflow. The route number and all extensions within the `extension_range` will port together.

## Manage extensions

### View extensions

The route number appears in the [List all porting phone numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-phone-numbers) response, but extended numbers do not. To view extensions attached to a porting order, use the [List all phone number extensions](https://developers.telnyx.com/api-reference/porting-orders/list-all-phone-number-extensions) endpoint.

### Delete extensions

To remove extensions from a porting order before submission, use the [Delete a phone number extension](https://developers.telnyx.com/api-reference/porting-orders/delete-a-phone-number-extension) endpoint. The order must be in `draft`, `in-process`, or `exception` status.

---

### Messaging + porting

> Source: https://developers.telnyx.com/docs/numbers/porting/messaging-porting.md

## Overview

For local and toll-free phone numbers in the US and Canada, porting voice and porting messaging are two separate processes. A porting order transitioning to `ported` status indicates that voice has ported to Telnyx, but this status does not reflect the state of messaging.

Messaging routing is controlled by a NetNumber ID (NNID), which identifies the provider that owns SMS routing for a telephone number. At the FOC date and time, the losing carrier is expected to release the NNID so messaging routes through the winning carrier. In most cases, both voice and messaging port simultaneously.

However, if the losing carrier fails to release the NNID, messaging continues to route through them even after voice has ported. This can occur due to:

- Internal system errors or delays at the losing carrier.
- Carrier block policies that retain messaging temporarily after a port.
- Intentional hosting of messaging with another carrier.

Telnyx provides visibility into messaging port status and automatically escalates issues when messaging fails to activate at the FOC date and time.

## Constraints

- Messaging porting tracking is only applicable to US and Canada local and toll-free phone numbers.
- The `messaging_capable` attribute must be `true` on the porting order to enable messaging tracking.
- A `messaging_profile_id` must be assigned to the porting order when enabling messaging activation.
- Phone numbers ported from other countries have messaging port simultaneously with voice.

## Messaging port statuses

The `messaging_port_status` field tracks messaging activation independently from the porting order's main `status` field. A porting order can have a `status` of `ported` (voice has ported) while the `messaging_port_status` is still `activating` or `exception`.

| Status           | Description                                                                                       |
| :--------------- | :------------------------------------------------------------------------------------------------ |
| `pending`        | Messaging activation is enabled but the porting order has not yet reached the FOC date and time. |
| `activating`     | The porting order has ported and Telnyx is verifying messaging activation.                       |
| `ported`         | Messaging has successfully ported to Telnyx.                                                     |
| `exception`      | Messaging failed to port automatically and Telnyx is escalating with the losing carrier.         |
| `not_applicable` | Messaging activation was not enabled for this porting order.                                     |

## How it works

### Step 1: Verify messaging capability

Check the `messaging_capable` attribute on your porting order or portability check response. Use the [POST /v2/portability_checks](https://developers.telnyx.com/api-reference/phone-number-porting/run-a-portability-check) endpoint to verify capability before creating a porting order, or check the `messaging` object on an existing porting order using the [GET /v2/porting_orders/{id}](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order) endpoint.

- If `messaging_capable` is `true`, Telnyx can support messaging for the phone numbers on the order.
- If `messaging_capable` is `false`, Telnyx cannot support messaging for those phone numbers.

### Step 2: Enable messaging activation

To enable messaging tracking and activation, update the porting order using the [PATCH /v2/porting_orders/{id}](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order) endpoint. Set `enable_messaging` to `true` in the `messaging` object.

You must also assign a `messaging_profile_id` in the `phone_number_configuration` object. This messaging profile is applied to all phone numbers on the order upon porting.

The porting order must be in `draft`, `in-process`, or `exception` status to enable this feature.

### Step 3: Monitor messaging port status

Prior to the FOC date and time, the order reflects `messaging_port_status: pending`. Once the porting order transitions to `ported` status, the messaging port status changes to `activating` while Telnyx verifies messaging activation.

In most cases, the losing carrier releases the NNID at the FOC date and time, and the status updates to `ported`.

### Step 4: Handle exceptions

If the losing carrier fails to release messaging, the status changes to `exception`. When this occurs, the Telnyx Messaging Ops team is automatically notified and escalates with the losing carrier. Resolution typically occurs within 72 hours for local numbers and up to 5 business days for toll-free numbers.

Once resolved, the `messaging_port_status` updates to `ported`.

## Webhook notifications

[Follow this support article](https://support.telnyx.com/en/articles/4277896-notification-settings) to set up webhook notifications for messaging port status changes.

Select the Notification Setting "Port In Notifications" to receive `porting_order.messaging_changed` events.

## Partial messaging ports

When a porting order contains multiple phone numbers, it is possible for some numbers to port messaging successfully while others do not. If any phone number on the order fails to port messaging, the order-level `messaging_port_status` is `exception`.

To check the messaging port status of individual phone numbers, use the [GET /v2/porting_orders/{id}/associated_phone_numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-associated-phone-numbers) endpoint. Each phone number has its own `messaging_port_status` attribute indicating whether that specific number ported messaging successfully.

## Hosted SMS alternative

To avoid potential messaging downtime during porting, you can port SMS to Telnyx before porting voice by submitting a Hosted SMS request. This approach ensures messaging is active on Telnyx before the FOC date and time.

The hosted SMS workflow involves:

- Submitting a Hosted SMS request for your phone numbers at least 4 business days before the scheduled FOC date.
- Creating a porting order with a FOC date at least 4 business days in the future.
- Once the Hosted SMS request completes, SMS routes through Telnyx while voice remains with the losing carrier.
- When the FOC date arrives, voice ports and both services route through Telnyx with no downtime.

For more information, see the [Hosted SMS messaging process](https://support.telnyx.com/en/articles/5336668-hosted-sms-messaging-process) support article.

## Troubleshooting

### Porting voice only without messaging

To port only voice to Telnyx while hosting messaging elsewhere, do not enable messaging activation on the porting order. Leave `enable_messaging` as `null` and do not assign a `messaging_profile_id`. The `messaging_port_status` remains `not_applicable` and Telnyx does not attempt to override the NNID.

If you later decide to activate messaging with Telnyx, see the [Send a message](https://developers.telnyx.com/docs/messaging/messages/send-message) guide.

### Porting non-US and non-Canada phone numbers

For phone numbers outside of the US and Canada, voice and messaging port simultaneously when the order transitions to `ported` status. Messaging porting tracking is available but not required for these numbers. You can optionally enable messaging activation to receive status updates and webhook notifications.

### Messaging port status shows exception

An `exception` status indicates one or more phone numbers on the order are still routing SMS through the losing carrier. Telnyx is automatically escalating with the losing carrier. Continue routing messaging through the losing carrier until you receive notification that messaging has ported.

### Expected messaging port timing

For US and Canada local phone numbers, approximately 90% of orders have messaging activated within 10 minutes of porting. The remaining orders typically complete within 1-2 business days.

For US and Canada toll-free phone numbers, messaging usually ports within 10 minutes. If activation does not occur within that window, resolution may take 4-5 business days.

For all other phone numbers, messaging ports simultaneously with voice.

### Messaging shows ported but messages fail to deliver

Verify that the phone number has a valid `messaging_profile_id` assigned. If a messaging profile is assigned and messages still fail, contact support for investigation.

### Unable to enable messaging activation

Verify that the porting order shows `messaging_capable: true` and the order status is `draft`, `in-process`, or `exception`. If these conditions are met and you cannot enable messaging activation, contact support for assistance.

---

### Bundles with porting

> Source: https://developers.telnyx.com/docs/numbers/porting/bundles-porting.md

## Overview

Bundle pre-configuration allows you to associate [bundles](https://support.telnyx.com/en/articles/8340760-bundles-bundle-pricing) with phone numbers on a porting order before those numbers are active at Telnyx. When the port completes and the phone numbers become active, the pre-configured bundles are automatically applied.

The term "pre-configure" is used because bundles are not actually applied to phone numbers until after the numbers port in and become active at Telnyx. During the porting process, the bundle association exists as a pending configuration that takes effect upon port completion.

## Constraints

- Bundle pre-configuration is only available via API.
- Bundles can be pre-configured or updated at any point before the porting order reaches `ported` or `cancelled` status, including shortly before the FOC date.
- Each bundle can only be associated with one phone number. If a pre-configured bundle is used elsewhere before the port completes, the assignment will fail.
- You can pre-configure up to 20 phone numbers per API request.
- The bundle must be valid for the specific phone number type and characteristics. Invalid bundle-number combinations will return an error.
- Pre-configuring bundles is optional. You can pre-configure bundles for some, all, or none of the phone numbers on a porting order.

## How it works

### Step 1: Verify available bundles

Use the [GET /v2/bundle-pricing/user_bundles endpoint](https://developers.telnyx.com/api-reference/user-bundles/get-user-bundles) to list your bundles, or view them on the [Bundles page](https://portal.telnyx.com/#/app/bundles) in Mission Control Portal.

A bundle is available for pre-configuration if its `resources` array is empty. Each bundle has eligibility criteria for which phone numbers it can be assigned to. To purchase additional bundles, visit the [Bundle Orders page](https://portal.telnyx.com/#/app/bundles/order).

### Step 2: Get porting phone number IDs

Each phone number on a porting order has a unique `porting_phone_number_id` that you need for pre-configuration.

Use the [GET /v2/porting_phone_numbers endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-phone-numbers) with a filter for your porting order ID to retrieve the list of phone numbers and their associated IDs.

### Step 3: Pre-configure bundles

Use the [POST /v2/porting_orders/phone_number_configurations endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-a-list-of-phone-number-configurations) to associate bundles with porting phone numbers. Each configuration requires:

- `porting_phone_number_id`: The ID of the phone number on your porting order.
- `user_bundle_id`: The ID of the bundle to pre-configure.

### Step 4: Verify configurations

Use the `GET /v2/porting_orders/phone_number_configurations` endpoint with your porting order ID to view which bundles are pre-configured with which phone numbers.

When the port completes and phone numbers become active at Telnyx, the pre-configured bundles are automatically applied to the corresponding phone numbers.

---

### Port-in blocks

> Source: https://developers.telnyx.com/docs/numbers/porting/port-in-blocks.md

## Overview

Block porting allows you to port consecutive groups of phone numbers (blocks) from another carrier to Telnyx. Unlike porting individual phone numbers, block porting handles entire ranges of numbers that are assigned together by carriers.

Phone number blocks are groups of consecutive phone numbers—typically 10, 100, or 1,000 numbers in sequence—assigned to a specific area or provider. Carriers manage these blocks as units, which means porting rules differ from individual numbers. Some countries require the entire block to be ported even if only some numbers are active.

By indicating that you are porting a block (rather than individual numbers), Telnyx can apply the correct processing rules and help you avoid rejections or exceptions during the porting process.

## Constraints

- Block porting is currently only available for **Germany (DE)** port orders.
- The maximum size for a single block is 1,000 phone numbers (`0` - `999`).
- Activation ranges must be equal to or a subset of the phone number range.
- Activation ranges cannot overlap with each other.
- When adding a block to an existing order, the block must match the order's country and phone number type.
- Blocks can only be added or deleted when the order is in `draft`, `in-process`, or `exception` status.

## Phone number range and activation ranges

When porting a block, you specify two key components:

**Phone number range**: The complete block of consecutive numbers being ported. This defines the full range that will transfer to Telnyx and must be included in the Letter of Authorization (LOA). Block sizes are typically 10, 100, or 1,000 numbers.

**Activation ranges**: The subset of numbers within the block that you want active immediately upon port completion. Numbers in the phone number range but not in any activation range will still port to your account but remain inactive.

This separation is useful when a country requires full-block porting but you only need certain numbers active. For example, if you own a 1,000-number block but only use 776 of them, you can port the entire block while activating only the numbers you need.

You can specify multiple activation ranges within a single block. For instance, if you need numbers `000`-`064` and number `087` active, you would define two separate activation ranges.

## How it works

### Step 1: Create a port order with blocks

Use the [POST /v2/porting_orders endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-a-porting-order) to create an order. Include a `phone_number_blocks` array with:

- `phone_number_range`: The `start_at` and `end_at` values defining the complete block.
- `activation_ranges`: An array specifying which numbers to activate upon completion.

Both range values must be in E.164 format.

### Step 2: Add blocks to an existing order (if needed)

If you created an order for individual numbers that were rejected because they belong to a block, you can add the block to your existing order rather than starting over.

Use the [POST /v2/porting_orders/{porting_order_id}/phone_number_blocks endpoint](https://developers.telnyx.com/api-reference/porting-orders/create-a-phone-number-block) to add a block. Any phone numbers already on the order that fall within the block range will be incorporated automatically.

### Step 3: View blocks on your order

Use the [GET /v2/porting_orders/{porting_order_id}/phone_number_blocks endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-phone-number-blocks) to view all blocks associated with your order.

Each block has a unique `id`. When you query porting phone numbers using the [List porting phone numbers endpoint](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-phone-numbers), numbers that belong to a block include a `block_reference_id` field linking them to their block.

### Step 4: Remove a block (if needed)

Use the [DELETE /v2/porting_orders/{porting_order_id}/phone_number_blocks/{id} endpoint](https://developers.telnyx.com/api-reference/porting-orders/delete-a-phone-number-block) to remove a block from an order.

When you delete a block, the individual phone numbers remain on the order—only the block grouping is removed.

---

## Port Out

### Port-out orders

> Source: https://developers.telnyx.com/docs/numbers/porting/port-out-quickstart.md

## Overview

A port-out order is created when another carrier requests to transfer phone numbers away from your Telnyx account. This occurs when an end-user authorizes a new carrier to port their number, and that carrier submits a port-in request to Telnyx.

When Telnyx receives a port-out request, the system automatically creates a port-out order in your account. You can then review the order details and choose to authorize or reject the request based on the information provided.

Port-out orders require a response within 24–48 hours. If you do not respond within this window, the port-out is automatically authorized and will proceed on the requested FOC (Firm Order Commitment) date.

## Port-out order statuses

Each port-out order has a `status` field that indicates its current state in the porting process:

| Status            | Description                                                                                                   |
| :---------------- | :------------------------------------------------------------------------------------------------------------ |
| `pending`         | The port-out request has been received and is awaiting your review.                                           |
| `authorized`      | You have approved the port-out request. The numbers will port on the FOC date.                                |
| `rejected-pending`| You have submitted a rejection. The Porting Ops team is reviewing the rejection reason to ensure it is valid. |
| `rejected`        | The port-out request has been formally rejected and will not proceed.                                         |
| `canceled`        | The port-out request has been canceled by the gaining carrier or Telnyx.                                      |
| `ported`          | The phone numbers have successfully ported to the gaining carrier.                                            |

## How it works

### Step 1: Review incoming port-out orders

Use the [GET /v2/portouts](https://developers.telnyx.com/api-reference/number-portout/list-portout-requests) endpoint to list all port-out orders on your account, or use the [GET /v2/portouts/:id](https://developers.telnyx.com/api-reference/number-portout/get-a-portout-request) endpoint to retrieve a specific order by ID.

Review the order details including `phone_numbers`, `carrier_name`, `requested_foc_date`, and any subscriber information to verify the request is valid.

### Step 2: Authorize or reject the order

After reviewing the port-out order, you must either authorize or reject it.

**To authorize a port-out:**

Use the [PATCH /v2/portouts/:id/authorized](https://developers.telnyx.com/api-reference/number-portout/update-status) endpoint where `:id` is the port-out order ID. Once authorized, the phone numbers are cleared to port out on the FOC date.

**To reject a port-out:**

First, retrieve the available rejection codes for your specific order using the [GET /v2/portouts/rejections/:portout_id](https://developers.telnyx.com/api-reference/number-portout/list-eligible-port-out-rejection-codes-for-a-specific-order) endpoint. The available rejection codes vary depending on the phone numbers in the order.

Then, use the [PATCH /v2/portouts/:id/rejected-pending](https://developers.telnyx.com/api-reference/number-portout/update-status) endpoint with the appropriate `rejection_code` in the request body.

If you use rejection code `1001` ("Other"), you must include a `reason` field explaining why you are rejecting the order. The Porting Ops team reviews the rejection reason to ensure it is valid. If the reason is not valid, the order is moved back to `pending` and you are notified to review it again.

## Notifications

To receive updates when port-out order statuses change or new comments are added, configure port-out notifications in your account. Notifications can be sent via email or webhook.

For setup instructions and webhook payload examples, see the [Port-out order notifications](https://developers.telnyx.com/docs/numbers/porting/port-out-notifications) guide.

To view and republish port-out events programmatically, see the [Port-out events API](https://developers.telnyx.com/docs/numbers/porting/port-out-events) guide.

---

### Port out order notifications

> Source: https://developers.telnyx.com/docs/numbers/porting/port-out-notifications.md

We understand the importance of being able to track the progress and status of your port orders. That is why we offer port-out notifications for the following events:
1. Port-out order status changes
2. New comments

Notifications can be emitted to either email or webhook addresses.

The following sections will discuss how to enable notification settings on your account, as well as provide example responses to the various webhook notification events.

## How to set up port-out notifications
If you are adding port-out notification settings in the portal, they will apply for all port orders that you create. Here is how to get started: 

1. Sign in to the Telnyx Portal
2. Go to your `Account Settings` and click on the `Advanced Features` section. Then select Notifications.
3. Click on the `New Profile` button to create a new `Notification Profile`
4. Click on the `New Channel` button to specify which email or webhook URL to send notifications to. Add as many notification channels as you would like!
5. Click on the `New Setting` button, select `Port Out Notifications` and select the profile and channel that you would like Telnyx to send port-out notifications to.

If you have further questions, check out 
 this support article
   or contact our customer support team.

## Example webhook notification events

### Transition to `pending` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "3b19372e-38d4-4a9e-855f-a5a9ed5db4c2",
    "occurred_at": "2022-04-11T14:46:27Z",
    "payload": {
      "carrier_name": "Onvoy",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "pending",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `rejected-pending` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "70d3c550-f4bd-4fa4-8502-d40d265355c4",
    "occurred_at": "2022-04-11T14:47:37Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "rejection_reason": "Reason for rejection",
      "spid": "073H",
      "status": "rejected-pending",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `rejected` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "92db90da-409d-42bb-88a2-13741ac5f2cc",
    "occurred_at": "2022-04-11T14:48:02Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "477bf6c3-c6b9-478a-a035-33bd785d6ae7",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "rejection_reason": "Reason for rejection",
      "spid": "073H",
      "status": "rejected",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `canceled` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "480fd3a5-c580-48c4-b724-84a3170fc043",
    "occurred_at": "2022-04-11T14:50:39Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "d17ac097-fc58-41f4-aab3-6dcd16cafae9",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "canceled",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `authorized` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "c147c471-e051-4cda-a547-c2f7e12b3445",
    "occurred_at": "2022-04-11T14:51:53Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "b31bf5a7-cebb-4ae1-a34f-e3f6af550413",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "authorized",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### Transition to `ported` status
```json
{
  "data": {
    "event_type": "portout.status_changed",
    "id": "8ed7a709-3659-41fe-8c49-7af0037ebf2d",
    "occurred_at": "2022-04-11T14:53:39Z",
    "payload": {
      "carrier_name": "Telnyx",
      "id": "b31bf5a7-cebb-4ae1-a34f-e3f6af550413",
      "phone_numbers": [
        "{{phone_number}}"
      ],
      "spid": "073H",
      "status": "ported",
      "subscriber_name": null,
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/porting_webhooks"
  }
}
```

### New Comment
```json
{
  "data": {
    "event_type": "portout.new_comment",
    "id": "0a9af296-a217-498c-a1ac-651a9fb0b2f5",
    "occurred_at": "2022-12-16T19:06:34Z",
    "payload": {
      "comment": "test comment",
      "id": "10ecb41e-c7b6-49a7-bf4a-23d8688b3ed6",
      "portout_id": "330f47af-4296-417a-84f6-05cec6ea5a8d",
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
  }
}
```

### FOC Date change
If the gaining carrier requests a FOC date change, we will emit the following notification.

For port-out orders, the gaining carrier is allotted a grace period of 10 days, which means the gaining carrier can port the phone number at any point between the FOC date listed and the following 10 days.

While most port out orders are expected to occur on the listed FOC date, there is no guarantee that they will be completed on that day.
```json
{
  "data": {
    "event_type": "portout.foc_date_changed",
    "id": "0a9af296-a217-498c-a1ac-651a9fb0b2f5",
    "occurred_at": "2022-12-16T19:06:34Z",
    "payload": {
      "foc_date": "2022-12-20T00:00:00Z",
      "id": "330f47af-4296-417a-84f6-05cec6ea5a8d",
      "user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/98e5e9e2-4921-4a64-b3c8-da0c6ce760f3"
  }
}
```

---

### Port-out events

> Source: https://developers.telnyx.com/docs/numbers/porting/port-out-events.md

## Overview

Port-out events provide a detailed record of everything that happens during the port-out process. Each time a status changes, a comment is added, or a FOC date is updated, the system creates an event that you can query and track.

This differs from [port-out notifications](https://developers.telnyx.com/docs/numbers/porting/port-out-notifications), which push updates to your webhook or email as they occur. The Events API gives you on-demand access to view your complete event history and republish notifications for specific events if needed.

With the Port-out Events API, you can:

- View all events across your port-out orders.
- Filter events by port-out order, event type, or date range.
- Republish notifications for specific events to your configured webhook or email.

## Event types

The following event types are generated during the port-out lifecycle:

| Event type                   | Description                                                                 |
| :--------------------------- | :-------------------------------------------------------------------------- |
| `portout.status_changed`     | The port-out order transitioned to a new status.                            |
| `portout.new_comment`        | A new comment was added to the port-out order.                              |
| `portout.foc_date_changed`   | The FOC (Firm Order Commitment) date for the port-out was updated.          |

## How it works

### Step 1: List port-out events

Use the [GET /v2/portout/events endpoint](https://developers.telnyx.com/api-reference/number-portout/list-all-port-out-events) to retrieve a list of events for your port-out orders.

You can filter results by `portout_id` to view events for a specific order, or retrieve all events across your account with pagination support.

### Step 2: Republish event notifications

If you need to resend notifications for a specific event, use the [POST /v2/portout/events/{id}/republish endpoint](https://developers.telnyx.com/api-reference/number-portout/republish-a-port-out-event) where `{id}` is the event ID.

This endpoint republishes notifications only to channels you are currently subscribed to. To configure your notification settings, see [how to set up port-out notifications](https://developers.telnyx.com/docs/numbers/porting/port-out-notifications#how-to-set-up-port-out-notifications).

Republishing an event resends the notifications but does not create a new event in the system. Email notifications may take a few minutes to be delivered.

---

## API Reference (Porting)

### Phone Number Porting

- [Run a portability check](https://developers.telnyx.com/api-reference/phone-number-porting/run-a-portability-check.md): Runs a portability check, returning the results immediately.

### Porting Orders

- [List all porting orders](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-orders.md): Returns a list of your porting order.
- [Create a porting order](https://developers.telnyx.com/api-reference/porting-orders/create-a-porting-order.md): Creates a new porting order object.
- [Retrieve a porting order](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-order.md): Retrieves the details of an existing porting order.
- [Edit a porting order](https://developers.telnyx.com/api-reference/porting-orders/edit-a-porting-order.md): Edits the details of an existing porting order.
- [Delete a porting order](https://developers.telnyx.com/api-reference/porting-orders/delete-a-porting-order.md): Deletes an existing porting order. This operation is restrict to porting orders in draft state.
- [Submit a porting order.](https://developers.telnyx.com/api-reference/porting-orders/submit-a-porting-order.md): Confirm and submit your porting order.
- [Cancel a porting order](https://developers.telnyx.com/api-reference/porting-orders/cancel-a-porting-order.md): Cancel a porting order
- [Activate every number in a porting order asynchronously.](https://developers.telnyx.com/api-reference/porting-orders/activate-every-number-in-a-porting-order-asynchronously.md): Activate each number in a porting order asynchronously. This operation is limited to US FastPort orders only.
- [Share a porting order](https://developers.telnyx.com/api-reference/porting-orders/share-a-porting-order.md): Creates a sharing token for a porting order. The token can be used to share the porting order with non-Telnyx users.
- [List allowed FOC dates](https://developers.telnyx.com/api-reference/porting-orders/list-allowed-foc-dates.md): Returns a list of allowed FOC dates for a porting order.
- [List all comments of a porting order](https://developers.telnyx.com/api-reference/porting-orders/list-all-comments-of-a-porting-order.md): Returns a list of all comments of a porting order.
- [Create a comment for a porting order](https://developers.telnyx.com/api-reference/porting-orders/create-a-comment-for-a-porting-order.md): Creates a new comment for a porting order.
- [List all porting phone numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-phone-numbers.md): Returns a list of your porting phone numbers.
- [List all associated phone numbers](https://developers.telnyx.com/api-reference/porting-orders/list-all-associated-phone-numbers.md): Returns a list of all associated phone numbers for a porting order. Associated phone numbers are used for partial porting in GB to specify which phone numbers…
- [Create an associated phone number](https://developers.telnyx.com/api-reference/porting-orders/create-an-associated-phone-number.md): Creates a new associated phone number for a porting order. This is used for partial porting in GB to specify which phone numbers should be kept or disconnected.
- [Delete an associated phone number](https://developers.telnyx.com/api-reference/porting-orders/delete-an-associated-phone-number.md): Deletes an associated phone number from a porting order.
- [List all phone number blocks](https://developers.telnyx.com/api-reference/porting-orders/list-all-phone-number-blocks.md): Returns a list of all phone number blocks of a porting order.
- [Create a phone number block](https://developers.telnyx.com/api-reference/porting-orders/create-a-phone-number-block.md): Creates a new phone number block.
- [Delete a phone number block](https://developers.telnyx.com/api-reference/porting-orders/delete-a-phone-number-block.md): Deletes a phone number block.
- [List all phone number extensions](https://developers.telnyx.com/api-reference/porting-orders/list-all-phone-number-extensions.md): Returns a list of all phone number extensions of a porting order.
- [Create a phone number extension](https://developers.telnyx.com/api-reference/porting-orders/create-a-phone-number-extension.md): Creates a new phone number extension.
- [Delete a phone number extension](https://developers.telnyx.com/api-reference/porting-orders/delete-a-phone-number-extension.md): Deletes a phone number extension.
- [List all phone number configurations](https://developers.telnyx.com/api-reference/porting-orders/list-all-phone-number-configurations.md): Returns a list of phone number configurations paginated.
- [Create a list of phone number configurations](https://developers.telnyx.com/api-reference/porting-orders/create-a-list-of-phone-number-configurations.md): Creates a list of phone number configurations.
- [List LOA configurations](https://developers.telnyx.com/api-reference/porting-orders/list-loa-configurations.md): List the LOA configurations.
- [Create a LOA configuration](https://developers.telnyx.com/api-reference/porting-orders/create-a-loa-configuration.md): Create a LOA configuration.
- [Retrieve a LOA configuration](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-loa-configuration.md): Retrieve a specific LOA configuration.
- [Update a LOA configuration](https://developers.telnyx.com/api-reference/porting-orders/update-a-loa-configuration.md): Update a specific LOA configuration.
- [Delete a LOA configuration](https://developers.telnyx.com/api-reference/porting-orders/delete-a-loa-configuration.md): Delete a specific LOA configuration.
- [Preview a LOA configuration](https://developers.telnyx.com/api-reference/porting-orders/preview-a-loa-configuration.md): Preview a specific LOA configuration.
- [Preview the LOA configuration parameters](https://developers.telnyx.com/api-reference/porting-orders/preview-the-loa-configuration-parameters.md): Preview the LOA template that would be generated without need to create LOA configuration.
- [Download a porting order loa template](https://developers.telnyx.com/api-reference/porting-orders/download-a-porting-order-loa-template.md): Download a porting order loa template
- [List additional documents](https://developers.telnyx.com/api-reference/porting-orders/list-additional-documents.md): Returns a list of additional documents for a porting order.
- [Create a list of additional documents](https://developers.telnyx.com/api-reference/porting-orders/create-a-list-of-additional-documents.md): Creates a list of additional documents for a porting order.
- [Delete an additional document](https://developers.telnyx.com/api-reference/porting-orders/delete-an-additional-document.md): Deletes an additional document for a porting order.
- [List porting order requirements](https://developers.telnyx.com/api-reference/porting-orders/list-porting-order-requirements.md): Returns a list of all requirements based on country/number type for this porting order.
- [List verification codes](https://developers.telnyx.com/api-reference/porting-orders/list-verification-codes.md): Returns a list of verification codes for a porting order.
- [Send the verification codes](https://developers.telnyx.com/api-reference/porting-orders/send-the-verification-codes.md): Send the verification code for all porting phone numbers.
- [Verify the verification code for a list of phone numbers](https://developers.telnyx.com/api-reference/porting-orders/verify-the-verification-code-for-a-list-of-phone-numbers.md): Verifies the verification code for a list of phone numbers.
- [List action requirements for a porting order](https://developers.telnyx.com/api-reference/porting-orders/list-action-requirements-for-a-porting-order.md): Returns a list of action requirements for a specific porting order.
- [Initiate an action requirement](https://developers.telnyx.com/api-reference/porting-orders/initiate-an-action-requirement.md): Initiates a specific action requirement for a porting order.
- [List available carriers in the UK](https://developers.telnyx.com/api-reference/porting-orders/list-available-carriers-in-the-uk.md): List available carriers in the UK.
- [List all porting events](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-events.md): Returns a list of all porting events.
- [Show a porting event](https://developers.telnyx.com/api-reference/porting-orders/show-a-porting-event.md): Show a specific porting event.
- [Republish a porting event](https://developers.telnyx.com/api-reference/porting-orders/republish-a-porting-event.md): Republish a specific porting event.
- [List porting related reports](https://developers.telnyx.com/api-reference/porting-orders/list-porting-related-reports.md): List the reports generated about porting operations.
- [Create a porting related report](https://developers.telnyx.com/api-reference/porting-orders/create-a-porting-related-report.md): Generate reports about porting operations.
- [Retrieve a report](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-report.md): Retrieve a specific report generated.
- [List all porting activation jobs](https://developers.telnyx.com/api-reference/porting-orders/list-all-porting-activation-jobs.md): Returns a list of your porting activation jobs.
- [Retrieve a porting activation job](https://developers.telnyx.com/api-reference/porting-orders/retrieve-a-porting-activation-job.md): Returns a porting activation job.
- [Update a porting activation job](https://developers.telnyx.com/api-reference/porting-orders/update-a-porting-activation-job.md): Updates the activation time of a porting activation job.
- [List all exception types](https://developers.telnyx.com/api-reference/porting-orders/list-all-exception-types.md): Returns a list of all possible exception types for a porting order.
- [Retrieve the associated V1 sub_request_id and port_request_id](https://developers.telnyx.com/api-reference/porting-orders/retrieve-the-associated-v1-sub_request_id-and-port_request_id.md): Retrieve the associated V1 sub_request_id and port_request_id

### Number Portout

- [List portout requests](https://developers.telnyx.com/api-reference/number-portout/list-portout-requests.md): Returns the portout requests according to filters
- [Get a portout request](https://developers.telnyx.com/api-reference/number-portout/get-a-portout-request.md): Returns the portout request based on the ID provided
- [List all comments for a portout request](https://developers.telnyx.com/api-reference/number-portout/list-all-comments-for-a-portout-request.md): Returns a list of comments for a portout request.
- [Create a comment on a portout request](https://developers.telnyx.com/api-reference/number-portout/create-a-comment-on-a-portout-request.md): Creates a comment on a portout request.
- [List supporting documents on a portout request](https://developers.telnyx.com/api-reference/number-portout/list-supporting-documents-on-a-portout-request.md): List every supporting documents for a portout request.
- [Create a list of supporting documents on a portout request](https://developers.telnyx.com/api-reference/number-portout/create-a-list-of-supporting-documents-on-a-portout-request.md): Creates a list of supporting documents on a portout request.
- [Update Status](https://developers.telnyx.com/api-reference/number-portout/update-status.md): Authorize or reject portout request
- [List all port-out events](https://developers.telnyx.com/api-reference/number-portout/list-all-port-out-events.md): Returns a list of all port-out events.
- [Show a port-out event](https://developers.telnyx.com/api-reference/number-portout/show-a-port-out-event.md): Show a specific port-out event.
- [Republish a port-out event](https://developers.telnyx.com/api-reference/number-portout/republish-a-port-out-event.md): Republish a specific port-out event.
- [List eligible port-out rejection codes for a specific order](https://developers.telnyx.com/api-reference/number-portout/list-eligible-port-out-rejection-codes-for-a-specific-order.md): Given a port-out ID, list rejection codes that are eligible for that port-out
- [List port-out related reports](https://developers.telnyx.com/api-reference/number-portout/list-port-out-related-reports.md): List the reports generated about port-out operations.
- [Create a port-out related report](https://developers.telnyx.com/api-reference/number-portout/create-a-port-out-related-report.md): Generate reports about port-out operations.
- [Retrieve a report](https://developers.telnyx.com/api-reference/number-portout/retrieve-a-report.md): Retrieve a specific report generated.