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:
- Address1
- Address2
- City
- StateProvince
- PostalCode
- Address1Standard
- Address2Standard
- CityStandard
- StateProvinceStandard
- PostalCodeStandard
- DayOfBirth
- MonthOfBirth
- YearOfBirth
- PlaceOfBirth
- DocumentNumber
- DayOfExpiry
- MonthOfExpiry
- YearOfExpiry
- FullName
- FirstName
- LastName
- DayOfIssue
- MonthOfIssue
- YearOfIssue
- Issuer
- Class
- Mrz1
- Mrz2
- Mrz3
- Nationality
- Gender
- AlternateFirstName
- AlternateMiddleName
- AlternateLastName
- AlternateFullName
- AlternateAddressLine1
- AlternateAddressLine2
- AlternateFullAddress
- AlternateDocumentNumber
- AlternateDocumentNumber2
- AlternateDateOfBirth
- AlternateExpiryDate
- AlternateIssueDate