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
| Environment | Location |
|---|---|
|
Production |
https://api.instnt.org/secure/transactions/{transaction_id} |
|
Pre-Prod |
https://preprod-api.instnt.org/secure/transactions/{transaction_id} |
|
Integration Sandbox |
https://sandbox-api.instnt.org/secure/transactions/{transaction_id} |
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 |