Porting llms-full.txt

Complete machine-readable documentation content for Porting (Numbers) for AI agents and LLMs

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://developers.telnyx.com/development/llms/numbers-porting-llms-txt.md

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.

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 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 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 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 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 for details on retrieving available windows and setting your preferred date.

Step 4: Submit the port order

Use the Submit porting order endpoint 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 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 and port-in events guide.

Comments

Comments allow you to communicate directly with Telnyx Porting Operations during the porting process. Use the Create comment endpoint to send messages or respond to requests from the porting team.

Monitor your port orders for new comments using the List comments endpoint. 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 - View and fulfill regulatory requirements on your port orders.
• Allowed FOC dates - Request and set a specific date for your port order to complete.
• On-demand activations - Take control of your port order with FastPort on-demand activations.
• 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.

The value you provide depends on the requirement type:

• Document: Provide a document ID from the Documents API.
• Textual: Provide a string value that meets the acceptance criteria.
• Address: Provide an address ID from the Addresses API.

For detailed fulfillment instructions for each type, see the regulatory requirements guide.

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

---

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 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 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 to request cancellation.

Step 2: Monitor cancellation status

You can check the status of the cancellation using the GET /v2/porting_orders/{id} endpoint.

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.

---

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.

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

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 or Retrieve a porting activation job endpoint 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 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:

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

{
  "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

{
  "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).

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

{
  "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 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:

{
  "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:

{
  "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
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:

{
      "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, 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 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 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.

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, 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 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 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
Remove an associated phone number	DELETE /v2/porting_orders/{id}/associated_phone_numbers/{associated_phone_number_id}

---

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 [phone], extensions might include [phone] or [phone].

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 [phone] and you want to activate only extension [phone]:

• Set extension_range to 0-9 (covering [phone] through [phone]).
• Set activation_ranges to 4-4 (activating only [phone]).

For multiple non-contiguous extensions like [phone], [phone], [phone], and [phone]:

• 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 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 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 response, but extended numbers do not. To view extensions attached to a porting order, use the List all phone number extensions endpoint.

Delete extensions

To remove extensions from a porting order before submission, use the 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 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} 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} 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 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 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 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 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 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 to list your bundles, or view them on the Bundles page 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.

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 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 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 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 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 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, 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 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 endpoint to list all port-out orders on your account, or use the GET /v2/portouts/:id 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 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 endpoint. The available rejection codes vary depending on the phone numbers in the order.

Then, use the PATCH /v2/portouts/:id/rejected-pending 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 guide.

To view and republish port-out events programmatically, see the Port-out events API 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

{
  "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, 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 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 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.

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: Runs a portability check, returning the results immediately.

Porting Orders

• List all porting orders: Returns a list of your porting order.
• Create a porting order: Creates a new porting order object.
• Retrieve a porting order: Retrieves the details of an existing porting order.
• Edit a porting order: Edits the details of an existing porting order.
• Delete a porting order: Deletes an existing porting order. This operation is restrict to porting orders in draft state.
• Submit a porting order.: Confirm and submit your porting order.
• Cancel a porting order: Cancel a porting order
• Activate every number in a porting order asynchronously.: Activate each number in a porting order asynchronously. This operation is limited to US FastPort orders only.
• Share a porting order: 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: Returns a list of allowed FOC dates for a porting order.
• List all comments of a porting order: Returns a list of all comments of a porting order.
• Create a comment for a porting order: Creates a new comment for a porting order.
• List all porting phone numbers: Returns a list of your porting phone numbers.
• List all associated phone numbers: 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: 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: Deletes an associated phone number from a porting order.
• List all phone number blocks: Returns a list of all phone number blocks of a porting order.
• Create a phone number block: Creates a new phone number block.
• Delete a phone number block: Deletes a phone number block.
• List all phone number extensions: Returns a list of all phone number extensions of a porting order.
• Create a phone number extension: Creates a new phone number extension.
• Delete a phone number extension: Deletes a phone number extension.
• List all phone number configurations: Returns a list of phone number configurations paginated.
• Create a list of phone number configurations: Creates a list of phone number configurations.
• List LOA configurations: List the LOA configurations.
• Create a LOA configuration: Create a LOA configuration.
• Retrieve a LOA configuration: Retrieve a specific LOA configuration.
• Update a LOA configuration: Update a specific LOA configuration.
• Delete a LOA configuration: Delete a specific LOA configuration.
• Preview a LOA configuration: Preview a specific LOA configuration.
• Preview the LOA configuration parameters: Preview the LOA template that would be generated without need to create LOA configuration.
• Download a porting order loa template: Download a porting order loa template
• List additional documents: Returns a list of additional documents for a porting order.
• Create a list of additional documents: Creates a list of additional documents for a porting order.
• Delete an additional document: Deletes an additional document for a porting order.
• List porting order requirements: Returns a list of all requirements based on country/number type for this porting order.
• List verification codes: Returns a list of verification codes for a porting order.
• Send the verification codes: Send the verification code for all porting phone numbers.
• Verify the verification code for a list of phone numbers: Verifies the verification code for a list of phone numbers.
• List action requirements for a porting order: Returns a list of action requirements for a specific porting order.
• Initiate an action requirement: Initiates a specific action requirement for a porting order.
• List available carriers in the UK: List available carriers in the UK.
• List all porting events: Returns a list of all porting events.
• Show a porting event: Show a specific porting event.
• Republish a porting event: Republish a specific porting event.
• List porting related reports: List the reports generated about porting operations.
• Create a porting related report: Generate reports about porting operations.
• Retrieve a report: Retrieve a specific report generated.
• List all porting activation jobs: Returns a list of your porting activation jobs.
• Retrieve a porting activation job: Returns a porting activation job.
• Update a porting activation job: Updates the activation time of a porting activation job.
• List all exception types: Returns a list of all possible exception types for a porting order.
• Retrieve the associated V1 sub_request_id and port_request_id: Retrieve the associated V1 sub_request_id and port_request_id

Number Portout

• List portout requests: Returns the portout requests according to filters
• Get a portout request: Returns the portout request based on the ID provided
• List all comments for a portout request: Returns a list of comments for a portout request.
• Create a comment on a portout request: Creates a comment on a portout request.
• List supporting documents on a portout request: List every supporting documents for a portout request.
• Create a list of supporting documents on a portout request: Creates a list of supporting documents on a portout request.
• Update Status: Authorize or reject portout request
• List all port-out events: Returns a list of all port-out events.
• Show a port-out event: Show a specific port-out event.
• Republish a port-out event: Republish a specific port-out event.
• List eligible port-out rejection codes for a specific order: Given a port-out ID, list rejection codes that are eligible for that port-out
• List port-out related reports: List the reports generated about port-out operations.
• Create a port-out related report: Generate reports about port-out operations.
• Retrieve a report: Retrieve a specific report generated.