Use the Credentials service to create custom verifiable credentials for users. The resulting credentials can then be shared with compatible wallet apps. The Credentials service enables you to:

• Define an issuer profile

• Define custom verifiable credentials

• Define credential issuance rules

• Manage users' credential digital wallets

• Issue credentials to PingOne users

• Present credentials for verification

• Revoke credentials or expire credentials issued to PingOne users

Automatic deletion and revocation

Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

Environment deleted:

• Delete all credential types

• Delete all issuance rules

• Delete all staged changes

• Delete all digital wallet applications

• Delete all digital wallets

• Delete all user credentials

• Delete all provisioned credentials

• Delete all credential type counts

• Delete environment credential count

Population deleted:

• Remove population from existing issuance rules

Group deleted:

• Remove group from existing issuance rules

User deleted:

• Delete user credential

• Delete digital wallets

Application (associated with digital wallet applications) deleted:

• No impact

Credential type deleted:

• Revoke issued credentials based on delete flag

• Delete issuance rule

Issuance rule deleted

• Delete staged changes

Digital wallet application deleted:

• Disable digital wallets that are of this type

Digital wallet deleted:

• Revoke credentials that were provisioned to the digital wallet based on credential type delete flag

User credential deleted:

• Revoke provisioned credentials based on credential type delete flag

Regardless of the setting of onDelete.revokeIssuedCredentials, the service always deletes any pending credentials. (Pending credentials are staged for issue but not provisioned to a wallet because no paired digital wallet exists.)

Use the Credential Issuers operations to retrieve or update the credential issuer information. A credential issuer profile, which enables issuance of credentials, is automatically created when the credential service is added to an environment.

Credential Issuers data model

The logo and name can be shown to the user when indicating the credential issuer by the wallet app using using the PingOne Neo Native SDKs with getIssuerMetadata for Android and getCredentialIssuerMetadataFromClaim(_:) for iOS.

Response codes

Use the Credentials Types operations to create, read, and update the credential types used by compatible wallet apps.

Versioning

If the updated credential type differs from the existing credential type, the service saves the existing credential type as a Credential Type Version and increments version.number in the updated credential type. Credential Type Versions can be read with Read All Credential Type Versions.

Credential schema

When the service creates a credential from a credential type, it maintains the full credential schema, including attributes without corresponding values in the Create a User Credential request, so that the credential structure is consistent and predictable. It assigns an empty string ("") to any attribute without a value in the request body.

Credential Types data model

If management.mode is AUTOMATED, the credential type is only issued by its associated credential issuance rule. If management.mode is MANAGED, the credential type is only issued by Create a User Credential or Update a User Credential API requests. If you change management.mode from AUTOMATED to MANAGED and an associated issuance rule exists, the rule is disabled, but not deleted.

If management.mode is AUTOMATED, you can value one and only one of the three properties in the expiration object and the associated credential issuance rule automatically assigns an expiration date when it issues the credential. If management.mode is MANAGED and an expiration object is present, it causes an error.

If you want to change management.mode from AUTOMATED to MANAGED, but one of the three properties in the expiration object is valued, you must remove the expiration object. Use Update the Credential Type with no expiration object, which removes it from the credential type, and with management.mode set to MANAGED.

metadata object data model

The metadata object is not returned with Read All Credential Types. You must Read One Credential Type with the id of the credential type you want to review.

fields.attribute definition

Although fields.attribute is always a string type, the service supports two interpretations of its string.

If the string begins with ${ and ends with }, the string is interpreted as a PingOne Expression Language (PEL) expression. As a PEL expression, the string must have user. before any attribute names. A PEL expression is essential to Issue multiple credentials to a user based on a directory attribute. The PEL expression extracts specific elements from the multiple potential credentials found in the attribute.

If the string does not have ${ and }, the string is interpreted as the traditional pointer to an attribute name in the directory. That is, you supply an attribute name as the string and the service supplies the value of that attribute to the credential. When used as a pointer, the string does not need user. to reference an attribute.

fields.fileSupport types

