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 in the Trulioo Platform, particularly, can sometimes take longer to complete. If they take longer than 2 minutes, the request may time out before the transaction completes.
Business Verification:
- Trulioo 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 are not going to be consumed, provide the following URL in CallBackUrl field:
<<endpoint>>/v3/connection/async-callback
-
This will ensure that the data from the call back remains in Trulioo and the asynchronous request can be executed without calling external systems.
-
Once the request is submitted, the Trulioo Platform 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.
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.
Business Verification
The following Request is made when you make an Asynchronous Call during the process of Business Verification. In this example, the Trulioo provided Callback URL was used, but if you plan on setting up your own webhook address, it would replace the '/v1/async-callback' url found below:
POST <<endpoint>>/v3/business/verify
Authorization: OAuth
Content-Type: application/json
body:
{
"AcceptTruliooTermsAndConditions": true,
"CallBackUrl": "https://api.trulioo.com/v3/connection/async-callback",
"CleansedAddress": false,
"ConfigurationName": "Identity Verification",
"ConsentForDataSources": [],
"CountryCode": "CA",
"BusinessDataFields": {
"BusinessName": "Acme Inc.",
"BusinessRegistrationNumber": "BRN123ABC",
"JurisdictionOfIncorporation": "BC",
"DayOfIncorporation": 13,
"MonthOfIncorporation": 5,
"YearOfIncorporation": 1990,
"EnhancedProfile": true,
"Entities": true,
"Location": {
"BuildingNumber": "123",
"UnitNumber": "6",
"StreetName": "Main",
"StreetType": "st",
"City": "Vancouver",
"StateProvinceCode": "BC",
"PostalCode": "V6M 1A3"
},
"Communication": {
"Telephone": "1 (888) 782-2912",
"EmailAddress": "[email protected]"
}
},
"VerboseMode": false
}
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 callback URL:
<<endpoint>>/v3/connection/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
{
"TransactionID": "23a29398-631b-4921-a537-a594fae4fd37",
"UploadedDt": "2018-05-29T23:12:58",
"CountryCode": "CA",
"ProductName": "Identity Verification",
"Record": {
"TransactionRecordID": "fd244b13-8cfe-4235-a61a-eadcdd629859",
"RecordStatus": "match",
"DatasourceResults": [
{
"DatasourceName": "Business Insights 433673",
"DatasourceFields": [
{
"FieldName": "MonthOfIncorporation",
"Status": "match"
},
{
"FieldName": "PostalCode",
"Status": "missing"
},
{
"FieldName": "StreetType",
"Status": "missing"
},
{
"FieldName": "YearOfIncorporation",
"Status": "match"
},
{
"FieldName": "BusinessName",
"Status": "match"
},
{
"FieldName": "taxidnumber",
"Status": "missing"
},
{
"FieldName": "City",
"Status": "missing"
},
{
"FieldName": "BuildingNumber",
"Status": "missing"
},
{
"FieldName": "BusinessRegistrationNumber",
"Status": "match"
},
{
"FieldName": "Suburb",
"Status": "missing"
},
{
"FieldName": "BuildingName",
"Status": "missing"
},
{
"FieldName": "JurisdictionOfIncorporation",
"Status": "match"
},
{
"FieldName": "StateProvinceCode",
"Status": "missing"
},
{
"FieldName": "UnitNumber",
"Status": "missing"
},
{
"FieldName": "DayOfIncorporation",
"Status": "match"
},
{
"FieldName": "County",
"Status": "missing"
},
{
"FieldName": "StreetName",
"Status": "missing"
}
],
"AppendedFields": [
{
"FieldName": "JurisdictionOfIncorporation",
"Data": "BC"
},
{
"FieldName": "BusinessName",
"Data": "Acme Inc."
},
{
"FieldName": "BusinessStatus",
"Data": "Active"
},
{
"FieldName": "BusinessType",
"Data": "Corporation"
},
{
"FieldName": "EnhancedProfile",
"Data": "{\"Location\":{\"PrimaryAddress\":[{\"StreetAddressLine\":[{\"LineText\":\"1055 Hastings St W Suite 1200\"}],\"UndeliverableIndicator\":false,\"PrimaryTownName\":\"VANCOUVER\",\"TerritoryAbbreviatedName\":\"BC\",\"PostalCode\":\"V6E 2E9\",\"CountryISOAlpha2Code\":\"CA\",\"TerritoryOfficialName\":\"BRITISH COLUMBIA\",\"PremisesDetail\":[{\"PremisesAreaMeasurement\":7502,\"PremisesAreaMeasurementReliabilityText\":{\"@DNBCodeValue\":9093,\"$\":\"Estimated\"},\"PremisesAreaMeasurementUnitText\":{\"@DNBCodeValue\":3848,\"$\":\"Square Feet\"}}],\"CountryGroupName\":\"North America\",\"LatitudeMeasurement\":49.28765,\"LongitudeMeasurement\":-123.118534,\"GeographicalPrecisionText\":{\"@DNBCodeValue\":30257,\"$\":\"Street Address Centroid\"},\"RegisteredAddressIndicator\":false}]},\"Telecommunication\":{\"TelephoneNumber\":[{\"TelecommunicationNumber\":\"(778) 123-4567\",\"UnreachableIndicator\":false,\"InternationalDialingCode\":\"1\"}],\"WebPageAddress\":[{\"TelecommunicationAddress\":\"www.acme.com\"}]},\"Linkage\":{\"GlobalUltimateOrganization\":{\"PrimaryAddress\":[{\"StreetAddressLine\":[{\"LineText\":\"1055 Hastings St W Suite 1200\"}],\"UndeliverableIndicator\":false,\"PrimaryTownName\":\"VANCOUVER\",\"TerritoryAbbreviatedName\":\"BC\",\"PostalCode\":\"V6E 2E9\",\"CountryISOAlpha2Code\":\"CA\",\"TerritoryOfficialName\":\"BRITISH COLUMBIA\"}],\"DUNSNumber\":\"203111604\",\"OrganizationPrimaryName\":[{\"OrganizationName\":{\"$\":\"Acme Inc\"}}]},\"DomesticUltimateOrganization\":{\"PrimaryAddress\":[{\"StreetAddressLine\":[{\"LineText\":\"1055 Hastings St W Suite 1200\"}],\"UndeliverableIndicator\":false,\"PrimaryTownName\":\"VANCOUVER\",\"TerritoryAbbreviatedName\":\"BC\",\"PostalCode\":\"V6E 2E9\",\"CountryISOAlpha2Code\":\"CA\",\"TerritoryOfficialName\":\"BRITISH COLUMBIA\"}],\"DUNSNumber\":\"203111604\",\"OrganizationPrimaryName\":[{\"OrganizationName\":{\"$\":\"Acme Inc\"}}]},\"LinkageSummary\":{\"GlobalUltimateFamilyTreeLinkageCount\":2},\"FamilyTreeHierarchyLevel\":1},\"RegisteredDetail\":{\"LegalFormDetails\":{\"LegalFormText\":{\"$\":\"Corporation\",\"@DNBCodeValue\":451}},\"IncorporationYear\":\"2010\"},\"PrincipalsAndManagement\":{\"CurrentPrincipal\":[{\"PrincipalName\":{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"FullName\":\"John Doe\",\"@type\":\"fir:IndividualNameType\"},\"JobTitle\":[{\"JobTitleText\":{\"$\":\"Board Member\"}}],\"CurrentManagementResponsibility\":[{\"ManagementResponsibilityText\":{\"$\":\"Board of Directors\",\"@ManagementResponsibilityCode\":\"A1G7\"}}],\"PrincipalIdentificationNumberDetail\":[{\"@DNBCodeValue\":24215,\"@TypeText\":\"Professional Contact Identifier\",\"PrincipalIdentificationNumber\":\"2031116042\"}]},{\"PrincipalName\":{\"FirstName\":\"Jane\",\"LastName\":\"Doe\",\"FullName\":\"Jane Doe\",\"@type\":\"fir:IndividualNameType\"},\"JobTitle\":[{\"JobTitleText\":{\"$\":\"President & Board Member\"}}],\"CurrentManagementResponsibility\":[{\"ManagementResponsibilityText\":{\"$\":\"President\",\"@ManagementResponsibilityCode\":\"A1A6\"}},{\"ManagementResponsibilityText\":{\"$\":\"Board of Directors\",\"@ManagementResponsibilityCode\":\"A1G7\"}}],\"PrincipalIdentificationNumberDetail\":[{\"@DNBCodeValue\":24215,\"@TypeText\":\"Professional Contact Identifier\",\"PrincipalIdentificationNumber\":\"2031116041\"}]}]},\"ActivitiesAndOperations\":{\"LineOfBusinessDetails\":[{\"LineOfBusinessDescription\":{\"$\":\"Miscellaneous personal services, nec, nsk\"}}],\"PrimarySICCategoryValue\":\"I\"},\"SubjectHeader\":{\"OrganizationSummaryText\":\"Miscellaneous personal services, nec, nsk\",\"DUNSNumber\":\"11111604\",\"LastUpdateDate\":{\"$\":\"2020-07-01\"},\"MarketabilityIndicator\":true,\"DUNSSelfRequestIndicator\":false},\"IndustryCode\":{\"IndustryCode\":[{\"IndustryCodeDescription\":[{\"$\":\"Consumer Services\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":9120}],\"@DNBCodeValue\":25838,\"@TypeText\":\"D&B Hoovers Industry Code\",\"IndustryCode\":{\"$\":\"1208\"},\"DisplaySequence\":1},{\"IndustryCodeDescription\":[{\"$\":\"All Other Personal Services\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":9120}],\"@DNBCodeValue\":700,\"@TypeText\":\"NAICS\",\"IndustryCode\":{\"$\":\"812990\"},\"DisplaySequence\":1},{\"IndustryCodeDescription\":[{\"$\":\"All Other Personal Services\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":9120}],\"@DNBCodeValue\":24664,\"@TypeText\":\"North American Industry Classification System 2012\",\"IndustryCode\":{\"$\":\"812990\"},\"DisplaySequence\":1},{\"IndustryCodeDescription\":[{\"$\":\"Other service activities not elsewhere classified\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":9120}],\"@DNBCodeValue\":21182,\"@TypeText\":\"UK SIC 2003\",\"IndustryCode\":{\"$\":\"93.050\"},\"DisplaySequence\":1},{\"IndustryCodeDescription\":[{\"$\":\"CONSUMER BUYING SVC\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":2121}],\"@DNBCodeValue\":3599,\"@TypeText\":\"D&B Standard Industry Code\",\"IndustryCode\":{\"$\":\"72999904\"},\"DisplaySequence\":1},{\"IndustryCodeDescription\":[{\"$\":\"Misc personal services\",\"@LanguageCode\":39,\"@IndustryCodeDescriptionLengthCode\":1441}],\"@DNBCodeValue\":399,\"@TypeText\":\"US SIC (1987)\",\"IndustryCode\":{\"$\":\"7299\"},\"DisplaySequence\":1}]},\"Financial\":{\"KeyFinancialFiguresOverview\":[{\"StatementHeaderDetails\":{\"FinancialPeriodDuration\":\"P1Y\"},\"SalesRevenueAmount\":[{\"@CurrencyISOAlpha3Code\":\"USD\",\"@ReliabilityText\":\"Modelled\",\"@UnitOfSize\":\"SingleUnits\",\"$\":1791405},{\"@CurrencyISOAlpha3Code\":\"CAD\",\"@ReliabilityText\":\"Modelled\",\"@UnitOfSize\":\"SingleUnits\",\"$\":2368916}]}]},\"OrganizationName\":{\"OrganizationPrimaryName\":[{\"OrganizationName\":{\"$\":\"Acn Inc\"}}]},\"OrganizationDetail\":{\"FamilyTreeMemberRole\":[{\"FamilyTreeMemberRoleText\":{\"@DNBCodeValue\":12775,\"$\":\"Global Ultimate\"}},{\"FamilyTreeMemberRoleText\":{\"@DNBCodeValue\":12774,\"$\":\"Domestic Ultimate\"}},{\"FamilyTreeMemberRoleText\":{\"@DNBCodeValue\":12771,\"$\":\"Headquarters\"}}],\"StandaloneOrganizationIndicator\":false,\"ControlOwnershipDate\":{\"$\":\"2004\"},\"ControlOwnershipTypeText\":{\"@DNBCodeValue\":0,\"$\":\"Unknown\"},\"BoneyardOrganizationIndicator\":false,\"OperatingStatusText\":{\"@DNBCodeValue\":9074,\"$\":\"Active\"},\"OrganizationStartYear\":\"2010\"},\"EmployeeFigures\":{\"ConsolidatedEmployeeDetails\":{\"TotalEmployeeQuantity\":15,\"EmployeeCategoryDetails\":[{\"EmployeeBasisText\":{\"@DNBCodeValue\":9064,\"$\":\"Principals\"}}],\"ReliabilityText\":{\"@DNBCodeValue\":9093,\"$\":\"Estimated\"}}},\"Assessment\":{\"CommercialCreditScore\":[{\"MarketingRiskClassText\":{\"@DNBCodeValue\":10925,\"$\":\"Low\"}}]},\"SocioEconomicIdentification\":{\"MinorityOwnedIndicator\":false,\"FemaleOwnedIndicator\":false,\"SmallBusinessIndicator\":false,\"OwnershipEthnicity\":[{\"EthnicityTypeText\":{\"@DNBCodeValue\":0,\"$\":\"Unknown\"}}]}}"
},
{
"FieldName": "BusinessDetails",
"Data": "{\"resultId\":\"104506\",\"entityName\":\"Acme Inc.\",\"entityNumber\":\"BRN123ABC\",\"normalizedEntityStatus\":\"Active\",\"jurisdiction\":\"BC\",\"formationDate\":\"1990-05-13T00:00:00\",\"normalizedEntityType\":\"Corporation\"}"
},
{
"FieldName": "BusinessRegistrationNumber",
"Data": "BRN123ABC"
},
{
"FieldName": "DayOfIncorporation",
"Data": "13"
},
{
"FieldName": "MonthOfIncorporation",
"Data": "05"
},
{
"FieldName": "YearOfIncorporation",
"Data": "1990"
}
],
"Errors": [],
"FieldGroups": []
},
{
"DatasourceName": "International Watchlist",
"DatasourceFields": [
{
"FieldName": "BusinessName",
"Status": "missing"
}
],
"AppendedFields": [
{
"FieldName": "WatchlistState",
"Data": "Clear"
}
],
"Errors": [],
"FieldGroups": []
},
{
"DatasourceName": "Business Insights 480052",
"DatasourceFields": [
{
"FieldName": "BuildingNumber",
"Status": "match"
},
{
"FieldName": "POBox",
"Status": "missing"
},
{
"FieldName": "City",
"Status": "match"
},
{
"FieldName": "BusinessRegistrationNumber",
"Status": "match"
},
{
"FieldName": "BuildingName",
"Status": "missing"
},
{
"FieldName": "Telephone",
"Status": "missing"
},
{
"FieldName": "Suburb",
"Status": "missing"
},
{
"FieldName": "JurisdictionOfIncorporation",
"Status": "match"
},
{
"FieldName": "UnitNumber",
"Status": "match"
},
{
"FieldName": "DayOfIncorporation",
"Status": "match"
},
{
"FieldName": "StateProvinceCode",
"Status": "match"
},
{
"FieldName": "StreetName",
"Status": "match"
},
{
"FieldName": "MonthOfIncorporation",
"Status": "match"
},
{
"FieldName": "County",
"Status": "missing"
},
{
"FieldName": "StreetType",
"Status": "match"
},
{
"FieldName": "YearOfIncorporation",
"Status": "match"
},
{
"FieldName": "PostalCode",
"Status": "match"
},
{
"FieldName": "BusinessName",
"Status": "match"
},
{
"FieldName": "Source",
"Status": "missing"
}
],
"AppendedFields": [
{
"FieldName": "City",
"Data": "Vancouver"
},
{
"FieldName": "BusinessName",
"Data": "Acme Inc."
},
{
"FieldName": "PostalCode",
"Data": "V6M 1A3"
},
{
"FieldName": "BusinessStatus",
"Data": "Active"
},
{
"FieldName": "BusinessDetails",
"Data": "{\"CompanyName\":\"Acme Inc.\",\"RegistrationNumber\":\"BRN123ABC\",\"CompanyStatus\":\"Active\",\"RegisteredFullAddress\":\"123 Main St, Vancouver, V6M 1A3\",\"RegisteredAddress\":{\"street_address\":\"123 Main St\",\"locality\":\"Vancouver\",\"region\":\"BC\",\"postal_code\":\"V6M 1A3\",\"country\":\"CA\"},\"CountryCode\":\"ca\",\"DayOfIncorporation\":\"13\",\"MonthOfIncorporation\":\"05\",\"YearOfIncorporation\":\"1990\",\"Source\":\"https://www.realsource.com/data.html?corpId=BRN123ABC\",\"AdditionalData\":{\"dissolution_date\":null,\"company_type\":\"Corporation\",\"branch\":null,\"branch_status\":null,\"inactive\":false,\"created_at\":\"2015-12-15T23:28:19+11:00\",\"updated_at\":\"2018-05-02T16:43:43+10:00\",\"retrieved_at\":\"2017-02-25T21:41:28+11:00\",\"source\":{\"publisher\":\"Corporations Canada\",\"url\":\"https://www.realsource.com/data.html?corpId=F154630\",\"retrieved_at\":\"2017-02-25T21:41:28+11:00\"},\"agent_name\":null,\"alternative_names\":[],\"previous_names\":[],\"number_of_employees\":null,\"native_company_number\":null,\"industry_codes\":[],\"identifiers\":[{\"identifier\":{\"uid\":\"859486577RC0001\",\"identifier_system_code\":\"ca_bn\",\"identifier_system_name\":\"Canadian Business Number\"}}],\"trademark_registrations\":[{\"trademark_registration\":{\"mark_details\":{\"mark_text\":\"secretstuff\",\"mark_image_url\":\"https://www.realsource.com/data.html\"},\"register_name\":\"United States Patent and Trademark Office\",\"registration_date\":\"2015-08-25\",\"expiry_date\":null}},{\"trademark_registration\":{\"mark_details\":{\"mark_text\":\"copyrights\",\"mark_image_url\":\"https://www.realsource.com/data.html\"},\"register_name\":\"United States Patent and Trademark Office\",\"registration_date\":\"2015-08-25\",\"expiry_date\":null}},{\"trademark_registration\":{\"mark_details\":{\"mark_text\":\"Brand Name\",\"mark_image_url\":\"https://www.realsource.com/data.html"},\"register_name\":\"United States Patent and Trademark Office\",\"registration_date\":\"2015-02-24\",\"expiry_date\":null}}],\"corporate_groupings\":[],\"data\":null,\"financial_summary\":null,\"home_company\":null,\"controlling_entity\":null,\"ultimate_beneficial_owners\":[],\"filings\":[],\"officers\":[{\"officer\":{\"id\":19371865,\"name\":\"John Bob\",\"position\":\"director\",\"uid\":null,\"start_date\":null,\"end_date\":null,\"occupation\":null,\"inactive\":false,\"current_status\":null,\"address\":\"123 West 9st\\nVancouver BC V8W 1P0\\nCanada\",\"nationality\":null,\"date_of_birth\":null}},{\"officer\":{\"id\":177852560,\"name\":\"Mary Berry\",\"position\":\"director\",\"uid\":null,\"start_date\":null,\"end_date\":null,\"occupation\":null,\"inactive\":false,\"current_status\":null,\"address\":\"123 - a different avenue\\nLangley BC V8U 3K7\\nCanada\",\"nationality\":null,\"date_of_birth\":null}},{\"officer\":{\"id\":19397462,\"name\":\"David O'Leary\",\"position\":\"director\",\"uid\":null,\"start_date\":null,\"end_date\":null,\"occupation\":null,\"inactive\":false,\"current_status\":null,\"address\":\"#6- The Place\\nSan Francisco CA 68716\\nUnited States\",\"nationality\":null,\"date_of_birth\":null}},{\"officer\":{\"id\":193546563,\"name\":\"Samantha Stafford\",\"position\":\"director\",\"uid\":null,\"start_date\":null,\"end_date\":null,\"occupation\":null,\"inactive\":false,\"current_status\":null,\"address\":\"35 West East Street\\nVancouver BC V0G 8P0\\nCanada\",\"nationality\":null,\"date_of_birth\":null}},{\"officer\":{\"id\":1574146,\"name\":\"Amanda Anaconda\",\"position\":\"director\",\"uid\":null,\"start_date\":null,\"end_date\":null,\"occupation\":null,\"inactive\":false,\"current_status\":null,\"address\":\"41 Up Down Place\\2nd Floor\\nNew York NY 12359\\nUnited States\",\"nationality\":null,\"date_of_birth\":null}}]}}"
},
{
"FieldName": "Source",
"Data": "https://www.realsource.com/data.html"
},
{
"FieldName": "StateProvince",
"Data": "BC"
},
{
"FieldName": "DayOfIncorporation",
"Data": "13"
},
{
"FieldName": "MonthOfIncorporation",
"Data": "05"
},
{
"FieldName": "YearOfIncorporation",
"Data": "1990"
},
{
"FieldName": "BuildingNumber",
"Data": "123"
},
{
"FieldName": "UnitNumber",
"Data": "1"
},
{
"FieldName": "StreetName",
"Data": "Main"
},
{
"FieldName": "StreetType",
"Data": "St"
},
{
"FieldName": "BusinessRegistrationNumber",
"Data": "BRN123ABC"
}
],
"Errors": [],
"FieldGroups": []
}
],
"Errors": [],
"Rule": {
"RuleName": "RuleScript BusinessVerify",
"Note": "Script manually created"
}
},
"Errors": []
}