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

For US-based identities:

  • phone.value is required.

  • Either name.value or given_name.value plus family_name.value is required.

  • email.value is optional.

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

Property Type Required Mutable Description

requirements

Object

Required

Mutable

Contains two or more objects with information to compare

requirements.email.value

String

Optional

Immutable

Email address of the user

requirements.family_name.value

String

Required/Optional

Immutable

Family name of the user

requirements.given_name.value

String

Required/Optional

Immutable

Given name of the user

requirements.name.value

String

Required/Optional

Immutable

Full name of the user

requirements.phone.value

String

Required

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.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.

Verify device ownership verification errors

In addition to the general error codes, device ownership verification operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /environments/{envID}/users/{userID}/deviceOwnershipVerification request supplies a requirement entry that is null or violates the requirement value rules

Details: cannot be null for a null requirement entry, value must be non-empty or null for a blank value, options must be non-empty or null for an empty options array, option entries must not be null or empty for a null or blank option, options cannot contain duplicates for duplicate options, must set either value, options, or expression when none is set, cannot set more than one of value, options, or expression when two or more are set, or expression must be non-empty or null for a blank expression (a blank requirement map key also triggers a validation error)

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A request omits the requirements object or supplies an empty object, supplies an unparseable or non-US country_code, or omits the required combination of phone plus either name or given_name and family_name

Details: Device ownership verification requirement is null or Device ownership verification requirement is empty with target deviceOwnershipVerification, Invalid country_code. Must be a valid ISO-3166 country value with target deviceOwnershipVerification.countryCode, Country code is not supported for device ownership verification with target deviceOwnershipVerification, or:

Device ownership verification requirement is missing. Expected requirements: phone + (name OR given_name + family_name) Provided keys: <keys>

with target deviceOwnershipVerification.requirements

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A request supplies email with an invalid address or phone with an invalid number, or supplies multiple values for a requirement

Details: invalid email address with target email, invalid phone number with target phone, or transunion requirement cannot have multiple values with target requirements.<key>

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: The verification provider returns no usable response for the request

Details: Device ownership provider is unavailable. Please retry later. with target deviceOwnershipVerification

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The environment does not have the device ownership feature flag enabled, or the environment is not licensed for device reputation scoring

Details: Device ownership verification feature flag is unavailable with target deviceOwnershipVerification or You are not licensed to make this request. with target deviceOwnershipVerification

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the idverifications:create:deviceOwnershipVerification permission, or the actor is authorized for the environment but not for the target user, the user’s population, or a group containing the user

Details: None

404

NOT_FOUND

None

Message: environment could not be found or user could not be found

When and details

When: The envID path parameter references an environment that does not exist, or the userID path parameter references a user that does not exist in the environment

Details: None