v1 - Step 7: Async Verify

Once you've completed steps 1-6, you should have everything you need to carry out a Verify request. Using one of the country codes from step 3 and the document type from step 5 you can now run a verify request:

GlobalGateway uses normalized fields across all countries supported by ID Document Verification. A sample request to the GlobalGateway API can be found below.

We recommend including the "CallbackURL" field to call the API asynchronously. This will ensure that your API call does not get timed out in 60 seconds should the verification take longer to process. The "DocumentType" field needs to be provided to process the type of document the end user submitted.

To use this workflow, you will require to use the asynchronous verification workflow, where you pass in a CallbackURL or pass this endpoint for polling https://api.trulioo.com/connection/v1/async-callback.

For extra details on asynchronous workflows please visit this page.

🚧

Important:

Trulioo provides multiple global and regional endpoints. Please choose the correct endpoint based on your business use case and your regulatory and compliance requirements. You can find more information on the Multi-Region Hosting page.

Request

https://api.trulioo.com/verifications/v1/verify

{
  "AcceptTruliooTermsAndConditions": true,
  "CleansedAddress": false,
  "VerboseMode": true,
  "ConfigurationName": "Identity Verification",
  "CallBackUrl":  CallbackURL,
  "CountryCode": "CA",
  "DataFields": {
    "PersonInfo": {
      "FirstGivenName": "FirstName",
      "FirstSurName": "LastName"
    },
    "Location": {},
    "Communication": {},
    "Document": {},
    "Passport": {},
    "Business": {},
    "CountrySpecific": {
      "CA": {
        "DocumentType": "DrivingLicence"
      }
    }
  }
}
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
var truliooClient = new TruliooApiClient("JoeNapoli_API_Demo", "05uZuPRCyPi!6");
VerifyRequest request = new VerifyRequest()
{
    AcceptTruliooTermsAndConditions = true,
    ConfigurationName = "Identity Verification",
    CountryCode = "US",
    DataFields = new DataFields()
    {
        PersonInfo = new PersonInfo()
        {
            FirstGivenName = "Kyle Antwon",
            MiddleName = "",
            FirstSurName = "Hertz",
        },
        Document = new Document()
        {
            DocumentFrontImage = "/9j/4QAYRXhpZgAASUkqAAgAAAAA .....IQCEIQCEIQCEIQP/9k=",
            DocumentBackImage = "/9j/4QAYRXhpZgAASUkqAAgAAAAA......LKICIiAiIgIiICIiAiIg//Z",
            DocumentType = "DrivingLicence"
        },
    }
};
            
VerifyResult result = await truliooClient.Verification
    .VerifyAsync(request);
//Example Username: JoeNapoli_API_Demo, Example Password: 05uZuPRCyPi!6
ApiClient apiClient = new ApiClient();
apiClient.setUsername("JoeNapoli_API_Demo");
apiClient.setPassword("05uZuPRCyPi!6");
VerificationsApi verificationClient = new VerificationsApi(apiClient);
VerifyRequest request = new VerifyRequest()
    .acceptTruliooTermsAndConditions(Boolean.TRUE)
    .configurationName("Identity Verification")
    .countryCode("US")
    .dataFields(new DataFields()
        .personInfo(new PersonInfo()
            .firstGivenName("Kyle Antwon")
            .middleName("")
            .firstSurName("Hertz"))
        .document(new Document()
            .documentFrontImage("/9j/4QAYRXhpZgAASUkqAAgAAAAA .....IQCEIQCEIQCEIQP/9k=")
            .documentBackImage("/9j/4QAYRXhpZgAASUkqAAgAAAAA......LKICIiAiIgIiICIiAiIg//Z")     
            .documentType("DrivingLicence"));
}}));
//verify
VerifyResult result = verificationClient.verify(request);



