Retrieving and Analyzing the Assertion Response

This article provides the details of how to retrieve the transaction response (also known as assertion). The assertion response returns the metrics that determine acceptance, rejection, or manual review decisions via the Instnt engine.

It authenticates information for each customer, including their first name, last name, phone number, email, and more. It includes data and metadata about the enrolling device, biometric behaviors, geolocation, network cohort analysis, KYC, and document verification outcomes.

API Endpoints

An 'transaction_id' is shorthand for an Instnt transaction ID, navigate to the Transaction Review page via Instnt dashboard and enter the specific transaction ID into the field above. You can find more information in the Transaction Review guide.

You can also view the user interface (UI) for this API Endpoint

Error Codes Response

Code Description
200 Ok
400 Bad Request
404 Not Found
405 Method Not Allowed
408 Request Timeout

 

Assertion Response Payload

The example code block below displays the payload:

{"id":1,
"instnttxnid":"aabbc-1234-asdasd-4014-caxc1",
"form_key_formaudit":"v12345",
"form_key_doc_verify":null,
"instnttxntimestamp":"2022-09-09T16:19:12.853157Z",
"instntuserid":212,
"instntapiversion":"1.4.5",
"form":{
	"dob":"1900-01-01",
	"zip":"12345",
	"city":"New York City",
	"email":"abc@abc.org",
	"state":"NY",
	"surName":"Doe",
	"form_key":"v12345",
	"client_ip":"127.0.0.1",
	"firstName":"Jo",
	"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36","expires_on":"1662743739",
	"nationalId":"123-45-6789",
	"instnttxnid":null,
	"mobileNumber":"+123456789",
	"physicalAddress":"1 Main Street",
	"client_referer_url":"",
	"client_referer_host":""},
"device":{
	"nativeDeviceDetails":{
							"os":"Other",
							"osVersion":null,
							"botProbability":"0"},
	"is_bot":false,
	"ipLocation":{
				"country":{"name":"United States"},
				"city":{"name":"New York City"},
				"state":"NY",
				"postalCode":"12345","timezone":"America/Chicago","latitude":0,"longitude":0}
		},
"biometrics":{
	"bot_Anomaly":false,
	"rat_Anomaly":false,
	"userCoached":false,
	"differIP":false,
	"flag_CorruptedSession":false,
	"flag_Whitelisted":false,
	"SessionRisk":0.35,
	"behavioralScore":0.5},
"documents":null,
"model":[
	{"name":"Aggregate Decision","version":"1.0.0","source":"internal","decision":"ACCEPT","overrideFlag":false,"overrideComments":null,"score":0,"thresholds":{"accept_min":0.0,"accept_max":0,"reject_min":1,"reject_max":1.0}},
	{"name":"1st Party Fraud Model","version":"1.0.0","source":"internal","decision":"ACCEPT","overrideFlag":false,"overrideComments":null,"score":0.117011120695112,"thresholds":{"accept_min":0.0,"accept_max":0.5,"reject_min":0.86,"reject_max":1.0}},
	{"name":"3rd Party Fraud Model","version":"1.0.0","source":"internal","decision":"REVIEW","overrideFlag":false,"overrideComments":null,"score":0.0218173367328576,"thresholds":{"accept_min":0.0,"accept_max":0.013,"reject_min":0.67,"reject_max":1.0}},
	{"name":"Synthetic Fraud Model","version":"1.0.0","source":"internal","decision":"ACCEPT","overrideFlag":false,"overrideComments":null,"score":0.00897116046962712,"thresholds":{"accept_min":0.0,"accept_max":0.0275,"reject_min":0.59,"reject_max":1.0}}],
"cohorts":{
	"ip_frequency_24h":1,
	"name_frequency_24h":1,
	"phone_frequency_24h":1,
	"email_frequency_24h":1,
	"address_frequency_24h":1,
	"device_frequency_24h":0},
"kyc":null,
"justification":{
	"reason_codes":[
		{"code":"CA104","description":"No hits on KYC watchlists, KYC pass","sentiment":"Positive"},
		{"code":"DOB102","description":"DOB is verified with PII vendors","sentiment":"Positive"},
		{"code":"EE100","description":"Email address is a personal address","sentiment":"Neutral"},
		{"code":"EE102","description":"Email address is free","sentiment":"Neutral"},
		{"code":"EN103","description":"Last Name may have changed in the past","sentiment":"Neutral"},
		{"code":"PA101","description":"Address age > 180 days","sentiment":"Neutral"},
		{"code":"PA102","description":"Physical address verified","sentiment":"Positive"},
		{"code":"PA103","description":"City matches","sentiment":"Positive"},
		{"code":"PE100","description":"Email matches","sentiment":"Positive"},
		{"code":"PE101","description":"Email valid and mainDomain","sentiment":"Neutral"},
		{"code":"PE102","description":"Email age > 180 days","sentiment":"Neutral"},
		{"code":"PN101","description":"Name matches","sentiment":"Positive"},
		{"code":"PP100","description":"Phone number matches","sentiment":"Positive"},
		{"code":"PP101","description":"Phone number belongs to a Major Carrier","sentiment":"Neutral"},
		{"code":"PP102","description":"Phone age > 180 days","sentiment":"Neutral"},
		{"code":"SSN100","description":"SSN verified","sentiment":"Positive"}],
"correlations":{
	"NameEmail":100,
	"NamePhone":100,
	"PhoneEmail":100,
	"NameAddress":100,
	"AddressEmail":87,
	"AddressPhone":100,
	"NamePhoneEmail":100,
	"NameAddressEmail":95,
	"NameAddressPhone":100,
	"AddressPhoneEmail":95,
	"NameAddressPhoneEmail":97}},
"form_key":"v12345",
"form_key_checkselfie":null,
"ip":"REDACT",
"decision":"ACCEPT"}  

