PingOne Platform APIs

Verify Device Ownership

With the Verify Device Ownership service, you can verify device ownership by comparison to thousands of databases for comprehensive coverage of US-based identities. The service returns match-level indicators for phone to name, email to name, and email to phone.

You can use POST {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/deviceOwnershipVerification to compare the unverified data submitted in the request body to the many databases and return data from the provider with indicators as described in (Verify device ownership response data model.

You can also include Device Ownership Verification in your Verify Policy.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Verify device ownership request data model

At least two of the following properties are required for US-based identities: name (or given_name and family_name), email, and phone.

In requirements, name takes precedence over given_name plus family_name. If given_name plus family_name is inconsistent with name, no error is reported because name is used.

Property Type Required Mutable Description

requirements

Object

Required

Mutable

Contains two or more objects with information to compare

requirements.email.value

String

Required/Optional

Immutable

Email address of the user

requirements.family_name.value

String

Required

Immutable

Family name of the user

requirements.given_name.value

String

Required

Immutable

Given name of the user

requirements.name.value

String

Required/Optional

Immutable

Full name of the user

requirements.phone.value

String

Required/Optional

Immutable

Mobile telephone number of the user

Verify device ownership response data model

If the input requirements are met, regardless of the validity of the values, errorcode returns SUCCESS.

In identityRisk.phone.indicators.phoneComp, each version of the phone compromise score is returned in a separate object with the version number incremented. For example, .phoneComp.1 contains the first version of the phone compromise score, .phoneComp.2 contains the second version of the phone compromise score, and so on.

Property Type Required Mutable Description

errorcode

String

N/A

Read-only

Result of request. Can be SUCCESS, GENERAL_FAILURE, CUSTOMER_RECORD_MISSING, DATA_UNAVAILABLE, TASK_REFUSED, TIMEOUT, SYSTEM_UNAVAILABLE, UNAUTHORIZED_REQUEST, INVALID_US_PHONE, BAD_PARAMETER, or OTHER_ERROR.

identityRisk

Object

N/A

Read-only

Detailed information about the device ownership risk assessment.

identityRisk.addressCurrent

String

N/A

Read-only

Confidence level of the current address match. Can be ADDRESS_IS_CURRENT, ADDRESS_IS_NOT_CURRENT, UNKNOWN, or INVALID_ADDRESS. However, because address is not accepted in the request body, this is always INVALID_ADDRESS.

identityRisk.addressToName

String

N/A

Read-only

Confidence level of the address to name match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.addressToPhone

Array

N/A

Read-only

Confidence level of the address to phone match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.correlationID

String

N/A

Read-only

A verify service-provided correlation identifier for the request.

identityRisk.email

Object

N/A

Read-only

Contains information about the email verification.

identityRisk.email.activeTenure

String

N/A

Read-only

Duration of active usage associated with the email. Can be NO_ACTIVITY_SEEN_OR_LONGEST_ACTIVE_STREAK_UNKNOWN, ACTIVE_FOR_LESS_THAN_12_CONSECUTIVE_MONTHS, ACTIVE_FOR_12_CONSECUTIVE_MONTHS, ACTIVE_FOR_13-24_CONSECUTIVE_MONTHS, or ACTIVE_FOR_MORE_THAN_24_CONSECUTIVE_MONTHS.

identityRisk.email.emailFound

String

N/A

Read-only

Indicates if the email was found in the TransUnion repository. Can be EMAIL_ADDRESS_NOT_FOUND_IN_TU_REPOSITORY or EMAIL_ADDRESS_FOUND_IN_TU_REPOSITORY.

identityRisk.email.firstActive

String

N/A

Read-only

Date of first activity associated with the email. Can be NO_ACTIVITY_SEEN_OR_DATE_OF_FIRST_ACTIVITY_IS_UNKNOWN, FIRST_ACTIVE_0-6_MONTHS_AGO, FIRST_ACTIVE_7-12_MONTHS_AGO, or FIRST_ACTIVE_OVER_12_MONTHS_AGO.

identityRisk.email.lastActive

String

N/A

Read-only

Date of last activity associated with the email. Can be NO_ACTIVITY_SEEN_OR_DATE_OF_LAST_ACTIVITY_IS_UNKNOWN, LAST_ACTIVE_0-6_MONTHS_AGO, LAST_ACTIVE_7-12_MONTHS_AGO, or LAST_ACTIVE_OVER_12_MONTHS_AGO.

identityRisk.email.validation

String

N/A

Read-only

Validation status of the email. Can be INVALID_DOMAIN, INVALID_SYNTAX, INVALID_ACCOUNT, PLACEHOLDER, UNKNOWN_ACCOUNT, or ACTIVE_ACCOUNT.

identityRisk.emailToAddress

String

N/A

Read-only

Confidence level of the email to address match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.emailToName

String

N/A

Read-only

Confidence level of the email to name match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.emailToPhone

Array

N/A

Read-only

Confidence level of the email to phone match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.identityVerification

Object

N/A

Read-only

Detailed information about the identity verification process.

identityRisk.identityVerification.
addressCurrent

String

N/A

Read-only

Confidence level of the current address match. Because address is not accepted in the request body, this is always INVALID_ADDRESS.

identityRisk.identityVerification.
addressToName

String

N/A

Read-only

Confidence level of the address to name match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.identityVerification.
addressToPhone

String[]

N/A

Read-only

Confidence level of the address to phone match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.identityVerification.
emailToAddress

String

N/A

Read-only

Confidence level of the email to address match. Because address is not accepted in the request body, this is always INVALID_OR_MISSING_INPUT.

identityRisk.identityVerification.
emailToName

String

N/A

Read-only

Confidence level of the email to name match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.identityVerification.
emailToPhone

String[]

N/A

Read-only

Confidence level of the email to phone match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.identityVerification.
phoneToFirstName

String[]

N/A

Read-only

Confidence level of the phone to first name match. Can be HIGH_CONFIDENCE_MATCH, LOWER_CONFIDENCE_MATCH, NO_LINK, INVALID_OR_MISSING_INPUT, or UNKNOWN_NO_DATA.

identityRisk.identityVerification.
phoneToName

String[]

N/A

Read-only

Confidence level of the phone to name match. Can be HIGH_CONFIDENCE_MATCH, LOWER_CONFIDENCE_MATCH, NO_LINK, INVALID_OR_MISSING_INPUT, or UNKNOWN_NO_DATA.

identityRisk.identityVerification.
unverifiedComponents

String

N/A

Read-only

Components that were not verified. Can be PHONE_ADDRESS_AND_EMAIL_NOT_LINKED_TO_NAME, PHONE_AND_ADDRESS_NOT_LINKED_TO_NAME, PHONE_AND_EMAIL_NOT_LINKED_TO_NAME, PHONE_LINKED_TO_NAME_EMAIL_AND_ADDRESS_NOT_LINKED, PHONE_NOT_LINKED_TO_NAME, EMAIL_NOT_LINKED_TO_NAME, ADDRESS_NOT_LINKED_TO_NAME, or NO_UNVERIFIED_COMPONENTS.

identityRisk.identityVerification.
verifiedComponents

String

N/A

Read-only

Components that were verified. Can be PHONE_ADDRESS_AND_EMAIL_LINKED_TO_NAME, PHONE_AND_ADDRESS_LINKED_TO_NAME, PHONE_AND_EMAIL_LINKED_TO_NAME, PHONE_LINKED_TO_NAME_EMAIL_AND_ADDRESS_LINKED, PHONE_LINKED_TO_NAME, EMAIL_LINKED_TO_NAME, ADDRESS_LINKED_TO_NAME, NO_VERIFIED_COMPONENTS.

identityRisk.phone

Object[]

N/A

Read-only

Contains detailed information about the phone verification.

identityRisk.phone.indicators

Object

N/A

Read-only

Contains indicators related to the phone verification.

identityRisk.phone.indicators.
phoneComp.1.decision

String

N/A

Read-only

Decision on whether the phone is compromised. Can be LOW_RISK, MEDIUM_RISK, or HIGH_RISK.

identityRisk.phone.indicators.
phoneComp.1

Object

N/A

Read-only

Contains the decision on whether the phone is compromised.

identityRisk.phone.indicators.
phoneComp

Object

N/A

Read-only

Contains indicators related to phone compromise.

identityRisk.phone.mvno

String

N/A

Read-only

Indicates if the phone is associated with a mobile virtual network operator (MVNO). Can be Y (yes) or N (no data to indicate MVNO). Only returned when techType is W (wireless).

identityRisk.phone.nameChange

Object

N/A

Read-only

Contains information about name changes associated with the phone.

identityRisk.phone.nameChange.
nameChange

String

N/A

Read-only

History of name changes. Can be NAME_CHANGE_HISTORY_UNKNOWN, NO_CHANGES_PHONE_NUMBER_FOUND_IN_TRANSUNION_DIRECTORY_BUT_NAME_HAS_NOT_CHANGED, CHANGED_IN_LAST_1_DAY, CHANGED_IN_LAST_2-3_DAYS, CHANGED_IN_LAST_4-5_DAYS, CHANGED_IN_LAST_6-30_DAYS, or CHANGED_IN_LAST_31-60_DAYS.

identityRisk.phone.nameChange.
nameChangeType

String

N/A

Read-only

Type of name change. Can be NAME_CHANGE_HISTORY_UNKNOWN, NO_CHANGES_PHONE_NUMBER_FOUND_IN_TRANSUNION_DIRECTORY_BUT_NAME_HAS_NOT_CHANGED, NAME_ADDED_TO_RECORD_WHERE_NAME_WAS_PREVIOUSLY_BLANK_OR_RECORD_WAS_NOT_AVAILABLE_IN_TU_DATABASE, NEW_NAME_IN_RECORD_THAT_DOES_NOT_MATCH_OLD_VALUE, or RECORD_PREVIOUSLY_CONTAINED_A_NAME_AND_NOW_NAME_CHANGED_TO_BLANK.

identityRisk.phone.nameChange.
numNameChange

String

N/A

Read-only

Number of times the name has been changed. Can be NAME_CHANGE_HISTORY_UNKNOWN, NO_CHANGES_DETECTED_WITHIN_60_DAYS, ONE_NAME_CHANGE_DETECTED_WITHIN_60_DAYS, TWO_NAME_CHANGES_DETECTED_WITHIN_60_DAYS, or THREE_OR_MORE_NAME_CHANGES_DETECTED_WITHIN_60_DAYS.

identityRisk.phone.nameChange.
source

String

N/A

Read-only

Source for the name change. Can be AUTHORITATIVE_DATA, NON-AUTHORITATIVE_DATA, or UNKNOWN.

identityRisk.phone.phoneType

String

N/A

Read-only

Type of phone. Can be BUSINESS, CONSUMER, or UNKNOWN.

identityRisk.phone.prepaid

String

N/A

Read-only

Indicates if the phone is prepaid. Can be Y (prepaid) or N (not prepaid or prepaid status unknown).

identityRisk.phone.spn

String

N/A

Read-only

Name of the Service Provider Network for the phone.

identityRisk.phone.techType

String

N/A

Read-only

Type of technology used by the phone. Can be WIRELESS, LANDLINE, or UNKNOWN.

identityRisk.phone.usage

Object

N/A

Read-only

Contains usage information about the phone.

identityRisk.phone.usage.
disconnectDate

String

N/A

Read-only

Indicates the disconnect date of the phone service in ISO 8601 YYYY-MM-DD format. Not returned if the phone has never been disconnected.

identityRisk.phone.usage.
serviceStartDate

String

N/A

Read-only

Indicates the start date of the phone service in ISO 8601 YYYY-MM format. Not returned if the data is unavailable.

identityRisk.phone.usage.
serviceTenure

String

N/A

Read-only

Indicates the tenure of the phone service. Can be ACTIVE_FOR_1_MONTH_OR_LESS, ACTIVE_FOR_2_MONTHS, ACTIVE_FOR_3_MONTHS, ACTIVE_FOR_BETWEEN_4-6_MONTHS, ACTIVE_FOR_BETWEEN_5-9_MONTHS, ACTIVE_FOR_BETWEEN_10-11_MONTHS, ACTIVE_FOR_12_MONTHS_OR_LONGER, INACTIVE_FOR_1_MONTH_OR_LESS, INACTIVE_FOR_2_MONTHS, INACTIVE_FOR_3_MONTHS, INACTIVE_FOR_BETWEEN_4-6_MONTHS, INACTIVE_FOR_BETWEEN_5-9_MONTHS, INACTIVE_FOR_BETWEEN_10-11_MONTHS, or INACTIVE_FOR_12+_MONTHS_OR_UNKNOWN.

identityRisk.phone.usage.
usage12mo

String

N/A

Read-only

Indicates the usage of the phone over the past 12 months. Can be DATA_UNAVAILABLE_OR_NO_USAGE_IN_THE_LAST_12_MONTHS, MINIMAL_USAGE, LIGHT_USAGE, MODERATE_USAGE, HEAVY_USAGE, or VERY_HEAVY_USAGE.

identityRisk.phone.usage.
usage2mo

String

N/A

Read-only

Indicates the usage of the phone over the past 2 months. Can be DATA_UNAVAILABLE_OR_NO_USAGE_IN_THE_LAST_2_MONTHS, MINIMAL_USAGE, LIGHT_USAGE, MODERATE_USAGE, HEAVY_USAGE, or VERY_HEAVY_USAGE.

identityRisk.phone.voip

Number

N/A

Read-only

Indicates the risk level if the phone is a voice over IP (VoIP) service or a traditional landline. Can be 1 (low risk VoIP or landline) or 2 (high risk VoIP).

identityRisk.phoneToFirstName

Array

N/A

Read-only

Confidence level of the phone to first name match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.phoneToName

Array

N/A

Read-only

Confidence level of the phone to name match. Can be INVALID_OR_MISSING_INPUT, NO_LINK, UNKNOWN_NO_DATA, LOWER_CONFIDENCE_MATCH, or HIGH_CONFIDENCE_MATCH.

identityRisk.useCase

String

N/A

Read-only

Always PingIdentity Verification.

nsr

String

N/A

Read-only

Provider’s identifier for the request.

transid

String

N/A

Read-only

Provider’s transaction identifier.

validationErrorMessage

String

N/A

Read-only

Description of the error when errorcode is not SUCCESS.