--- title: Verify Device Ownership description: 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. component: pingone-api page_id: pingone-api:verify:verify-device-ownership-verification canonical_url: https://developer.pingidentity.com/pingone-api/verify/verify-device-ownership-verification.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service verify-device-ownership-request-data-model: Verify device ownership request data model verify-device-ownership-response-data-model: Verify device ownership response data model --- # 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](#verify-device-ownership-response-data-model\)). You can also include Device Ownership Verification in your [Verify Policy](verify-policy.html). ## 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](../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../platform/roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](../platform/group-role-assignments/group-role-assignments.html). * [User Role Assignments](../platform/users/user-role-assignments.html). Refer to [Roles Management](../platform/roles.html) 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`. |