Note: The ‘iss’, ‘exp’, and ‘iat’ are registered claim names as per JSON Web Token standards. The assertion claim is a custom claim defined by Instnt.

Assertion Field Glossary

The following table lists the relevant fields in the assertion response payload along with their definitions:

String Definition
form All field entries input by a customer in a signup form that are verified and cross-referenced back to the user's name are returned as features with risk ratings.
device Device characteristics are fingerprinted to uniquely identify the device and returned as features with associates risk ratings.
assertion Contains customer information, the decision on the customer, and the instntid.
kyc Instnt's Know Your Customer compliance models for customer identification programs and customer due
diligence including correlations and hits on watchlists such as OFAC, PEP etc. are returned.
biometrics Passive user behaviors such as the way they type, press buttons etc. and cognitive behaviors such as how long they take to recollect their date of birth,
whether they copied and pasted their date of birth etc. are analyzed and returned as features with associated risk ratings.
bot_Anomaly The Bot Detection Flag indicates that robotic behavior was detected such as a typing rhythm that is too uniform or jittery mouse movements.
rat_Anomaly The Remote Access flag indicates that one or more remote access protocols were detected in the session.
userCoached The Coaching Detection flag indicates that the user has probably been coached to perform a transaction.
differIP The IP Changed Flag indicates that the IP address changed during the active session or is different than the last 20 sessions.
flag_CorruptedSession The Session Corrupted flag indicates that there was session level corruption, such as when a username changes during a session.
flag_Whitelisted The Whitelisted flag appears on any session where a user has been designated as white-listed by an BehavioSense Administrator.
SessionRisk Risk is a numerical measure of potentially fraudulent activity during the course of a session.
The Risk level can be a number greater than or equal to zero. A Risk level in the range of 0 to
1 is considered minimal risk, while over 1 is considered high risk and should be investigated.
behavioralScore Score (Behavioral Score) is a value ranging from 0 to 1.
Score indicates to what degree the behavioral timing data in the session matches the behavioral timing data in the trained User Profile.
A high Score means there is little difference between the timing data in the current session and that of the Profile,
while a low Score means the behavioral timing data of the logged in user did not match the data stored in the Profile.
cohort_analysis A comparison of model inputs for a specific user versus a cohort of users to see where they lie in the data.
hiddenIP The Hidden flag appears on any session where the origin of the IP address has been hidden, such as when a TOR exit node or VPN was in use.
error .jpg file submitted is an invalid file, submission was unable to complete.
exp The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
The processing of the "exp" claim requires that the current date/time MUST be before the expiration date/time listed in the "exp" claim.
iat The "iat" (issued at) claim identifies the time at which the JWT was
issued. This claim can be used to determine the age of the JWT. Its
value MUST be a number containing a NumericDate value. Use of this
claim is OPTIONAL.
iss The "iss" (issuer) claim identifies the principal that issued the
JWT. The processing of this claim is generally application specific.
The "iss" value is a case-sensitive string containing a StringOrURI
value. Use of this claim is OPTIONAL.
models The accept/reject/review decision made by Instnt's fraud detection models and the individual results from the model's assumptions are returned.
search_term The name that is passed into the KYC search
match_status Returns the status of the KYC match. "potential_match" if there is any match OR "no_match" if not
match_confidence Give some relative indication of match relevance. Ranging between 0 and 100
matched_media_urls The url links of adverse media sources
matched_names All possible names returned by the search
matched_entity_type Whether the matched entity is a person or organization
matched_types_detail Returns the detail of match types. It may be "name_exact", "aka_exact", "year_of_birth" based on the returned fields or "unknown" if the match is based on an acronym
matched_watchlist_types Types of watchlists the name exists in such as "adverse-media" or "sanction"
matched_watchlist_sources Specific sources of watchlists the name exists in
number_of_matches The number of possible matches
reason_codes A set of explanatory codes defining the reasoning for the decision within Instnt's fraud detection models
are returned for justification purposes and compliance with model governance requirements.

Document Authentication and Selfie Segment Names

The following table is a collection of the segment names listed in the authentication and 'matchselfie' fields in the documents subsection of the assertion response payload and their definitions:

Segment Name Action Description
Verified No rescan action suggested. Default Action Code.
Fraud Shield Failed as matched to a Fraud Shield Watchlist
Recapture All Rescan entire transaction
Recapture Selfie Rescan Selfie
Recapture ID Rescan ID front and back only
Expired ID Try a valid ID (non expired)
Unsupported ID Recapture All ID and Selfie Images
Potential Paper ID Recapture All ID and Selfie Images
Failed Failed transaction, but take no action
Submission Error Recapture All ID and Selfie Images
Document did not pass ... checks Rescan ID front and back. If ExpireDate is one of the checks failed,
please rescan and/or use a valid non-expired ID