//verifyAsync
verificationClient.verifyAsync(request, new ApiCallback<VerifyResult>() {
    @Override
    public void onFailure(ApiException e, int statusCode, Map<String, List<String>> responseHeaders) {
        Logger.getLogger(SdkJavaV1Sample.class.getName()).log(Level.SEVERE, null, e);
    }
    @Override
    public void onSuccess(VerifyResult result, int statusCode, Map<String, List<String>> responseHeaders) {
        System.out.println(result); //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onUploadProgress(long bytesWritten, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
    @Override
    public void onDownloadProgress(long bytesRead, long contentLength, boolean done) {
        //To change body of generated methods, choose Tools | Templates.
    }
});

Response

{
    "TransactionID": <Transaction-ID-Here>,
    "UploadedDt": "0001-01-01T00:00:00",
    "CountryCode": "CA",
    "ProductName": "Identity Verification",
    "Record": {
        "RecordStatus": "nomatch",
        "DatasourceResults": [],
        "Errors": [],
        "Rule": {}
    },
    "Errors": []
}

After making the asynchronous verification, you take the Response TransactionID and use it in the POST Body of the of ImageUpload Request

Request

For the front image
https://api.trulioo.com/v1/docv/UploadImage

Request

{
	"TransactionID": <Transaction-ID-Here>,
	"DataField": "DocumentFrontImage",
	"Status": <"Pending">,
	"Value": <"Base64-Image-String">
}

*NOTE*
If the Status is Completed, ImageUpload will no 
longer continue to wait for the remaining images
to be uploaded and will continue onto Tier 1 with 
the captured Images.

The response after each upload is 200 OK.

Request

For the back image
https://api.trulioo.com/v1/docv/UploadImage

Request

{
	"TransactionID": <Transaction-ID-Here>,
	"DataField": "DocumentBackImage",
	"Status": <"Completed">,
	"Value": <"Base64-Image-String">
}

*NOTE*
If the Status is Completed, ImageUpload will no 
longer continue to wait for the remaining images
to be uploaded and will continue onto Tier 1 with 
the captured Images.

Once the completed status is sent with your final image, the transaction will complete asynchronously.

The API responds with an overall verified through RecordStatus field. If RecordStatus is a “match”, all or most of the checks performed on the document will have passed. In addition, the OCR data is returned in the API response through AppendedFields. The checks performed on the document are returned in the AuthenticityDetails field. If a document failed due to some of the checks performed on the document, AuthenticityReasons is also returned in AppendedFields with comma separated values of why the document failed.

Response

{
   "TransactionID":"123fbb49-54fb-4ac1-9662-6f75402c0648",
   "UploadedDt":"2020-07-13T21:23:33.722704",
   "CountryCode":"US",
   "ProductName":"Identity Verification",
   "Record":{
      "TransactionRecordID":"2521e146-0bed-3eb7-07a7-zxxxxxxxxxxxx",
      "RecordStatus":"match",
      "DatasourceResults":[
         {
            "DatasourceName":"DocVDemo_DocumentVerification",
            "DatasourceFields":[
               {
                  "FieldName":"FirstSurName",
                  "Status":"match"
               },
               {
                  "FieldName":"FirstGivenName",
                  "Status":"match"
               },
               {
                  "FieldName":"Address1",
                  "Status":"match"
               },
               {
                  "FieldName":"PostalCode",
                  "Status":"match"
               },
               {
                  "FieldName":"DayOfBirth",
                  "Status":"match"
               },
               {
                  "FieldName":"MonthOfBirth",
                  "Status":"match"
               },
               {
                  "FieldName":"YearOfBirth",
                  "Status":"match"
               },
               {
                  "FieldName":"City",
                  "Status":"match"
               },
               {
                  "FieldName":"DocumentVerified",
                  "Status":"match"
               },
               {
                  "FieldName":"StateProvinceCode",
                  "Status":"match"
               },
               {
                  "FieldName":"TamperingCheck",
                  "Status":"match"
               },
               {
                  "FieldName":"SecurityFeatureCheck",
                  "Status":"match"
               },
               {
                  "FieldName":"ClassifiedDocument",
                  "Status":"match"
               },
               {
                  "FieldName":"DataCrosscheck",
                  "Status":"match"
               },
               {
                  "FieldName":"DataValidation",
                  "Status":"match"
               },
               {
                  "FieldName":"ValidDocument",
                  "Status":"match"
               },
               {
                  "FieldName":"LivePhotoCrosscheck",
                  "Status":"match"
               },
               {
                  "FieldName":"MachineReadableDocument",
                  "Status":"match"
               },
               {
                  "FieldName":"DocumentTypeCheck",
                  "Status":"match"
               },
               {
                  "FieldName":"DocumentCountryCheck",
                  "Status":"match"
               },
               {
                  "FieldName":"AddressFound",
                  "Status":"match"
               }
            ],
            "AppendedFields":[
               {
                  "FieldName":"YearOfBirth",
                  "Data":"1981"
               },
               {
                  "FieldName":"City",
                  "Data":"San Francisco"
               },
               {
                  "FieldName":"PostalCode",
                  "Data":"94109"
               },
               {
                  "FieldName":"FirstName",
                  "Data":"Timothy"
               },
               {
                  "FieldName":"LastName",
                  "Data":"Jones"
               },
               {
                  "FieldName":"DayOfBirth",
                  "Data":"01"
               },
               {
                  "FieldName":"MonthOfBirth",
                  "Data":"02"
               },
               {
                  "FieldName":"Address1",
                  "Data":"222 Eastland Dr."
               },
               {
                  "FieldName":"DayOfExpiry",
                  "Data":"01"
               },
               {
                  "FieldName":"MonthOfExpiry",
                  "Data":"02"
               },
               {
                  "FieldName":"YearOfExpiry",
                  "Data":"2019"
               },
               {
                  "FieldName":"DocumentCountryCode",
                  "Data":"US"
               },
               {
                  "FieldName":"StateProvince",
                  "Data":"CA"
               }
            ],
            "Errors":[

            ],
            "FieldGroups":[

            ]
         }
      ],
      "Errors":[

      ],
      "Rule":{
         "RuleName":"RuleScript - DocVDemoRule_v1",
         "Note":"1 Records Match\r\n(\r\n    LastName!=\"True\"\r\n)"
      }
   },
   "Errors":[

   ]
}

The following are the standardized field checks performed across all three document verification vendors. The purpose of this was to standardize the data returned from the vendor so that data across multiple vendors is returned in a consumable manner to our customers.

Verification Checks:

SecurityFeatureCheck
Checks the security features defined for the document template can be found on the submitted document in the expected location.

TamperingCheck
Checks for proof of digital tampering on the submitted document by detecting use of photo editing software to tamper human and machine readable data or photo ID present in the document.

DataCrosscheck
Checks the data matches from multiple data sources present on a document such as Visual Inspection Zone, 2D Barcode and Machine Readable Zone (MRZ).

DocumentTypeCheck

Checks the submitted document type matches the classified document type.

DocumentCountryCheck
Checks the submitted document country matches the classified document country.

LivePhotoCrosscheck
Compares the LivePhoto of the individual with the photo in the submitted document.

Validations:

ClassifiedDocument
Validates the submitted document can be classified to a specific document type and the document type can be fully authenticated.

DataValidation
Validates the extracted human and machine readable data meets the expected format as defined for the document template.

ValidDocument
Validates the extracted human and machine readable data meet the requirements for a document to be valid. Expiration and Issue Date are the most common data elements used to deem a document to be invalid.

MachineReadableDocument
Validates barcode or MRZ data that can be found in the submitted document and can be parsed successfully.

Note that not all document types undergo the same verification checks.

The API responds with an overall verified through RecordStatus field. If RecordStatus is a “match”, all or most of the checks performed on the document will have passed. In addition, the OCR data is returned in the API response through AppendedFields. The checks performed on the document are returned in the output field section. If a document failed due to some of the checks performed on the document.

OCR

We have standardized the OCR data across all countries that are returned in appended fields. These standardized fields can be found below:

  1. Address1
  2. Address2
  3. City
  4. StateProvince
  5. PostalCode
  6. Address1Standard
  7. Address2Standard
  8. CityStandard
  9. StateProvinceStandard
  10. PostalCodeStandard
  11. DayOfBirth
  12. MonthOfBirth
  13. YearOfBirth
  14. PlaceOfBirth
  15. DocumentNumber
  16. DayOfExpiry
  17. MonthOfExpiry
  18. YearOfExpiry
  19. FullName
  20. FirstName
  21. LastName
  22. DayOfIssue
  23. MonthOfIssue
  24. YearOfIssue
  25. Issuer
  26. Class
  27. Mrz1
  28. Mrz2
  29. Mrz3
  30. Nationality
  31. Gender
  32. AlternateFirstName
  33. AlternateMiddleName
  34. AlternateLastName
  35. AlternateFullName
  36. AlternateAddressLine1
  37. AlternateAddressLine2
  38. AlternateFullAddress
  39. AlternateDocumentNumber
  40. AlternateDocumentNumber2
  41. AlternateDateOfBirth
  42. AlternateExpiryDate
  43. AlternateIssueDate