Proof Transactions

The Verified platform can capture and verify the identity of a user based on a combination of acceptable government document types and user-supplied biometric data. This process is also known as a proof transaction.

Optionally, this combination can be used to create an account with a reference biometric credential for use in future verification transactions.

Logical Sequence

1 - Start Proof Process

During your workflow to onboard or enroll a user, your backend can initiate a proof transaction request to capture and verify a user's identity documents and biometrics.

2 - Verify User Data

After initiating the request on your backend, you can use one of Verified's various integration options to build a UI for the user to supply their information. The APIs will then provide information about the validity of this information along with other transaction metadata for your internal use.

3 - (Optional) Enroll User in Verified

Verified can optionally use the information from the proof process to enroll a customer on the platform so you can quickly start running verification transactions.

Postman Sample

For your convenience we have provided sample Postman collections demonstrating the API sequence. Within the collection, the numbered requests correspond directly to the numbered sections below. Download the collection here.

API Sequence

OpenAPI specs can be downloaded here: Administration Service

Sequence Diagram

1 - Authenticate

In your backend, authenticate your access and store the AccessToken and RefreshToken from the response. Before every subsequent API call, implement logic to check if the token is expired and renew it if needed.

2 - Initiate Proof Transaction

In your backend, call the BeginGetForeignIDDocument API endpoint. For a list of supported document types for your tenant, you can call the GetIDDocumentTypes and pass the Name field in the request body below.

Request body:

{
  "DocumentTypes": [
    "2"
  ],
  "TimeoutSec": 3600,
  "PhoneNumber": "",
  "Email": "",
  "TransportType": 0,
  "IntroductionText": ""
}

TransportType	Description
0	Inline
1	SMS
2	Email

You need to store the following parameters from the response:

• OperationId: to track status and use in embedded UI integrations
• OneTimeSecret: to use in embedded UI integrations

Example response body:

{
    "OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ==",
    "TempId": null,
    "OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce",
    "Status": 0,
    "Message": null,
    "StartDate": "2021-10-13T15:59:25.06Z",
    "EndDate": null
}

3 - Display UI for Data Capture

Use the OperationId and OneTimeSecret to build a transaction URL for one of our convenient, prebuilt UI options.

4 - Get Proof Transaction Result

In your backend, check if the user has provided the response.

• You can poll by OperationId for the transaction result using the EndGetForeignIDDocument API endpoint.
• The code should exit the polling loop when the status is not equal to 0, indicating that the operation is not pending.

When the status equals 1 "Accepted", the response will return a TempId. This is where Verified securely stores the data provided by the user. Verified does not store this information for longer than 72 hours.

Example response body:

{
  "OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ==",
  "TempId": "be6e89db-d709-4636-b708-b526c37018a1",
  "OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce",
  "Status": 1,
  "Message": "Operation has been accepted by the user.",
  "StartDate": "2021-10-13T15:59:25.06Z",
  "EndDate": "2021-10-13T16:03:33.01Z"
}

tip

• You can also register a webhook using UpdateCustomerWebhookSettings API so we can notify your backend when the user is done.

5 - Get Document Details

If you are electing to use Verified's document capture capability, you can retrieve the details of the user-supplied documents by calling the GetIDDocument API endpoint. The response of this call will provide information such as the raw image data, verification status, and other metadata about the transaction.

Example response body:

