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

eKYC request

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"
        ]
    }
    ]
}

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

eKYC error responses

• 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

eKYC Reason Codes

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.