What is an Asynchronous Request?
Asynchronous requests do not block/wait for the API call to return from the server. The execution continues on in your program, and when the call returns from the server, a “callback” function is executed.
Why make an Asynchronous call?
Verifications with certain data sources can sometimes take longer to complete. If they take longer than 2 minutes, the request may time out before the transaction completes.
Document Verification:
- When the verification is done by datasources that review the document manually, then Trulioo API provides customers with the ability to verify uploaded document images and selfies through manual data source partners.
- Processing time for returning results from these verifications can be anywhere from a few minutes to several minutes long.
- The callback URL is useful here as this processing time can exceed normal HTTP response times.
Business Verification:
- Trulioo API provides customers with the ability to download shareholder and financial information documents.
- Processing time for returning these documents can vary as per the Government registry.
- The callback URL is useful here as this processing time can exceed normal HTTP response times.
Click here to get more details on Document Request Time.
Important
- In order to get optimal results from Trulioo's business verification service globally an asynchronous integration is required.
- Using Asynchronous calls allows you to submit verifications and get a quicker response if your application only needs to submit a transaction and does not need to process the result of a transaction right away.
Making an Asynchronous Request?
-
Submitting a Verify request with the CallBackUrl parameter defined allows a transaction to run asynchronously.
-
The CallBackUrl parameter must be a valid and secure URL. Trulioo recommends setting up your own server and URL to receive all the necessary information to review your response.
-
If callbacks from Trulioo API are not going to be consumed, provide the following URL in CallBackUrl field:
<<endpoint>>/connection/v1/async-callback
-
This will ensure that the data from the call back remains in Trulioo API and the asynchronous request can be executed without calling external systems.
-
Once the request is submitted, Trulioo API updates the client with transaction state updates - at the URL specified - until the transaction completes.
-
Once the transaction is complete, a Transaction Record ID (TRID) is available in the response. Get Transaction Status updates are synchronous. Trulioo recommends polling status updates at 15 second intervals.
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.
Identity Verification
The following Request is made when you make an Asynchronous Call during the process of Identity Verification:
POST <<endpoint>>/verifications/v1/verify
Authorization: Basic ACCESS_TOKEN
Content-Type: application/json
body:
{
"AcceptTruliooTermsAndConditions": true,
"ConfigurationName": "Identity Verification",
"CallBackUrl": "<<endpoint>>/connection/v1/async-callback",
"ConsentForDataSources": [],
"CountryCode": "US",
"DataFields": {
"PersonInfo": {
"FirstGivenName": "German",
"MiddleName": "Leandro",
"FirstSurName": "Stuarts",
"DayOfBirth": "22",
"MonthOfBirth": "10",
"YearOfBirth": "1980"
},
"Location": {
"BuildingNumber": "123",
"StreetName": "123",
"City": "123",
"StateProvinceCode": "TX",
"PostalCode": "123"
},
"DriverLicence": {
"Number": "123",
"State": "CA"
},
"Passport": {
"Mrz1": "123",
"Mrz2": "123"
}
}
}
Document Verification
The following Request is made when you make an Asynchronous Call during the process of Document Verification:
POST <<endpoint>>/verifications/v1/verify
Authorization: Basic ACCESS_TOKEN
Content-Type: application/json
body:
{
"AcceptTruliooTermsAndConditions": true,
"CleansedAddress": false,
"VerboseMode": true,
"ConfigurationName": "Identity Verification",
"CallBackUrl": "<<endpoint>>/connection/v1/async-callback",
"CountryCode": "US",
"DataFields": {
"PersonInfo": {
"FirstGivenName": "Timothy",
"FirstSurName": "Jones"
},
"Document": {
"DocumentFrontImage":"/9j/4QAYRXhpZgAASUkqAAgAAAAA .....IQCEIQCEIQCEIQP/9k=",
"DocumentBackImage": "/9j/4QAYRXhpZgAASUkqAAgAAAAA......LKICIiAiIgIiICIiAiIg//Z",
"LivePhoto": "/9/9j/4QAYRXhpZgAASUkqAAgAAAAA .....JGHGTDKYFRFS/9k=",
"DocumentType": "DrivingLicence"
}
}
}
All responses will have content type application/json; charset=utf-8
Async Record Response
{
"TransactionID": "5a26c222-a6b3-460e-a2aa-0b71d8bf7b8c",
"UploadedDt": "0001-01-01T00:00:00",
"CountryCode": "US",
"ProductName": "Identity Verification",
"Record": {
"RecordStatus": "nomatch",
"DatasourceResults": [],
"Errors": [],
"Rule": {}
},
"Errors": []
}
Status Updates
The TransactionRecordId populates when Status is Completed.
Updates are available at the URL provided in the 'CallBackUrl' field, unless you are utilizing the Trulioo API callback URL:
<<endpoint>>/connection/v1/async-callback
// returned at CallBackUrl
{
"TransactionId": "5a26c222-a6b3-460e-a2aa-0b71d8bf7b8c",
"TransactionRecordId": "9070d025-41fb-4c73-801d-d49be264fd20",
"Status": "Completed"
}
// when using <<endpoint>>/connection/v1/async-callback
{
"TransactionId": "5a26c222-a6b3-460e-a2aa-0b71d8bf7b8c",
"TransactionRecordId": "9070d025-41fb-4c73-801d-d49be264fd20",
"Status": "Completed",
"UploadedDt": "2019-03-18T17:28:15",
"IsTimedOut": false
}
To review your transaction's results, perform a GET Transaction Record request with the completed transaction's resulting TRID.
Full Record Response
{
"InputFields": [
{
"FieldName": "YearOfBirth",
"Value": "1980"
},
{
"FieldName": "FirstName",
"Value": "German"
},
{
"FieldName": "MiddleName",
"Value": "Leandro"
},
{
"FieldName": "LastName",
"Value": "Stuarts"
}
],
"TransactionID": "5a26c222-a6b3-460e-a2aa-0b71d8bf7b8c",
"UploadedDt": "2019-03-18T17:28:15",
"CountryCode": "US",
"ProductName": "Identity Verification",
"Record": {
"TransactionRecordID": "9070d025-41fb-4c73-801d-d49be264fd20",
"RecordStatus": "nomatch",
"DatasourceResults": [
{
"DatasourceName": "International Watchlist",
"DatasourceFields": [
{
"FieldName": "FirstSurName",
"Status": "missing"
},
{
"FieldName": "FirstGivenName",
"Status": "missing"
},
{
"FieldName": "YearOfBirth",
"Status": "missing"
},
{
"FieldName": "MiddleName",
"Status": "missing"
}
],
"AppendedFields": [
{
"FieldName": "WatchlistState",
"Data": "Clear"
}
],
"Errors": [],
"FieldGroups": []
}
],
"Errors": [],
"Rule": {
"RuleName": "Category 3 KYC v3",
"Note": "Match(FamilyAndGivenInitial, DOB) or Match(FamilyAndGivenInitial, FullAddress) or Match(FamilyAndGivenInitial, ID) MiddleName Ignored"
}
},
"Errors": []
}