PhoneID API - Add-ons: Porting Status

The Porting Status add-on allows you to find out if a phone number was ported or not and what carrier currently has the number. The information you get in a response includes the current MCC (mobile country code) and the current MNC (mobile network code).

Example Request and Response for Porting Status

This section provides examples of a request with the porting status add-on and possible responses.

Porting Status Request

POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 08 Nov 2018 14:11:09 GMT
Content-Type: application/json 
{
    "addons": {
        "porting_status": {}
    }
}

Here is an example of a successful response body:

Porting Status Successful Response Body

{
  "porting_status": {
    "mcc_current": "310",
    "mnc_current": "01",
    "ported": true,
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

This is the response body when the request times out:

Porting Status Response Body for a Timeout

{
    "porting_status": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

Here is an example response body when the phone number is out of coverage. This means it is too far from a cellular antenna, in a restricted area that blocks signals, or it may be off.

Response Body When the Phone Number is Out of Coverage

{
  "porting_status": {
    "status": {
      "code": 2803,
      "description": "Phone number out of porting_status add-on coverage."
    }
  }
}

Porting Status Request Parameters

ParameterTypeDescription
addonsobjectYou must have you Technical Account Manager enable this feature for use. The addons parameter allows you to receive information returned from Contact, Contact Plus, Contact Match, or Number Deactivation, depending on which add-ons you enable. You receive add-on information back along with standard PhoneID information.
addons.porting_statusstringThis add-on allows you to find out whether or not a phone number was ported to a carrier and who the current carrier is based on the mobile country code (MCC) and mobile network code (MNC) returned in the response.

Porting Status Request Parameters

PropertyTypeDescription
reference_idstringA 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.
phone_typestringOne of the [phone type code](https://enterprise.telesign.com/docs/codes-languages-and-time-zones#section-phone-type-codes\).
descriptionstringText describing the phone type.
porting_statusobject
porting_status.mcc_currentstringThe mobile country code (MCC) for the current carrier associated with the device. The MNC is used in conjunction with the MCC to uniquely identify a carrier.
porting_status.mnc_currentstringThe mobile network code (MNC) for the current carrier associated with the device. The MNC is used in conjunction with the MCC to uniquely identify a carrier.
porting_status.portedbooleanPorted indicates whether the number was ported or not.
porting_status.statusobject
porting_status.status.codestringA status code describing the status of your request.
porting_status.status.descriptionstringDescription of the status code.

Did this page help you?