A credential field that uses a type of Directory Attribute can contain a URL that references a JPEG, PNG, or GIF image file uploaded with Create Image. The credential type is limited to 5 fields that have fileSupport set to BASE64_STRING or INCLUDE_FILE. For credentials, an image file has a maximum size of 2 MB. A credential cannot exceed 2.5 MB including all images.

fields.type types

Automatic deletion and revocation

Typical behavior for credential types is to automatically revoke user credentials when a credential type, user, or environment is deleted. However, some credential types, such as birth certificates, university degrees, or marriage certificates, should never be automatically revoked even if the user or environment is deleted. You control this using onDelete.revokeIssuedCredentials on the credential type.

The selected deletion and revocation behavior cascades over all resources managed by the service: credential types, issuance rules, staged changes, digital wallet applications, digital wallets, and user credentials.

If onDelete.revokeIssuedCredentials is true:

• User credentials are revoked and deleted when the credential type is deleted.

• Provisioned credentials are revoked when a user credential is deleted, its credential type is deleted, or its digital wallet is disabled or deleted.

If onDelete.revokeIssuedCredentials is false:

• User credentials are only revoked if the issuance rule causes it to be revoked or if Update a User Credential sets the expiration date.

• Provisioned credentials are revoked if the user credential is revoked (refer to previous item).

Issue multiple credentials to a user based on a directory attribute

Some customers must issue multiple credentials to a user based on a directory attribute. For example, a bank might issue credit cards in their own name while also issuing credit cards branded for their customers. A user may have more than one of these credit cards in their wallet. The directory service requires an attribute that contains all the credit cards for that user and the service must support credential issuance to any or all of that user's credit cards.

The customer can define a single directory attribute for each user to hold a data object that contains the different accounts owned by the user. Our hypothetical bank wants to support the end user being able to present a verifiable credential that contains only the information from one of these accounts. Although issuance of multiple credentials is initiated by a single directory attribute, definition of the credential type can reference any directory attributes for its fields.

The definition of the data object is up to the customer. They then use PingOne Expression Language (PEL) expressions to retrieve any information as required. The Credential Types multiple.expression contains a PEL expression that counts qualifying entries in the data object. The Credential Types metadata.fields.attribute contains a PEL expression to retrieve individual data elements that populates a field in the credit type definition.

When you Apply Credential Issuance Rule Staged Changes for a user for a credential type that has multiple configured, the service creates multiple, separate user credentials for the credential type.

An example may better illustrate applying these concepts.

Example data object

Our hypothetical bank customer, BigBank, uses this JSON object, stored as a JSON binary large object (blob), as the source for credit card information.

{
  "credit_cards": {
    "branded": [
      {
        "oem_merchant": "ChainRetailer",
        "customer_id": "0010380",
        "user_id": "1506980157738"
      },
      {
        "oem_merchant": "GlobalOil",
        "customer_id": "0475932",
        "user_id": "1506980157739"
      }
    ],
    "owned": [
      {
        "customer_id": "0010380",
        "int_id" : "03918203198"
      },
      {
        "customer_id": "0475932",
        "int_id" : "03918203100"
      }
    ]
  }
}

An administrator at BigBank creates two different credential types, one each for branded and owned. Each credential type is configured to issue a credential for each JSON object in that array.

Example API

This demonstrates the API using the branded array. An administrator at BigBank created this credential type for branded.

A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.branded is:

{
    "title": "Branded Cards",
    "description": "Example for branded cards attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "title",
                "title": "oem_merchant",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].oem_merchant}",
                "isVisible": true,
                "type": "Directory Attribute",
                "default": "Use this if missing"
            },
            {
                "id": "Directory Attribute -> user_id",
                "title": "user_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].user_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['branded'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ]
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['branded']}"
    }
}

The PEL expression in multiple.expression returns the count of objects in the credit_cards.branded object array of the data object. This populates the iteration limit of the system __ITERATOR__ variable seen in the PEL expressions of the three metadata.fields.attribute values.

A body for Create a credential type (automated) that creates multiple credentials from the data object for the credit_cards.owned is:

