United States Credit Bureau
eKYC US Credit Bureau leverages numerous sources of truth to streamline and enhance the customer identity verification process for more accurate and efficient authentication, reducing fraud, and ensuring regulatory compliance.
Integration
eKYC module configuration for the US Credit Bureau source requires that certain fields such as country, name, taxId are mandatory fields as you are verifying the other fields (eg. name) against the taxId. You will even notice in our API responses a "taxIdNameMatch" for example.
User input flow
Direct API Approach
All module configurations and user data can be forwarded directly in the request for performing an eKYC search. This will override existing configuration and data collected about the user.
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation
POST /omni/externalVerification/ekyc
This endpoint performs an eKYC check for the individual specified. Note: Endpoint can have empty body {} and in that case information will be pulled from module configuration and session details.
- plugins: must be ["kyc"]: (mandatory)
- source:: (mandatory) String. Must be: "US_CREDIT_BUREAU_1".
- ssn: (mandatory) String. 9 digit US TaxID of the individual (eg. 123456789)
- firstName: (mandatory) String. First name of the individual.
- middleName: (optional) String. Middle name of the individual.
- surName: (mandatory) String. Last name of the individual.
- street: (mandatory) String. Full street including house number and apartment number.
- city: (mandatory) String. City of the individual's address. (eg. San Francisco).
- state: (mandatory) String. Two letter state of the individual's address (eg. CA).
- postalCode: (mandatory) String. postalCode formatted based on per-country postalCode basis.
- countryCode: (mandatory) String. Two letter Alpha-2 country code. (must be US).
- dateOfBirth: (optional) String. Format: yyyy-mm-dd (eg. 1986-01-04)
- email: (optional) String. Email address of the individual (eg. [email protected])
- phone: (optional) String. Phone number associated to the individual (eg. +12125550123 )
Direct API Response
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation
Note: Endpoint can have empty body {} and in that case information will be pulled from module configuration and session details.
{
"kyc": [
{
"key": "customer",
"reasonCodes": [
"PAVN",
"PNNS",
"PNMB",
"PMU",
"PABM",
"PSDBM",
"EANI",
"TTIQ",
"TPSMT",
"TPDNV",
"TSTUT"
]
},
{
"key": "addressRiskLevel",
"status": "low",
"reasonCodes": [
"A70SS"
]
},
{
"key": "emailDomainLevel",
"status": "low"
},
{
"key": "emailLevel",
"status": "medium"
},
{
"key": "phoneCarrier",
"status": "Multiple Ocn Listing"
},
{
"key": "phoneLevel",
"status": "high"
},
{
"key": "phoneLineType",
"status": "FixedVoIP"
},
{
"key": "taxIdAddressMatch",
"status": "exact"
},
{
"key": "taxIdDobMatch",
"status": "exact"
},
{
"key": "taxIdLevel",
"status": "medium",
"reasonCodes": [
"TTIQ",
"TPSMT",
"TPDNV",
"TSTUT"
]
},
{
"key": "taxIdMatch",
"status": "exact"
},
{
"key": "taxIdNameMatch",
"status": "fuzzy"
},
{
"key": "taxIdStateMatch",
"status": "exact"
},
{
"key": "overallLevel",
"status": "medium"
}
]
}
Please refer to error response to see conventional HTTP response codes to indicate the success or failure of an API request.
API responses
US API Key | Status | Definition |
---|---|---|
taxIdMatch | exact fuzzy, no match, or unknown | Matches taxID submitted against the taxID related to the closest matching identity found with all submitted information. |
taxIdNameMatch | exact, fuzzy, no match, or unknown | Matches full name submitted against the taxID related to the closest matching identity found with all submitted information from firstName, middleName (optional), and surName. |
taxIdDobMatch | exact, fuzzy, no match, or unknown | Matches name submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdStateMatch | exact, no match, or unknown | Matches state submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdAddressMatch | exact, no match, or unknown | Matches address submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdLevel | low, medium, high, very_high | Tax ID Level is provided in detail below. Scroll to Tax ID Risk Level |
phoneLineType | Mobile, Landline, FixedVOIP, NonFixedVOIP, or Other | If there is phone data available, this field provides the phone line type of the phone number inputted. |
phoneCarrier | eg. T-Mobile | If there is phone data available, this field provide the phone carrier of the phone number inputted. |
phoneLevel | low, medium, high, very_high | Phone level is provided in detail below. Scroll to Phone Risk Level |
addressRiskLevel | low, medium, high, very_high | Address Risk level is provided in detail below. Scroll to Address Risk Level |
emailLevel | low, medium, high, very_high | Email Risk level is provided in detail below. Scroll to Email Risk Level |
emailDomainLevel | low, high | Email Domain Risk level is provided in detail below. Scroll to Email Risk Level |
overallLevel | low, medium, high, very_high | overallLevel is customized to your needs and requirements for low, medium, high_very and determines whether sessions should be passed or failed. Our dedicated customer support team can assist you in customizing this to your needs. As a default overallLevel = taxIdLevel |
customer "reasonCodes": [] | eg. PAVN, PNNS | Reason codes help you contextualize matches and risk levels further. All reason codes and their descriptions can be accessed here . More context also provided below in single session dashboard results section |
*Note: A match returning unknown indicates that no information was found for that specific attribute for the closest match identity.
Tax ID Matches
SSN verification is not a direct Social Security Administration database social security number lookup. Instead, this product takes a US-based identity and compares the Name, DoB, Address, Email, Phone to 3rd party data including credit header files, which contains PII (name, date of birth, social security number), address history, consumer history length, and other information from credit reports stripped of tradelines and other credit information. Other 3rd party data used in matching includes phone records, phone carrier information, email records, bankruptcies, deceased data, IP information, and other public records.
The submitted attributes (eg. Name, DOB, Address, Email, Phone, SSN) are used to find the closest matching identity, with the data match information returned.
US API Key | Status | Definition |
---|---|---|
taxIdMatch | exact fuzzy, no match, or unknown | Matches taxID submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdNameMatch | exact, fuzzy, no match, or unknown | Matches name submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdDobMatch | exact, fuzzy, no match, or unknown | Matches name submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdStateMatch | exact, no match, or unknown | Matches state submitted against the taxID related to the closest matching identity found with all submitted information |
taxIdAddressMatch | exact, fuzzy, no match, or unknown | Matches address submitted against the taxID related to the closest matching identity found with all submitted information |
*Note: A match returning unknown indicates that no information was found for that specific attribute for the closest match identity.
Fuzzy definitions for each taxIdMatch
Fuzzy taxIdNameMatch
Two names are labeled a fuzzy match if at least one of the following criteria is met:
- first names exact match
- last names exact match
- first name and last name swapped, and exact match if swapped back
- first name and last name from compared-name-1 is contained in compared-name-2 and compared-name-1 is at least length-5
- For example:
- first_name = “Joanna” and last name = “Smith” from the application
- internally in the credit header file the record “Joanna Lucinda Smith” exists
- This would be a fuzzy match as both Joanna and Smith are in the full name
- For example:
- Restricted Damerau-Levenshtein distance between two names less than 3 and both names are at least length-5.
Fuzzy taxIDDobMatch
- Two DOBs are labeled a fuzzy match if they are not exactly matched and one of the following requirements is met:
- Two components of the DOBs (year, month and day) are an exact match, e.g. 1987-01-05 vs 1987-06-05, 1987-01-05 vs 2000-01-05
- Month and day are swapped, e.g. 1987-12-06 vs 1987-06-12
Fuzzy taxIDMatch
- Two SSNs are labeled a fuzzy match if they are not exactly matched and their Restricted Damerau-Levenshtein distance is less or equal to 3.
Fuzzy taxIDStateMatch
- For state, there is no fuzzy match type.
Fuzzy taxIDAddressMatch
- Includes the following use cases:
- partial match to street data (e.g. misspelling of street name or missing street number) and all other address fields match
- no match to state, but all other address fields match
- no match to zipcode, but all other address fields match
- no match to city, but all other address fields match
TaxID Risk Level
TaxID Risk Level is a signal that is derived off of taxIdMatch, taxIdNameMatch, and taxIdDobMatch as a default.
Low
- Rule 1: If taxIdDobMatch returns exact
- Rule 2: If taxIdMatch returns exact
- Rule 3: If taxIdNameMatch returns exact
Medium
- Rule 1: If taxIdDobMatch returns fuzzy
- Rule 2: If taxIdMatch returns fuzzy
- Rule 3: If taxIdNameMatch returns fuzzy
High
- Rule 1: If taxIdDobMatch returns no match
- Rule 2: If taxIdMatch returns no match
- Rule 3: If taxIdNameMatch returns no match
Very High
- Rule 1: If taxIdDobMatch, taxIdMatch, and taxIdNameMatch returns no match
Address Risk Level
Address Risk Level is a signal derived from a combination of factors including: whether or not the address is valid or not, address deliverability based on USPS deliverability data for that address, commercial vs. residential buildings and a Lob based confidence score. Lob confidence score, created by one of the largest direct mail automation services, indicates the likelihood that the address is a valid, mail-receiving address.
AddressRiskLevel is not based off address verification to the name or other fields user has submission but rather the risk of the address itself.
Note: these are our default recommended thresholds; however, this can be customized if you prefer.
Low
- Rule 1:
- Address is valid and
- Over 70% of mailpieces Lob has sent to this address were delivered successfully and recent mailings were also successful and
- The address is deliverable by the USPS or the address is deliverable to the building's default address but is missing secondary unit information. There is a chance the mail will not reach the intended recipient.
- Result: addressRiskLevel == low
Medium
- Rule 1: Address is valid. However, no tracking data exists for this address or lob deliverability was unable to find a corresponding level of mail success.
- Rule 2: Address is valid and between 40% and 70% of mailpieces Lob has sent to this address were delivered successfully and the address is deliverable to the building's default address but is missing secondary unit information. There is a chance the mail will not reach the intended recipient.
- Result: If either of these two rules are hit, result of addressRiskLevel == medium
High
- Rule 1: If the address is valid but there is low confidence of the address. This is because less than 40% of mailpieces Lob has sent to this address were delivered successfully and recent mailings weren't successful.
- Result: addressRiskLevel == high
Very_high
- Rule 1: If the address is not a valid address and the address is not deliverable by the USPS
- Result: addressRiskLevel == very_high
Phone Risk Level
Phone Level is generated based on a risk number outputted between 0-1000 with 1000 being the highest risk. This number is calculated off of an analysis of phone number usage velocity, traffic patterns, phone type, telecom carrier, history of fraud etc. to predict risk.
Note: these are our default recommended thresholds; however, this can be customized if you prefer.
Low
- Rule: Phone risk score ≤ 500
- Result: phoneLevel == low
Medium
- Phone risk score ≥ 501 && Phone risk score ≤ 800
- Result: phoneLevel == medium
High
- Phone risk score ≥ 801 && Phone risk score ≤ 900
- Result: phoneLevel == high
Very High
- Phone risk score ≥ 901
- Result: phoneLevel == very_high
Email Risk Level
Email risk level is a signal based on an ML model (which leverages age, velocity, network signals, domain reputation, etc). The risk score is outputted as number between 0-100.
Note: these are our default recommended thresholds; however, this can be customized if you prefer.
Low
- Rule: Email risk score ≤ 20
- Result: emailLevel == low
Medium
- Email risk score ≥ 21 && Email risk score ≤ 84
- Result: emailLevel == medium
High
- Email risk score ≥ 85 && Email risk score ≤ 98
- Result: emailLevel == high
Very High
- Email risk score ≥ 98
- Result: emailLevel == very_high
Email Domain Risk Level
EmailDomainLevel is a machine learning based email risk score of 0 – 100 to identify high risk and fraudulent email domains. 100 is highest risk.
Note: these are our default recommended thresholds; however, this can be customized if you prefer. Incode does not have default recommendations for medium or very_high levels and instead only uses this field to identify what risky domains are.
Low
- Rule: If high risk domain not identified, then default to low.
- Result: emailDomainLevel == low
High
- Email Domain risk score ≥ 90
- Result: emailDomainLevel == high
Single Session Dashboard Result
See above in the example single session dashboard results, you can see the bottom section "Codes" that can help you further interpret the results of matches and risk levels in your single session dashboard. All reason codes can be accessed here.
Updated 29 days ago