Create Verify Transaction

POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/verifyTransactions

Create a new verify transaction for the specified user with the POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/verifyTransactions request.

Prerequisites

• Create a user to get a userID for the endpoint. See also Users, especially User operations.

• Create a verify policy to get a verifyPolicyID for the body. See also PingOne Verify, especially Verify Policies.

See Verify transaction data model for full property descriptions.

requirements - Requirements object

A referenceSelfie is required when, in the verify policy referenced by verifyPolicy.id (or the default verify policy), facialComparison.verify is REQUIRED and governmentID.verify is DISABLED. Otherwise, referenceSelfie is ignored.

Biographic matching occurs when the Verify Policy includes governmentId and this body 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 preforms 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.

For webVerificationUrl in the response body, the value is the URL for the ${app.open.url} dynamic variable of the id_verification notification sent to the user. Furthermore, it 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 will be replaced with a new method to pass redirectMessage in an upcoming update. 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 will be replaced with a new method to pass redirectUrl in an upcoming update. 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.

There are three parties to creating a verify transaction, the user, the company requesting the transaction, and the service. When used, requirements.email.options can have 0, 1, or multiple email addresses.

• If the company sends 0 email addresses, the user can provide any email they want.

• If the company sends 1 email address from their records, that email address receives the OTP and the user cannot change it.

• If the company sends 2 or more email addresses from their records, the service returns the addresses to the user with part of the address masked. The user sends the email address they want to verify.

When a phone number is needed, a valid phone number string must be provided in international format (includes a leading + character), 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.5125551234
+15125551234
+1.512.555.1234
15125551234
1-512-555-1234
+1 (512) 555-1234

The device (browser or smartphone) receives a single page application (SPA) - an HTML web page containing a code that establishes a link between the device and this transaction. Once linked, the device captures identity documents for verification. After completing verification, depending on the verify policy, the email or phone number submitted with the transaction can become a multifactor authentication device for PingOne.

If a phone number or an email address or both are supplied in the request body, after receipt of this request the verification service sends notifications using these notification templates: - email_phone_verification - Sends a one-time password (OTP) to verify an SMS number or email address or both for a verify transaction. You can define a notification variant and locale for the email_phone_verification notification with Create Verify Policy or Update Verify Policy. Associate a verify policy in verifyPolicy of this request or, if no verifyPolicy is provided, the default verify policy for the environment is used. - id_verification - Sends an SMS or email or both to the end user with a link to Web Verify (Universal Capture) for the verify transaction. You cannot define a notification variant or locale for an id_verification notification.

The transaction is used by client applications when sending a web verification request, and for allowing requests to service providers.

Request Body

{"sendNotification"=>{"phone"=>"{{phone}}", "email"=>"{{email}}"}, "verifyPolicy"=>{"id"=>"{{verifyPolicyID}}"}, "requirements"=>{"referenceSelfie"=>{"value"=>"{{base64EncodedData}}"}, "phone"=>{"value"=>"{{phone}}"}, "email"=>{"options"=>["{{email}}", "test@mailinator.com"]}, "given_name"=>{"options"=>["Robert", "Bob"]}, "family_name"=>{"value"=>"Redford"}, "name"=>{"value"=>"Robert Redford"}, "address"=>{"options"=>["4321 Main Street #407, Hollywood, CA 90027", "4321 Main Street Apt 407, Hollywood, CA 90027"]}, "birth_date"=>{"value"=>"1984-08-02"}}, "callback"=>{"url"=>"https://example.com/testUrl2", "headers"=>{"x-environment-id"=>"{{envID}}", "x-phone"=>"{{phone}}"}}, "redirect"=>{"url"=>"https://example.com", "message"=>"Redirect message"}}

RESPONSES

status: Created

{"_links":{"self":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/ad7b009a-6d88-4830-b3a6-99906049e372/verifyTransactions/293c1116-4050-47a1-ace0-be126b115d46"},"environment":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"},"user":{"href":"https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/ad7b009a-6d88-4830-b3a6-99906049e372"}},"id":"293c1116-4050-47a1-ace0-be126b115d46","verifyPolicy":{"id":"cf4fc8f1-9db1-45b1-a157-ab4035425e00"},"transactionStatus":{"status":"REQUESTED","verificationStatus":{"FACIAL_COMPARISON_DOCUMENT":"REQUESTED","FACIAL_COMPARISON_REFERENCE_SELFIE":"REQUESTED","GOVERNMENT_ID":"REQUESTED","LIVENESS":"REQUESTED"}},"qrUrl":"https://api.pingone.com/v1/idValidations/webVerifications/293c1116-4050-47a1-ace0-be126b115d46/qr","webVerificationUrl":"https://apps.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/verify/verify-webapp/v2/index.html?txnid=293c1116-4050-47a1-ace0-be126b115d46\u0026url=https%3A%2F%2Fapi.pingone.com%2Fv1%2FidValidations%2FwebVerifications\u0026code=232660\u0026envId=abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6","webVerificationCode":"232660","requirements":{"address":{"options":["4321 Main Street #407, Hollywood, CA 90027","4321 Main Street Apt 407, Hollywood, CA 90027"]},"referenceSelfie":{"value":"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"},"phone":{"value":"+1 972-555-1234"},"birth_date":{"value":"1984-08-02"},"name":{"value":"Robert Redford"},"given_name":{"options":["Robert","Bob"]},"family_name":{"value":"Redford"},"email":{"options":["user@example.com","test@mailinator.com"]}},"callback":{"url":"https://example.com/testUrl2","headers":{"x-environment-id":"abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6","x-phone":"+1 972-555-1234"}},"sendNotification":{"email":"user@example.com","phone":"+1 972-555-1234","results":[{"method":"SMS","sent":true,"notification":{"id":"00ce0d7d-7c8d-4898-befa-90d301195471"}},{"method":"EMAIL","sent":true,"notification":{"id":"0091eb4b-5180-4c93-b65c-3b8d181619b0"}}]},"createdAt":"2024-02-06T15:00:28.250Z","updatedAt":"2024-02-06T15:00:28.250Z","expiresAt":"2024-02-06T15:30:28.250Z"}