PhoneID API - Add-ons: Porting History

The Porting History add-on allows you to find out at what point and where a phone number was ported to. If a phone number is ported in the last 90 days from one carrier to another, the information you get in a response includes:

  • Current and previous carrier name
  • Current and previous MCC (mobile country code)
  • Current and previous MNC (mobile network code)
  • Current and previous phone type
  • The date the number was ported
  • The combination MCC and MNC uniquely identify a mobile network operator (carrier)
  • Porting History add-on information is available for US phone numbers ported in the last 90 days

Example Request and Response for Porting History

POST Request for Porting History

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_history": {
        "past_x_days": 10
    }
  }
}

Response Body for Porting History

{
  "porting_history": {
    "carrier_current": "Sprint Spectrum, L.P.",
    "carrier_previous": "US Cellular Corp.",
    "mcc_carrier_current":"310",
    "mcc_carrier_previous":"310",
    "mnc_carrier_current": "120",
    "mnc_carrier_previous": "160",
    "phone_type_current": "MOBILE",
    "phone_type_previous": "MOBILE",
    "port_date": "2018-08-26T16:33:19Z",
    "number_of_portings": "1",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
      }
    }
  }
}

Response Body When a Phone Number Was Not Ported in the Last 90 Days

{
  "porting_history": {
    "status": {
      "code": 2805,
      "description": "No porting_history add-on information for phone number."
    }
  }
}

Response Body When Porting History Add-on is Not Enabled

{
  "porting_history": {
    "status": {
      "code": 2806,
      "description": "porting_history add-on is not enabled."
    }
  }
}

Porting History 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_historyobjectThis add-on allows you to find out at what point and where a phone number was ported to. If a phone number was ported in the last 90 days from one carrier to another, available details are provided in the response.
addons.porting_history.past_x_daysstringHow many days back the service will go to check for whether the phone number was ported.

Porting History Response

PropertyTypeDescriptionExample
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_historyobject
porting_history.carrier_currentstringThe name of the current carrier for the phone number you provided.
porting_history.carrier_previousstringThe name of the carrier before the phone number was ported to the new carrier.
porting_history.mcc_carrier_currentstringThe mobile country code for the current carrier. This field can include multiple values for MCC.
porting_history.mcc_carrier_previousstringThe mobile country code for the previous carrier. This field can include multiple values for MCC.
porting_history.mnc_carrier_currentstringThe mobile network code for the current carrier. This field can include multiple values for MNC.
porting_history.mnc_carrier_previousstringThe mobile network code for the previous carrier. This field can include multiple values for MNC.
porting_history.phone_type_currentstringThe phone type currently associated with the phone number.
porting_history.phone_type_previousstringThe phone type previously associated with the phone number.
porting_history.port_datestringThe date the phone number was ported to a new carrier.
porting_history.number_of_portingsstringThe number of times the phone number was ported during the time window you specified with past_x_days in your request.1
porting_history.statusobject
porting_history.status.codestringA status code describing the status of your request.
porting_history.status.descriptionstringDescription of the status code.

Did this page help you?