Skip to main content

Port out events API

Porting out phone numbers is typically a multi-step, asynchronous process.

Numerous events (comments, status changes) will occur as the order is processed. Each of these events has an associated notification. Users can subscribe to these notifications to stay up to date on their orders. For more information, please visit our Port-out order notifications developer guide.

Now, you can use the Port Out Events API for further control and clarity over your porting orders. Specifically, you can:

  • View all events for your port out orders
  • Republish notifications for specific events

Note: if you are looking for the similar "Port In Events API", you can find that guide here.

List port out events

You can perform a GET v2/porting/events API request to view a list of port out events. A sample request is shown below:

Request:
curl --location --request GET 'https://api.telnyx.com/v2/portout/events' \
--header 'Authorization: ••••••'

Response:
{
"data": [
{
"id": "58467ede-6cd1-4fbf-88c6-4878ad3ab8be",
"record_type": "portout_event",
"updated_at": "2024-06-27T18:35:49.713300Z",
"payload": {
"carrier_name": "Test",
"id": "bfd076bd-5d4f-4336-930e-9f91f92922f0",
"phone_numbers": [
"+16508221563"
],
"spid": "073H",
"status": "pending",
"subscriber_name": null,
"user_id": "40d68ba2-0847-4df2-be9c-b0e0cb673e75"
},
"event_type": "portout.status_changed",
"portout_id": "bfd076bd-5d4f-4336-930e-9f91f92922f0",
"created_at": "2024-06-27T18:35:48.881639Z",
"available_notification_methods": [
"webhook",
"email"
],
"payload_status": "completed"
}
],
"meta": {
"page_number": 1,
"page_size": 25,
"total_pages": 1,
"total_results": 1
}
}

A couple of key components of that response are:

  • id = the id of the port out event
  • payload_status = indicates whether the webhook payload for the event has been generated. When created, the payload in the API response will be null. When completed, the payload in the API response will be fulfilled.
  • payload = provides additional details for the event. If the event_type supports webhooks, then payload is the webhook payload. If the event_type only supports email, then payload will be null.
  • available_notification_methods = this lists all possible notification methods for that particular event_type. In the example above, it is communicating that you could subscribe to webhook or email notifications for the porting_order.status_changed event_type. It does not indicate if you are currently subscribed to those notifications, and it does not indicate if those notifications were successfully emitted

Republish a port out event

If you would like to republish a particular port out event, perform a POST v2/portout/events/{{id}}/republish api request. The {{id}} in the URL path should be the id of the port out event you would like to be republished. A sample request is shown below:

curl --location --request POST 'https://api.telnyx.com/v2/portout/events/{{id}}/republish' \
--header 'Authorization: ••••••'

This endpoint will only republish notifications that you are currently subscribed to. For more information on how to set up port out event notifications, please visit our Port-out order notifications developer guide.

For email notifications, please be patient. These may take a few minutes to deliver again.

Republishing an event only republishes the notifications. A new event will not appear in the GET v2/portout/events API response.


Note: if you are looking for the similar "Port In Events API", you can find that guide here.

On this page