PingOne Platform APIs

Verify Policies

With verify policies, you can:

  • Configure what is required to verify a user.

  • Configure parameters for verification, such as the number of one-time password (OTP) attempts and OTP expiration.

You can create as many verify policies as needed to satisfy every verification scenario.

You must have the role of an Identity Data Admin in your environment to perform verify policy requests.

Verify policies can perform any of ten checks:

  • Government identity document - Validate a government-issued identity document, which includes a photograph, and can optionally compare biographic data extracted from the government-issued identity document to biographic data provided by the client from their records

  • AAMVA - For US-based government identity documents, you can enable system of record verification, using American Association of Motor Vehicle Administrators(AAMVA) Driver’s License Data Verification (DLDV, for environments in the North America region (licensed separately) on the governmentID configuration object. This is an option to government identity document verification.

  • Aadhaar - For India-based government Aadhaar documents, you can enable system of record verification, using Unique Identification Authority of India (UIDAI), of the resident’s unique identification (UID) number, termed Aadhaar. The resident submits images of their Aadhaar card, the UID, and a selfie, and must successfully respond to a one-time passcode (OTP) sent to the mobile phone linked to their Aadhaar account. This is an option to government identity document verification. If Aadhaar is enabled, the verify policy must have facial comparison REQUIRED. If Aadhaar is enabled and initial evaluation of the submitted document indicates an Aadhaar document, Veriff is the provider irrespective of the governmentId.provider object.

  • Facial comparison - Compare a self-image to a reference photograph, such as on a government ID or previously verified photograph

  • Liveness - Inspect a self-image for evidence that the subject is alive and not a representation, such as a photograph or mask, and that the image is not an injection attack, such as a 3D rendering or deep fake

  • Data based identity verification - For US-based identities (licensed separately) and select non-US-based identities (licensed separately by group), you can compare first name, last name, current addresses, Social Security or national identification number, date of birth, and phone number to thousands of databases and hundreds of alerting systems

  • Identity record matching - Compare submitted biographic data (address, birth date, full name, given name, or family name) to an identity record

  • Email - Receive a one-time password (OTP) on an email address and return the OTP to the service

  • Phone - Receive a one-time password (OTP) on a mobile phone and return the OTP to the service

  • Voice (deprecated) - Compare a voice recording to a previously submitted reference voice recording

  • Credentials - Verify a presented digital credential

A verify policy defines which of the ten checks are performed for a verification transaction and configures the parameters of each check. The checks can be either required or optional. All checks are performed for every document type received regardless of whether any check fails. If a type is optional, then the transaction can be processed with or without the documents for that type. If the documents are provided for that type and the optional type verification fails, it will not cause the entire transaction to fail.

Injection attack detection check (IAD) is performed automatically when liveness check is required, after the liveness check is performed. When face comparison is required or both face comparison and liveness are required, the following rules apply:

  1. If face comparison and liveness are required: Face comparison check is performed and liveness check is performed then IAD is performed. If data collection only is set, face comparison and liveness checks are skipped and only IAD is performed.

  2. If face comparison is required and liveness is not required: Face comparison check is performed and, if successful, IAD is performed regardless of the state of data collection only.

  3. If face comparison is not required and liveness is required: Liveness check is performed then IAD is performed. If data collection only is set liveness checks is skipped and IAD is performed.

Available to a verify policy for any of the checks is the optional data collection only mode, when dataCollectionOnly is set to true (found in the transaction configuration object). In data collection only mode, the user submits all documents defined by the policy, but the service verifies none of them. Once submitted, you can retrieve the documents with Read All Verification Documents or Read One Verification Document.

You assign one verify policy as the default policy. When you create a verification transaction, a verify policy identifier is preferred, but not required. If you create a verification transaction without a policy identifier, the default policy is applied. You cannot delete a policy set as the default policy, you must first assign a different policy as the default and then delete this policy. Use the Update Verify Policy request to change the default policy or use the Create Verify Policy to create a new default policy by setting its default to true. The initial default policy, provided by PingOne Verify, performs government identity document, facial comparison, and liveness checks.

Verify policies also permit voice enrollment (deprecated). Voice enrollment requires a verify policy that has enrollment set to true. When you prepare a voice enrollment, you Create Verify Transaction that references that verify policy with enrollment set to true. Subsequent voice verification requires a verify policy that has enrollment set to false. When you prepare a voice verification, you Create Verify Transaction that references that verify policy with enrollment set to false.

Verify policy data model

Property Type Required? Mutable? Description

createdAt

String

N/A

Read-only

Date and time the verify policy was created

dataBasedIdentityVerification

Object

Optional

Mutable

dataBasedIdentityVerification configuration object

default

Boolean

Optional

Mutable

Required as true to set this verify policy as the default policy for the environment; otherwise optional and defaults to false

dataBasedIdentityVerification

Object

Optional

Mutable

dataBasedIdentityVerification configuration object

description

String

Optional

Mutable

Description displayed in PingOne Admin UI, 1-1024 characters

email

Object

Optional

Mutable

email and phone configuration object

environment.id

String

Required

Immutable

Ping environment identifier (UUID) for user

facialComparison

Object

Optional

Mutable

facialComparison configuration object

governmentId

Object

Optional

Mutable

governmentID configuration object

id

String

N/A

Read-only

Policy identifier (UUID)

identityRecordMatching

Object

Optional

Mutable

identityRecordMatching configuration object

liveness

Object

Optional

Mutable

liveness configuration object

name

String

Required

Mutable

Name displayed in PingOne Admin UI

phone

Object

Optional

Mutable

email and phone configuration object

transaction

Object

Optional

Mutable

transaction configuration object

updatedAt

String

N/A

Read-only

Date and time the verify policy was updated. Can be null.

voice (deprecated)

Object

Optional

Mutable

voice configuration object

governmentID configuration object

The GOVERNMENT_ID configuration object includes BIOGRAPHIC_MATCHING in the policy (if biographic data is provided when the client creates a verify transaction), but results are returned separately in Verification Metadata.

Property Type Required? Mutable? Description

aadhaar

Object

Optional

Mutable

Aadhaar configuration

aadhaar.enabled

Boolean

Optional

Mutable

Whether Aadhaar verification is enabled or not

aadhaar.otp

Object

Optional

Mutable

Aadhaar one-time password (OTP) configuration

aadhaar.otp.
deliveries

Object

Required

Mutable

OTP delivery configuration

aadhaar.otp.
deliveries.
coolDown

Object

Required

Mutable

Cooldown (waiting period between OTP deliveries) configuration

aadhaar.otp.
deliveries.
coolDown.
duration

Integer

Required

Mutable

Cooldown duration configuration. Can be 60-1800 seconds (1-30 minutes)

aadhaar.otp.
deliveries.
coolDown.
timeUnit

String

Required

Mutable

Time unit of cooldown duration: SECONDS or MINUTES

aadhaar.otp.
deliveries.
count

Integer

Required

Mutable

Maximum number of OTP deliveries. Must be 1 to 3.

failExpiredId

Boolean

Optional

Mutable

Whether the Government ID verification fails when the document is expired

inspectionType

String

Optional

Mutable

Determine whether document authentication is automated, manual, or possibly both. Can be AUTOMATIC, MANUAL, or STEP_UP. Refer to notes following this table.

provider.auto

String

Optional

Mutable

Provider to use for the automatic verification service. Can be MITEK (the default) or VERIFF.

provider.manual

String

Optional

Mutable

Provider to use for the manual verification service. Can be MITEK.

retry.attempts

Integer

Optional

Mutable

Number of retries permitted when submitting images. Must be 0 (no retries permitted) to 3.

verify

String

Required

Mutable

Controls if Government ID verification is REQUIRED, OPTIONAL, or DISABLED

verifyAamva

Boolean

Optional

Mutable

Whether AAMVA DLDV verification is enabled for supported driver licenses

Options for inspectionType are:

  • AUTOMATIC invokes automated identification inspection only

  • MANUAL invokes manual identification inspection only (additional license required)

  • STEP_UP invokes automated identification inspection and, if that fails, invokes manual identification inspection (additional license required)

If verify is set to DISABLED, inspectionType is optional and ignored if used.

If inspectionType is not used, it defaults to the highest option available to the license capabilities in your environment. Similarly, availability of the options depend on the license capabilities of your environment. For example, if your environment is only licensed for automated identification inspection, then MANUAL and STEP_UP will not be available.

facialComparison configuration object

If Aadhaar is enabled in the GOVERNMENT_ID configuration object, the FACIAL_COMPARISON configuration object must have verify set to REQUIRED.

Property Type Required? Mutable? Description

threshold

String

Required

Mutable

Threshold for successful facial comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

verify

String

Required

Mutable

Controls if facial comparison is REQUIRED, OPTIONAL, or DISABLED

liveness configuration object

The LIVENESS configuration object includes INJECTION_DETECTION in the policy, but results are returned separately in Verification Metadata.

Property Type Required? Mutable? Description

retry.attempts

Integer

Optional

Mutable

The number of times a user can retake a selfie if prior attempt fails due to photo quality issues. Possible values for selfie retry attempts are 0-3.

threshold

String

Required

Mutable

Threshold for successful facial comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

verify

String

Required

Mutable

Controls if liveness check is REQUIRED, OPTIONAL, or DISABLED

identityRecordMatching configuration object

If governmentId.verify is DISABLED, then identity record matching is disabled. To enable identity record matching, at least one field must be defined with a threshold. If identity record matching is enabled and biographic data is provided when the client creates a verify transaction, results are returned separately in Verification Metadata.

Property Type Required? Mutable? Description

address

String

Optional

Mutable

Address of the user.

address.fieldRequired

Boolean

Required

Mutable

Whether the field is required or not

address.threshold

String

Required

Mutable

Threshold for successful address comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

birth_date

String

Optional

Mutable

Birth date of the user.

birth_date.fieldRequired

Boolean

Required

Mutable

Whether the field is required or not

birth_date.threshold

String

Required

Mutable

Threshold for successful birth date comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

family_name

String

Optional

Mutable

Family name of the user.

family_name.fieldRequired

Boolean

Required

Mutable

Whether the field is required or not

family_name.threshold

String

Required

Mutable

Threshold for successful family name comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

given_name

String

Optional

Mutable

Given name of the user.

given_name.fieldRequired

Boolean

Required

Mutable

Whether the field is required or not

given_name.threshold

String

Required

Mutable

Threshold for successful given name comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

name

String

Optional

Mutable

Full name of the user.

name.fieldRequired

Boolean

Required

Mutable

Whether the field is required or not

name.threshold

String

Required

Mutable

Threshold for successful full name comparison. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions).

