Phone ID - Identity attributes: Porting History

📘

NOTE:

To add this feature to your account, contact a Telesign expert. This feature is available for full-service accounts only.

The Porting History identity attribute allows you to find out when a phone number was ported and where it 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 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 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 identity attribute is not enabled

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

Porting History request parameters

ParameterTypeDescription
addonsobjectYou must have your Technical Account Manager enable this feature for use. This parameter allows you to receive information returned from your enabled identity attributes.
addons.porting_historyobjectInclude this parameter to initiate use of the Porting History identity attribute.
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 and is randomly generated by Telesign.
phone_typestringOne of the 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 previous 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 numeric code indicating the status of your request.
porting_history.status.descriptionstringDescription of the status code.