Skip to main content

Port In Events API

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

Numerous events (comments, splits, status changes) can 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-in order notifications developer guide.

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

  • View all events for your porting orders
  • Republish notifications for specific events

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

List port in events​

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

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

Response:
{
    "data": [
        {
            "id": "da7989d5-ffeb-47b5-9dc4-4a177a4094b0",
            "payload_status": "completed",
            "event_type": "porting_order.status_changed",
            "record_type": "porting_event",
            "updated_at": "2024-06-11T18:52:51.232176Z",
            "porting_order_id": "dcec50b4-55f2-4501-9fcd-f028ddba81d9",
            "created_at": "2024-06-11T18:52:47.972297Z",
            "payload": {
                "customer_reference": null,
                "id": "dcec50b4-55f2-4501-9fcd-f028ddba81d9",
                "status": {
                    "details": [
                        {
                            "code": "INVALID_SIGNATURE_ON_THE_LOA",
                            "description": "LOA must be signed with a wet signature and/or current signature provided is obstructed by Text."
                        }
                    ],
                    "value": "exception"
                },
                "support_key": "sr_6bc693",
                "updated_at": "2024-06-11T18:52:47.972299Z",
                "webhook_url": null
            },
            "available_notification_methods": [
                "webhook",
                "email"
            ]
        }
    ],
    "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 in 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 in event​

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

curl --location --request POST 'https://api.telnyx.com/v2/porting/events/da7989d5-ffeb-47b5-9dc4-4a177a4094b0/republish' \
--header 'Authorization: ••••••'

This endpoint will only republish notifications that you are currently subscribed to. For more information on how to set up port in event notifications, please visit our Port-in 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/porting/events API response.

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

On this page​