dataBasedIdentityVerification configuration object

Declaring a dataBasedIdentityVerification configuration object indicates that DATA_BASED_IDENTITY_VERIFICATION is enabled. To disable, do not include a dataBasedIdentityVerification object.

To include DATA_BASED_IDENTITY_VERIFICATION in a policy, at least one verification type is required, such as PHONE or GOVERNMENT_ID. If a policy has only DATA_BASED_IDENTITY_VERIFICATION and GOVERNMENT_ID, then IDENTITY_RECORD_MATCHING is also required. If GOVERNMENT_ID and IDENTITY_RECORD_MATCHING are both required, comparison between GOVERNMENT_ID personally identifiable information (PII) and DATA_BASED_IDENTITY_VERIFICATION PII is returned in the IDENTITY_RECORD_MATCHING results.

if DATA_BASED_IDENTITY_VERIFICATION is required in a verify policy, and phone is in the transaction requirements, then phone is required in the verify policy.

IDA is updated when DATA_BASED_IDENTITY_VERIFICATION succeeds. If both GOVERNMENT_ID and DATA_BASED_IDENTITY_VERIFICATION are verified, IDA verified_claims.check_details have separate sections for each.

Verification checks are performed in this order:

  • EMAIL and PHONE verification are performed before DATA_BASED_IDENTITY_VERIFICATION, if either fails, DATA_BASED_IDENTITY_VERIFICATION is not performed

  • DATA_BASED_IDENTITY_VERIFICATION is performed when submitting documents for other verification types

  • DATA_BASED_IDENTITY_VERIFICATION, GOVERNMENT_ID, LIVENESS, and FACIAL_COMPARISON are verified together, if DATA_BASED_IDENTITY_VERIFICATION fails, the other tests are still performed

  • Other verification types are performed after DATA_BASED_IDENTITY_VERIFICATION, therefore failure of any of those does not affect DATA_BASED_IDENTITY_VERIFICATION

