Phone ID - Identity attributes: Breached Data

πŸ“˜

NOTE:

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

Use this identity attribute to check if a phone number or any associated Personal Identifiable Information (PII) was compromised in a recent data breach. This identity attribute flags phone numbers that have been involved in a recent data breach, which helps prevent synthetic identity fraud and account takeovers using stolen passwords and credentials. Accounts that belong to users impacted by recent data breaches are at additional risk of being targeted by fraudsters as the users' data might be accessible on the dark web.

Breached Data allows you to take extra steps to verify the legitimacy of an affected end user and strengthen their account integrity by prompting a password reset, confirming their identity using an MFA solution, or simply by locking their account temporarily.

Based on the phone number provided in the API request, Breached Data provides a true/false response (indicating whether the phone number is breached). For breached phone numbers, it provides the date of the data breach and lists the categories of other personally identifiable information (PII) that were compromised.

Examples

Request body

{
  "addons": {
    "breached_number_check": {}
  }
}

Response 1: Breach detected

When a number is breached, the breached_data property returns a list of the types of PII data that are compromised.

{
    "breached_number_check": {
        "phone_number_breached": True,
        "breach_date": "2017-05-25T00:00:00Z",
        "breached_data": ["username", "password", "email"],
        "status": {
            "code": 2800,
            "description": "Request successfully completed."
        }
    }
}

Response 2: Breach not detected

When no breach is detected, breached_data returns null.

{
    "breached_number_check": {
        "phone_number_breached": False,
        "breach_date": null,
        "breached_data": null,
        "status": {
            "code": 2800,
            "description": "Request successfully completed."
        }
    }
}

Response error examples

Breached Data returns the applicable error code and a description of the error for status.code when a request isn't successfully completed. The examples below are a few that you might see. See Error codes for a complete list of error codes. If error code 2806 is returned, please contact Customer Support Team to enable Breached Data.

Code 2802 is returned when there is an unexpected error. 2810 is included in the response when a provider returns an unrecognized response.

Response 3: Error - request processing timeout occurred

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

Response 4: Error - no breached_number_check information can be found

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

Response 5: Error - phone type not applicable

When the phone number is invalid, restricted, toll-free, or a pay phone number, code 2804 is returned.

{
    "breached_number_check": {
        "status": {
            "code": 2804,
            "description": "Phone number not applicable in breached_number_check add-on."
        }
    }
}

Breached data types

When Breached Data finds a breached phone number, breached_data returns a list of the types of PII data which were breached. The data itself is not returned - only the type of data. Depending on the region and any applicable regulations, these may include:

PropertyDescription
nameThe name associated with the breached phone number.
addressThe address associated with the breached phone number.
stateThe state associated with the breached phone number.
cityThe city associated with the breached phone number.
countyThe county, if applicable, associated with the breached phone number.
countryThe country associated with the breached phone number.
device_modelThe model of the mobile device associated with the breached phone number.
device_nameThe device name that is associated with the breached phone number.
dobThe date of birth of the person associated with the breached phone number.
ageThe age of the person associated with the breached phone number.
ip_addressesThe IP addresses associated with the breached phone number.
national_idThe national ID, if applicable, of the person associated with the breached phone number.
social_security_numberThe social security number, if applicable, of the person associated with the breached phone number.
emailThe email address associated with the breached phone number.
passwordThe password associated with the breached phone number.
password_plaintextThe password associated with the phone number, in plaintext.
usernameThe username associated with the breached phone number.