{
  "Data": {
    "VerificationSteps": {
      "DocumentParsed": true,
      "EmrtdParsedFields": null,
      "DocumentVerified": true,
      "EmrtdVerificationDetails": null,
      "BiometryProcessed": true,
      "BiometryMatched": true,
      "LivenessDetectionPerformed": true
    },
    "Document": {
      "Description": "Document Image",
      "Type": "2",
      "CapMethod": 2,
      "RawData": [
        {
          "Key": "Barcode",
          "Value": "rawImageString"
        },
        {
          "Key": "Ipsidy.Bus.DocScan.Scanned",
          "Value": "rawJsonOutput"
        },
        {
          "Key": "Ipsidy.DocScan.Engine.RawJson",
          "Value": "rawJsonOutput"
        }
      ],
      "Data": [
        {
          "Key": "Key",
          "Value": "Value"
        }
      ],
      "FacialImage": {
        "Description": "crop",
        "DataType": 1,
        "Data": "base64imageString"
      },
      "AdditionalImages": [
        {
          "Description": "Ghost portrait",
          "DataType": 1,
          "Data": "base64imageString"
        },
        {
          "Description": "Signature",
          "DataType": 1,
          "Data": "base64imageString"
        },
        {
          "Description": "Barcode",
          "DataType": 1,
          "Data": "base64imageString"
        },
        {
          "Description": "Document front side",
          "DataType": 1,
          "Data": "base64imageString"
        },
        {
          "Description": "Document back side",
          "DataType": 1,
          "Data": "base64imageString"
        }
      ]
    },
    "CurrentFacialImage": {
      "Description": "Selfie",
      "DataType": 1,
      "Data": "base64imageString"
    },
    "Matched": true,
    "MatchScore": 99,
    "VerificationPolicy": null,
    "Error": "",
    "MatchProbability": 0.99999999437658671,
    "ErrorId": "",
    "LivenessDetectionResult": {
      "IsLive": true,
      "Version": "1.27.1",
      "Probability": 1.0,
      "Score": 23.291086,
      "Quality": 0.7932194,
      "Error": null,
      "ErrorId": null
    },
    "BiometryProcessingResult": {
      "Processed": true,
      "Quality": 89,
      "Error": null,
      "ErrorId": null,
      "LivenessCheckPerformed": true,
      "IsLive": true,
      "LivenessScore": 73
    }
  },
  "Id": "8561de9a-1eda-4131-88ca-d207c7445056",
  "CreatedDate": "2022-03-21T16:32:57.077Z",
  "DeletedDate": null,
  "Tag": null,
  "Metadata": {
    "DocumentType": "2",
    "CapMethod": 2,
    "VerificationSteps": {
      "DocumentParsed": true,
      "EmrtdParsedFields": null,
      "DocumentVerified": true,
      "EmrtdVerificationDetails": null,
      "BiometryProcessed": true,
      "BiometryMatched": true,
      "LivenessDetectionPerformed": true
    },
    "VerificationPolicy": null,
    "Error": "",
    "ErrorId": "",
    "BiometricVerificationResult": {
      "Verified": true,
      "Score": 99,
      "MatchProbability": 0.99999999437658671
    },
    "LivenessDetectionResult": {
      "IsLive": true,
      "Version": "1.27.1",
      "Probability": 1.0,
      "Score": 23.291086,
      "Quality": 0.7932194,
      "Error": null,
      "ErrorId": null
    },
    "BiometryProcessingResult": {
      "Processed": true,
      "Quality": 89,
      "Error": null,
      "ErrorId": null,
      "LivenessCheckPerformed": true,
      "IsLive": true,
      "LivenessScore": 73
    }
  }
}

6 - (Optional) Create Account

In your backend, create a Verified account using the CreateAccount API endpoint. You'll need to provide an AccountNumber and DisplayName. You can choose anything that makes sense for your system. AccountNumber must be unique, but DisplayName does not. Use something you can easily link to the specific user for the AccountNumber.

• Ideally, you should setup an "MFA Account GUID" in your system that you would use. This way, the Verified platform has only the info it needs instead of storing identifiable information.
• A simpler, albeit less safe example: create AccountNumber that is equal to Username, so that MFA can be used without creating additional records anywhere in your system.

Example request body:

{
  "AccountNumber": "MyAccount",
  "DisplayName": "MyAccount",
  "CustomDisplayName": "MyAccount",
  "Description": "My Test Account 1",
  "Custom": true
}

caution

Avoid using spaces and special symbols in AccountNumber since this value is used in the URL path in subsequent calls.

7 - (Optional) Create a Reference Biometric Credential

In your backend, create a reference biometric credential using one of the following methods:

Option 1
Use the CreateAccountProofedBiometricCredential API endpoint. Provide the AccountNumber in the URL from step 6 and TempId in the JSON body from step 4.

Example request body:

{
  "TempId": "be6e89db-d709-4636-b708-b526c37018a1"
}

Option 2
Use the CreateAccountBiometricCredential API endpoint and supply the data you captured from the user. This can optionally be the output of document and biometric data from the result of step 5.

Example request body:

{
  "ExternalId": null,
  "Description": "Main account biometric credential",
  "CredentialType": 1,
  "DataType": 1,
  "Data": "dJS6ku0zWI3mXYgsMRv3ayLLX6V91em2gt0AVQ15tr0=",
  "IsProofed": false,
  "SourceCredentials": [],
  "DeletedDate": null
}