For US-based identities, the service requires at minimum for verification either name (or given_name and family_name) and national_id_number, which is a Social Security Number, or name (or given_name and family_name) and birth_date.

If only DATA_BASED_IDENTITY_VERIFICATION is needed, use the standalone Verify Data Based Identity Verification endpoint.
Property Type Required? Mutable? Description

threshold

String

Optional

Mutable

Threshold for successful data based identity verification. Can be LOW, MEDIUM, or HIGH (for which PingOne Verify uses industry and vendor recommended definitions) and defaults to MEDIUM.

Groups for identities outside the US

You can use data-based identity verification for identities from countries included in this table. Each group is licensed and priced separately. For countries appearing more than once, the parenthetic clause identifies the data source included in that group for that country.

Group Countries Included

I

Australia (DVS only) [AU], Cambodia [KH], China [CN], India [IN}, Indonesia [ID], Malaysia [MY], Philippines [PH], Thailand [TH], Brazil [BR], Mexico [MX], Sweden [SE]

II

Canada (excluding FINTRAC) [CA], Australia [AU], New Zealand [NZ], Argentina [AR], Chile [CL], Colombia [CO], Peru [PE], France [FR], Belgium [BE], Italy [IT], United Kingdom [GB], Netherlands [NL], Spain [ES], Nigeria [NG], Morocco [MA]

