United States Telco 2
eKYC leverages U.S. telco sources of truth to streamline and enhance the customer identity verification process by accessing telecommunications data for more accurate and efficient authentication, reducing fraud, and ensuring regulatory compliance.
Integration
eKYC module configuration for the US Telco 2 source requires that both phone is a mandatory field as you are verifying the other fields (eg. name) against the phone. You will even notice in our API responses a "phoneNameMatch" for example.
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.
- plugins: must be ["kyc"]: (mandatory)
- source:: (mandatory) String. Must be: "US_TELCO_2".
- phone: (mandatory) String. Phone number of the individual (eg. +14081234567)
- firstName:: (optional) String. First name of the individual.
- surName: (optional) String. Last name of the individual. *Note: This source of truth cannot process middle name
- street: (optional) String. Full street including house number and apartment number.
- city: (optional) String. City of the individual's address. (eg. San Francisco).
- state: (optional) String. Two letter state of the individual's address (eg. CA).
- postalCode: (optional) 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)
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": "phoneStateMatch",
"status": "nomatch"
},
{
"key": "phoneLevel",
"status": "low"
},
{
"key": "phoneCarrier",
"status": "AT&T Wireless"
},
{
"key": "phoneZipcodeMatch",
"status": "nomatch"
},
{
"key": "phoneNameMatch",
"status": "unknown"
},
{
"key": "phoneDobMatch",
"status": "nomatch"
},
{
"key": "phoneMatch",
"status": "exact"
},
{
"key": "phoneAddressMatch",
"status": "exact"
},
{
"key": "phoneLineType",
"status": "Mobile"
},
{
"key": "overallLevel",
"status": "low"
},
{
"key": "phoneCityMatch",
"status": "nomatch"
},
{
"key": "addressRiskLevel",
"status": "low",
"reasonCodes": [
"A70SS"
]
}
]
}
US API Key | Status | Definition |
---|---|---|
phoneMatch | exact, nomatch | Identifies whether there is a match that this phone number exists in the source of truth |
phoneNameMatch | exact, fuzzy, nomatch, or unknown | Matches name submitted against the name associated to the phone in the source of truth. *Note this source of truth does not account for middle name See below for more info on phoneNameMatch |
phoneAddressMatch | exact, fuzzy, nomatch, or unknown | Matches address submitted against the address associated to the phone in the source of truth See below for more info on phoneAddressMatch |
phoneCityMatch | exact, nomatch, or unknown | Matches city submitted against the city associated to the phone in the source of truth |
phoneStateMatch | exact, nomatch, or unknown | Matches state submitted against the state associated to the phone in the source of truth |
phoneZipcodeMatch | exact, nomatch, or unknown | Matches zip code submitted against the zip code associated to the phone in the source of truth |
phoneDobMatch | exact, nomatch | Matches date of birth submitted against the date of birth associated to the phone in the source of truth Note: for DOB, nomatch includes both cases where non-matching DOB information was available and no DOB information was available |
addressRiskLevel | low, medium, high, or very_high | Address Risk Level is focused on the risk associated to the submitted address Note: AddressRiskLevel is not based off address verification to the name or other fields user has submission but rather the risk of the address itself See context below for more information around how low, medium, high, and very_high are calculated |
phoneLevel | low, medium, high, or very_high | Phone Risk Level is focused on the risk associated to the submitted phone See context below for more information around how low, medium, high, and very_high are calculated |
overallLevel | low, medium, high, or 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 |
phoneCarrier | eg. T-Mobile USA, Verizon, etc. | This key responds back with the phone carrier the submitted phone number is associated to |
phoneLineType | eg. Mobile, etc. | This key responds back with the phone line type associated to the submitted phone number |
Note: unknown is generated when the source of truth does not have this information available.
phoneNameMatch
PhoneNameMatch is the API response for both the submitted first and last name. The fields exact, fuzzy, nomatch, and unknown are mapped to a proprietary matching algorithm that is mapped to a score from -1 to 100. phoneNameMatch cannot account for middle name.
As a default, phoneNameMatch will return:
- unknown: matching score is -1
- nomatch: matching score is between 0-29
- fuzzy: matching score is between 30-99
- exact: matching score is between is 100
Note: Incode has set these mappings as the default; however, if you want to account for nicknames, we recommend adjusting this threshold. You can request threshold adjustments with our dedicated team and they can assist you with your use case and preferences.
phoneAddressMatch
PhoneAddressMatch is the API response key for the submitted address. The fields exact, fuzzy, nomatch, and unknown are mapped to a proprietary matching algorithm that is mapped to a score from -1 to 100.
As a default, phoneAddressMatch will return:
- unknown: matching score is -1
- nomatch: matching score is between 0-29
- fuzzy: matching score is between 30-69
- exact: matching score is between 70-100 (Default threshold is 70 due to slight variations of input such as apt number or house number etc)
Note: Incode has set these mappings as the default; however, you can request thresholds to be updated to your use case and preferences.
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
- Please refer to error response to see conventional HTTP response codes to indicate the success or failure of an API request.
- If phone is not in international E.164 format, you will see an error message.
- If both mandatory fields (phone & countryCode) are not submitted, you will see an error message
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 about 2 months ago