{
    "title": "Owned",
    "description": "Example for owned attribute for BigBank",
    "metadata": {
        "fields": [
            {
                "id": "Directory Attribute -> int_id",
                "title": "int_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].int_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            },
            {
                "id": "Directory Attribute -> customer_id",
                "title": "customer_id",
                "attribute": "${user.credit_cards['owned'][__ITERATOR__].customer_id}",
                "isVisible": true,
                "type": "Directory Attribute"
            }
        ],
        "textColor": "#000000",
        "version": 4
    },
    "cardDesignTemplate": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 740 480\">...</svg>",
    "multiple": {
        "expression": "${user.credit_cards['owned']}"
    }
}

The PEL expression in multiple.expression returns the count of objects in the credit_cards.owned object array of the data object. This populates the iteration limit of the system __ITERATOR__ variable seen in the PEL expressions of the two metadata.fields.attribute values.

Important considerations

1. Do not use a multi-valued attribute type. Use a single JSON attribute that contains the necessary arrays.

   When configuring a custom JSON attribute for issuing multiple credentials for a user, the administrator can set it to a multi-valued type, which allows the attribute to be an array of JSON blobs. The PingOne Directory does not guarantee ordering for multi-valued attributes. Multi-valued attributes values are treated as a set rather than a list. This conflicts with how the service determines if a credential has changed, where order is essential. For example, a user has three credentials issued using a multi-valued type of [A, B, C]. If you add another JSON blob to the user attribute, one might expect the change to look like [A, B, C, D] (where each letter is a different credential) and issue one more credential to the user. However, with a multi-valued custom JSON attribute, the change may look like [A, C, D, B]. When the service compares the order, it interprets that two credentials have been updated and one more credential has been added.

   Due to this involuntary re-ordering behavior, multi-valued custom JSON attributes are strongly discouraged.

2. Revocation can be affected by re-ordering.

   If the user has an array like [A, B, C] so that the service issues three credentials and an administrator then revokes the credential B, credential B remains revoked. If the user is updated to change some values in A, B, and C, A and C update while B remains revoked. However, if the user is updated with a new object or value added to the array such that it becomes [A, D, B, C], credential C updates to the values of B and a new credential issues for C. No credential will be issued or updated to have the values of D because it is in the second place and the credential for second place was revoked.

   To mitigate this behavior, always add new entries to the end of the arrays in the JSON blob.

Response codes

Use the Credentials Issuance Rules operations to create, read, and update rules for issuing, updating, and revoking credentials by credential type. Rules are defined for:

• A specific Credential Type in the endpoint

• A specific Digital Wallet App in the request body

• A specific set of users defined by one, and only one, of these filters in the request body:

  • Membership in one or more Groups.

  • Membership in one or more Populations.

  • Satisfying a SCIM query. For information about SCIM syntax and operators, refer to Filtering collections.

A credential rule contains an automation object with available actions as keys: issue, revoke, and update. If an action is set to PERIODIC, the service performs the action at the end of the period. If an action is set to ON_DEMAND, you must use Apply Credential Issuance Rule Staged Changes to perform staged changes for those ON_DEMAND actions.

The general procedure for rules is:

1. Create - create a new rule to stage actions for for the credential by user

2. Update - update an existing rule to stage actions for the credential by user

3. Staged Changes - show actions staged for execution

4. Apply - act upon credentials staged for actions.

You can also monitor credential rules:

• All Rules - view all rules defined for a credential type

• One Rule - view a specific rule for a credential

• Usage Counts - show counts by action applied to the credential by user

• Usage Details - show details by action applied to the credential by user

You can, finally, remove a rule for a credential type:

• Delete - remove a rule from a credential type

For actions set to PERIODIC, an improper credential could cause endless repetitious errors. The service monitors staged changes for errors. When an error occurs during processing, the service adds details of the error to the staged change so that errors can be tracked, counted, and returned to the user. If more than 3 errors occur for the same scheduled staged change, the service unschedules (changes stagedChanges.scheduled from true to false) that staged change so that the service no longer attempts to process it. The user can manually trigger the staged change with Apply Credential Issuance Rule Staged Changes.

Credentials unscheduled due to errors are reported. Some errors are known but there can also be unexpected errors. The errors.errorDetail object provides an error code and message. If the error was related to processing a specific credential field, the field name will be in errors.errorDetail.target. This includes the staged changes that exist when the request is made with 1 or more errors. It does not include a staged change that was failed in the past, but has since completed successfully or was deleted (because the user no longer matches the issuance rule). Requests that report errors include:

• Read Credential Issuance Rule Staged Changes

• Read Credential Issuance Rule Usage Counts

• Read Credential Issuance Rule Usage Details

• Apply Credential Issuance Rule Staged Changes

Credential Issuance Rules data model

Actions within automation (.issue, .update, and .revoke) can be PERIODIC, the service applies the rule frequently every hour, or ON_DEMAND, the service applies the rule only with an Apply Credential Issuance Rule Staged Changes request. For ON_DEMAND, use Read Credential Issuance Rule Staged Changes to determine staged changes.

The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user's preferred language or, if the user has no preferred language, the default language of the environment.

Credential Issuance Rules staged changes data model

Credential Issuance Rules apply staged changes data model

This data model applies only to Read Credential Issuance Rule Staged Changes and Apply Credential Issuance Rule Staged Changes.

Credential Issuance Rules usage counts data model

Credential Issuance Rules usage details data model

Credential Issuance Rules errors object

Credential Issuance Rules staged changes error codes

Response codes

The credential digital wallet apps service controls the relationship between the customer's digital wallet app, which communicates with users' digital wallets, and a customer's PingOne application.

Credential digital wallet app data model

The credential Digital Wallet service controls the relationship between a user's phone wallet app, which uses the Wallet SDK, and the customer's PingOne application. It also offers notifications when the PingOne application communicates with the user's Wallet SDK. Settings on the Digital Wallet configure sending push notifications from PingOne Credentials to the Wallet SDK of the user.

In the normal digital wallet pairing use case, you use Create Digital Wallet to create the Digital Wallet without the applicationInstance.id and a pairing session is created. The Digital Wallet service uses the digital_wallet_pairing notification template to send the pairing session URL (refer to appOpen.href in the response) to the user via email or text or you show a QR code (refer to qrUrl.href in the response) of the pairing session URL to the user. When the user opens the URL, it opens your app or takes them to a page with instructions on how to install the app. When the app opens the URL, it shares its applicationInstance.id with the service using the Wallet SDK.

Alternatively, you send the applicationInstance.id when you create the Digital Wallet. For example, if you have the user install your app, the user authenticates with your servers. When your app is installed, it creates an application instance. Since the app knows who the user is, the app sends its application instance identifier to your server and then your application sends the applicationInstance.id to the service when creating or updating the Digital Wallet. This creates a Digital Wallet with a known application instance identifier. Activation of the Digital Wallet requires sending some device data, such as SDK version and application bundle ID or package name, to PingOne Credentials:

1. The service creates a pairing session and sends a pairing request message to the device.
2. The Wallet SDK receives this request and the app approves the request.
3. The Wallet SDK sends the device data to PingOne Credentials, which activates the Digital Wallet.

Credential digital wallet data model

Pairing attempt errors

The digital wallet service uses the digital_wallet_pairing notification template to send the pairing session URL to the user via email or SMS text. The notification.template object can define a variant and locale for the notification, if needed.

Provisioned Credentials data model (wallet)

This object is shared with user credentials. It is returned only with Read One Digital Wallet Credentials and Read One User Credential Wallets. The former returns all user credentials associated with the specified digital wallet, the latter returns all digital wallets associated with the specified user credential.

Use the User Credentials service to create a user credential and get the credential status. To issue the credential to the user you must first create a credential type (automated) or create a credential type (managed). After you create a credential type, you can issue credentials to users two ways depending on the management.mode of the credential type:

• if management.mode is AUTOMATIC, create a credential issuance rule and the service issues the credential to all users who match the rule.

• if management.mode is MANAGED, create a credential type (managed) or update a user credential and the service issues the credential to that user.

Regardless of management.mode, you can revoke a user credential, read all user credentials, read one user credential, or read one user credential wallets.

User Credentials data model

The one notification.template object applies a variant and locale to all three credential notification templates: credential_issued, credential_updated, and credential_revoked. When adding a variant or locale to any of the three notification templates, consider adding the same variant or locale to the other notification templates. If a requested variant is not defined, the notification uses the default notification template. If a requested locale is not defined, the notification uses the user's preferred language or, if the user has no preferred language, the default language of the environment.

Although notification.template is immutable, Update a User Credential can change notification.template on a specific credential for its life span.

data object data model

The data object can only be used for Credential Types where its management.mode is MANAGED. Individual fields in data can only be used where the corresponding credential type's metadata.fields.type is Alphanumeric Text. If the corresponding credential type's metadata.fields.value is valued, that value represents a default for the field and can be overridden in Create a User Credential or Update a User Credential API requests.

The data object contains any number of keys, where the key is the title in metadata.fields that represents a specific attribute of the credential type required by the issuer. For example, an insurance company might have a metadata.fields.title of Medical Limitations and the corresponding data key would be Medical Limitations. These data fields must match the metadata.fields defined for the credential type in credentialType.id. For more information on fields, refer to the fields object in metadata object data model and the data types in fields.type types.

Whether any given data.<field> is required or optional depends on the corresponding fields.required and fields.value in the metadata object of the credential type. A data.<field> is required when fields.required is true and no fields.value exists and optional when fields.required is false or when fields.value has a value.

Provisioned Credentials data model (credential)

This object is shared with digital wallets. It is returned only with Read One User Credential Wallets and Read One Digital Wallet Credentials. The former returns all digital wallets associated with the specified user credential, the latter returns all user credentials associated with the specified digital wallet.

Response codes

The Credential Verification service receives, and responds to, requests for credential verification using Decentralized Identity Foundation Java Web Token Verifiable Credentials Presentation Profile (DIF JWT-VC Profile). The profile uses such open standards as:

• World Wide Web Consortium (W3C) Decentralized Identifiers (DID) for core architecture, data model, and representations

• W3C Verifiable Credentials Data Model for the presentation data model

• DIF Presentation Exchange for credential request

• OpenID for Verifiable Presentations (OpenID4VP ID1) as the base protocol for transportation

Use of these standards provides interoperability with any app that complies with DIF JWT-VC Profile.

The service can also use PingOne native protocols. The PingOne native protocol only works with apps that use the PingOne Neo Native SDKs, which has more features but is restricted to only supported apps.

Credential Verifications session data model

The digital wallet service uses the credential_verification notification template to send a push notification to a digital wallet when a Create Credential Verification Session (NATIVE - Push Notification) is created. The notification.template object can define a variant and locale for the notification, if needed.

If issuerFilter.environmentIds is submitted, the service searches all listed environments for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

If issuerFilter.dids is submitted and protocol is OPENID4VP, the service searches all listed decentralized identifiers (DID) for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

This issuerFilter.dids typically contains decentralized identifiers for issuers that are not using PingOne Credentials for JWT-VC issuance. The service supports these three DID methods:

• did:web - https://w3c-ccg.github.io/did-method-web/

• did:jwk - https://github.com/quartzjer/did-jwk/blob/main/spec.md

• did:ion - https://identity.foundation/ion/ (The service supports only long-form URIs for this method)

Credential Verifications credential data data model

Credential Verifications session data data model

Credential Verifications errors object data model

Credential Verifications error codes

Response codes

For a user to initiate an ID verification request, the client must obtain an ID verification transaction record from the ID verification service. The transaction record is created when a POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/verifyTransactions request is made.

The transaction record acts as permission for the user to engage in the verification process. The user can then submit the necessary user ID information (such as a driver license or passport) for verification by the ID Validation service. The user can also send a self-image that the ID Validation service compares to the submitted identity document, to ensure the submitter is the person on the document, and checks for liveness, to prevent fraud.

One of the challenges to identity proofing is getting high quality images from the user. Our Universal Capture frontends do the best quality verification they can, but it is still possible that the images will not pass the quality check of the identity proofing vendor. When images are taken during verification (such as submitting government documents, liveness checks, or selfies), retries can be permitted to obtain a satisfactory image for processing. The number of retries permitted, if any, are set on the Verify Policy. The user's Universal Capture interface, such as a mobile phone with an app using the PingOne Verify Native SDKs, and the verification service negotiate directly for retries when an unacceptable image is submitted and a retry is permitted. Interaction at the API level is not required.

Once verified, the transaction record also acts as a tracking mechanism to identify the user provisioned using ID Validation. This information is logged with the transaction record by the ID Validation service when the transaction ID is received by the client.

US-based Driver Licenses

Document verification provides additional verification support with American Association of Motor Vehicle Administrators (AAMVA). AAMVA offers a service, Driver's License Data Verification (DLDV), for identity proofing and vetting driver license, identity cards, mobile driver license (mDL), and other secure credentials. Most states (43) and the District of Columbia participate in DLDV. No U.S. territories participate. The states that do not participate in DLDV are:

• Alaska (under review)
• California (SSA only)
• Louisiana (SSA only)
• Minnesota (SSA only)
• New York (SSA only)
• Pennsylvania (participates but requires written permission from the individual)
• Utah (SSA only)

SSA only indicates that only the Social Security Administration has access, not even other government agencies have access. SSA uses AAMVA for employment eligibility.

Submitting state-issued driver's license or identity document to DLDV increases the accuracy of document authentication and also checks their validity by the state government. Accuracy and validity increase by comparing the biographic data, selfie, or both with the issuing government system of record, or another authoritative commercial system of record when the government system of record is unavailable. Results of DLDV checks are returned with the results of other checks in the Verification Metadata.

Request groups

The requests are grouped by endpoints for ease of use.

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.

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

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

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.

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.

liveness configuration object

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

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.

email and phone configuration object

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.

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.

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.

voice configuration object

For each verification attempt, all the necessary information is gathered in a transaction. The verifyTransactions endpoint, /environments/{{envID}}/users/{{userID}}/verifyTransactions, receives all read, status, and control requests associated with the verification attempt.

In the responses is the verificationStatus object, a list that indicates the verification types being verified by the service and the verification status of each step. The verification types are keys in the list and the verification status is the value in the list.

The verification types for a verify transaction are determined from the verify policy.

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

Verify transaction data model

The webVerificationUrl has query parameter options:

1. You can append a &dt=1 query parameter to webVerificationUrl. You can offer to redirect your users to a mobile or desktop browser-based verification. By default, on laptop or desktop browsers, you present to the user a page with the QR code to continue verification on their mobile device. A &dt=1 query parameter also permits verification on laptop or desktop browsers.

2. Deprecated - This query parameter is replaced by message in the redirect object. You can append a &redirectMessage=<message> query parameter to webVerificationUrl, where <message> is an unquoted, URL-encoded text string. The message appears after document collection. For example: &redirectMessage=You%27ve%20successfully%20collected%20all%20document%2e%20Return%20to%20registration.

3. Deprecated - This query parameter is replaced by url in the redirect object. You can append a &redirectUrl=<redirect URL> query parameter to webVerificationUrl, where <redirect URL> is a URL-encoded redirect URL. The redirect URL appears after document collection. For example: &redirectUrl=https%3A%2F%2Fhome.example.com%2Fs%2Fmembership.

redirect object

Used only in the request body of Create Verify Transaction and never returned by any API response.

requirements object

Biographic matching occurs when the Verify Policy includes governmentId and the Create Verify Transaction includes the optional biographic matching data requirements (given_name, family_name, name, address, and birth_date). If the client does not provide biographic matching data, the service performs the verifications required by the verify policy. If the client does provide biographic matching data, the service performs the verifications required by the verify policy and then compares the data extracted from the government identity document to the data provided by the client.

Identity record matching occurs when the Verify Policy includes governmentId and the Create Verify Transaction includes the optional biographic matching data requirements (given_name, family_name, name, address, and birth_date). If the identityRecordMatching configuration object has at least one field defined with a threshold and the client does not provide biographic matching data corresponding to the required fields in the identityRecordMatching configuration object, an error is returned. If the client does provide biographic matching data, the service performs the verifications required by the verify policy and then compares the data extracted from the government identity document to the data provided by the client. If name required by the identityRecordMatching configuration object but only given_name.value and family_name.value are submitted in requirements, given_name.value and family_name.value will be combined as name.

Note on phone property

When a phone number is needed, a valid phone number string must be provided in international format consisting of a leading plus sign, 1 to 3-digit country code, and 4 to 14-digit phone number, for example, +14155552671.

Always include the country code in the value you provide for the phone parameter. Phone formats across the globe are constantly expanding and changing. If the country code is not included, issues might occur with message delivery.

The following sample shows acceptable valid phone attribute formatting for the same number:

+1.5125201234
+15125201234
+1.512.520.1234
+1 (512) 520-1234

sendNotification object

transactionStatus object

Transaction level status definitions

Verification types

Verification type level status definitions

Verification error messages

Errors returned vary by vendor:

• Mitek errors

• Veriff errors

Mitek errors

API errors

If the transaction receives an error for reason code 144, DOCUMENT_IMAGES_MISMATCH - Document images do not match input type, you can ask the user to retry taking a document image.

Processing reasons for document verification (automated)

If the transaction receives an error for reason codes marked Yes in the Retry column, you can ask the user to retry taking a document image.

Selfie capture

If the transaction receives an error for error codes marked Yes in the Retry column, you can ask the user to retry taking a selfie.

Veriff errors

With the Verify Identity Record Matching service, you can submit any of name, given name, family name, birth date, or address from an unverified source and corresponding values from one or more verified sources. The identityRecordMatching endpoint, /environments/{{envID}}/users/{{userID}}/identityRecordMatching, compares the unverified biographic data to the verified biographic data, and returns a raw score and confidence level of the match.

Verify identity record matching request data model

Verify identity record matching response data model

A confidence of NONE occurs when rawScore is very low or when a governmentIdValue value is missing but its corresponding requirementsValue is valued.

The service stores reference data about the user that is later used in verify transactions. For voice verification, an enrollment transaction is necessary to store voice reference data. The voice reference data is then used during voice verification. Voice verification cannot be performed for a user if enrollment has not been performed.

Voice verification does not evaluate the spoken words and therefore is language-independent and can be text-independent when used with longer speech streams. For interactive voice enrollment or verification, between the service and a user's mobile device, the user reads aloud a voice phrase that is submitted to the service. Verify voice phrases are the phrases that the user reads aloud. For non-interactive voice enrollment and verification, longer voice recordings are submitted without specific phrases spoken.

Some phrases are pre-defined by the service. However, customers can define their own, custom phrases.

Voice phrases are a container with a name. The actual phrases to speak are in contents, where the content has a locale and the phrase to speak written in the language required by the locale. Pre-defined phrases have contents in the locales supported by PingOne in their products. Because they are only read by a native speaker, custom voice phrases can be any locale and written in any language or character set.

To define a custom voice phrase:

1. Create a custom voice phrase container to hold the localized contents.
2. Create a custom voice phrase content with the locale and content.

Verify voice phrase data model

Verify voice phrase contents data model

Verify reference data is any data submitted by the user, or by a PingOne customer on behalf of the user, to the verification service as reference material for later comparison during verification. Reference data are voice samples. Verify reference data is retained for an indefinite period of time, although it can be deleted.

Verify reference data data model

Note: The data property can contain rather large base64-encoded data. To reduce message size, it is not returned by Read All Reference Data. Use that call to find the id of a specific reference data and then use Read One Reference Data to retrieve it.

data object

Note: The data object can contain rather large base64-encoded data and therefore is returned only with Read One Reference Data. To find the id for specific reference data, use Read All Reference Data and find the 'id of the reference data to retrieve.