III

Hong Kong [HK], Denmark [DK], Germany [DE]

IV

Greece [GR], Ireland [IE], Czech Republic [CZ], Slovakia [SK], Finland [FI], Norway [NO], Poland [PL], and Canada (FINTRAC only) [CA]

V

Austria [AT], and Switzerland [CH]

email and phone configuration object

Property Type Required? Mutable? Description

createMfaDevice

Boolean

Optional

Mutable

When enabled, PingOne Verify registers the email address or phone number with PingOne MFA as a verified MFA device

otp

Object

Optional

Mutable

SMS/Voice/Email one-time password (OTP) configuration

otp.
attempts

Object

Required

Mutable

OTP attempts configuration

otp.
attempts.
count

Integer

Required

Mutable

Maximum number of attempts to type the OTP

otp.
deliveries

Object

Required

Mutable

OTP delivery configuration

otp.
deliveries.
coolDown

Object

Required

Mutable

Cooldown (waiting period between OTP deliveries) configuration

otp.
deliveries.
coolDown.
duration

Integer

Required

Mutable

Cooldown duration configuration. Can be 0-1800 seconds (0-30 minutes)

otp.
deliveries.
coolDown.
timeUnit

String

Required

Mutable

Time unit of cooldown duration: SECONDS or MINUTES

otp.
deliveries.
count

Integer

Required

Mutable

Maximum number of OTP deliveries

otp.
lifeTime

Object

Required

Mutable

The length of time for which the OTP is valid

otp.
lifeTime.
duration

Integer

Required

Mutable

OTP duration configuration. Can be 60-1800 seconds (1-30 minutes).

otp.
lifeTime.
timeUnit

String

Required

Mutable

Time unit of OTP duration configuration: SECONDS or MINUTES

otp.
notification

Object

Required

Mutable

OTP notification template configuration; for more information about templates, refer to Notifications Templates

otp.
notification.
templateName

String

Required

Mutable

Name of the template to use to pass a one-time passcode; must be email_phone_verification

otp.
notification.
variantName

String

Optional

Mutable

Name of the template variant to use to pass a one-time passcode

verify

String

Required

Mutable

Controls if email or phone verification is REQUIRED, OPTIONAL, or DISABLED

The notification.variantName in the email and phone configuration objects can define a variant for the email_phone_verification notification submitted in notification.templateName, if needed. After receipt of a Create Verify Transaction request, the verification service uses an email_phone_verification notification template to send notice of the action taken to the user via email or SMS text.

A policy-specific locale cannot be specified for the email_phone_verification notification. The notification uses the user’s preferred language or, if the user has no preferred language, the default language of the environment.

transaction configuration object

