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