In the verify transaction response is expiresAt. Transactions do not allow users an unlimited amount of time to submit verification data and complete the verify transaction. If the verify transaction is not completed before the expiresAt date and time, the transaction fails. If all required documents are collected but are still being processed when expiresAt is reached, document processing continues and the transaction either passes or fails based on the processing result. The default verify transaction timeout is 30 minutes from transaction creation.

Furthermore, data collection is also time-constrained. (Data collected, such as the images of documents and images of the user ("selfies"), are required by the verification service.) Data collection time starts when the user initiates data collection using PingOne Verify web or native SDK. If required data are not submitted by the lesser of the data collection timeout and the time remaining before expiresAt, the transaction fails. The default data collection timeout is 15 minutes from the start of data collection.

To understand the timeouts, particularly the data collection timeout, an example may help. Let us say that the verify transaction timeout is 30 minutes and the data collection timeout is 15 minutes. If the user does not begin data collection for 18 minutes, the data collection timeout becomes 12 minutes - the lesser of the data collection timeout (15 minutes) and the remaining time before expiresAt (12 minutes).

You can create a new verify policy or update an existing verify policy to use different timeouts.

Property Type Required? Mutable? Description

authenticationMode

Boolean

Optional

Mutable

When true, web verify and apps using the PingOne Verify Native SDKs do not show the instructional pages when verifying; defaults to false

dataCollection

Object

Optional

Mutable

Object for data collection timeout definition

dataCollection.
timeout

Object

Required

Mutable

Object for data collection timeout

dataCollection.
timeout.
duration

Integer

Required

Mutable

Length of time before data collection timeout expires. Can be 0-1800 seconds (0-30 minutes).

dataCollection.
timeout.
timeUnit

String

Required

Mutable

Time unit of data collection timeout. Can be SECONDS or MINUTES.

dataCollectionOnly

Boolean

Optional

Mutable

When true, collects documents specified in the policy without determining their validity; defaults to false

timeout

Object

Optional

Mutable

Object for transaction timeout

timeout.
duration

Integer

Required

Mutable

Length of time before transaction timeout expires. Can be 60-1800 seconds (1-30 minutes).

timeout.
timeUnit

String

Required

Mutable

Time unit of transaction timeout. Can be SECONDS or MINUTES.

If dataCollectionOnly is true, documents submitted by a user are retained and available from Verify Documents, but are not verified. Additionally, when the verification policy requires facialComparison configuration object or liveness configuration object, injection attack detection is still automatically performed.

When setting or changing timeouts in the transaction configuration object, dataCollection.timeout.duration must be less than or equal to timeout.duration. Use caution when reducing the timeouts below the defaults to avoid an unfavorable user experience.

voice configuration object

Voice verification is deprecated and will be removed on November 25, 2026.
Property Type Required? Mutable? Description

comparison.
threshold

String

Required

Mutable

Comparison threshold. Can be LOW, MEDIUM, or HIGH.

enrollment

Boolean

Required

Mutable

Controls if the transaction performs voice enrollment (true) or voice verification (false)

liveness.
threshold

String

Required

Mutable

Liveness threshold. Can be LOW, MEDIUM, or HIGH.

referenceData

Object

Optional

Mutable

Object for configuration of reference data stored per user for voice verification

referenceData.
retainOriginalRecordings

Boolean

Optional

Mutable

Controls if the service stores the original voice recordings; defaults to false

referenceData.
updateOnReenrollment

Boolean

Optional

Mutable

Controls updates to user’s voice reference data (voice recordings) upon user re-enrollment. If true, new data adds to existing data. If false, new data replaces existing data.

referenceData.
updateOnVerification

Boolean

Optional

Mutable

Controls updates to user’s voice reference data (voice recordings) upon user verification. If true, new data adds to existing data. If false, new voice recordings are not retained as reference data.

textDependent

Object

Optional

Mutable

Object for configuration of text dependent voice verification

textDependent.
phrase.
id

String

Required

Mutable

Identifier (UUID) of the voice phrase to use

textDependent.
samples

Integer

Required

Mutable

Number of voice samples to collect

verify

String

Required

Mutable

Controls if voice verification is REQUIRED, OPTIONAL, or DISABLED