# United States
United States eKYC verification supports multiple sources of truth, including telco databases, credit bureau records, USPS-verified address data, and state driver's license records. Because the response schema and calculation logic differ meaningfully between US sources, each source is documented separately below. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common response semantics that apply across all sources.
## Available sources
| Source | API source string | Description |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| US TELCO 1 | `US_TELCO_1` | Verifies submitted data against telco records associated with the provided phone number. |
| US TELCO 2 | `US_TELCO_2` | Verifies submitted data against telco records associated with the provided phone number. |
| US TELCO 4 | `US_TELCO_4` | Verifies submitted data against telco records associated with the provided phone number. |
| US TELCO 5 | `US_TELCO_5` | Verifies submitted data against telco records associated with the provided phone number. |
| US CREDIT BUREAU 1 | `US_CREDIT_BUREAU_1` | Verifies submitted data against credit bureau records associated with the provided tax ID (SSN). |
| US CREDIT BUREAU 3 | `US_CREDIT_BUREAU_3` | Verifies submitted data against credit bureau records. |
| US ADDRESS 1 | `US_Address_1` | Verifies submitted data against USPS-verified address records. |
| US DRIVERS LICENSE 1 | `US_DRIVERS_LICENSE_1` | Verifies submitted driver's license details against state driver's license records. |
## US TELCO 1
### Request parameters
| Parameter | Required | Description |
| ------------- | --------- | ----------------------------------------------------------- |
| `source` | Mandatory | Must be `US_TELCO_1`. |
| `country` | Mandatory | Must be `US`. |
| `phone` | Mandatory | Phone number in E.164 format (for example, `+14081234567`). |
| `firstName` | Mandatory | First name of the individual. |
| `surName` | Mandatory | Last name of the individual. |
| `street` | Optional | Full street including house number and apartment number. |
| `city` | Optional | City of the individual's address. |
| `state` | Optional | Two-letter state code. |
| `postalCode` | Optional | Postal code. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
| `email` | Optional | Email address. |
| `dlNumber` | Optional | Driver's license number. |
| `dlState` | Optional | Two-letter driver's license state. |
| `last4SSN` | Optional | Last four digits of SSN. |
### Response fields
US TELCO 1 anchors verification on the phone number. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common status values.
| Field | Statuses | Description |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phoneNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches name submitted against the name associated with the phone in the source of truth. |
| `phoneAddressMatch` | `exact`, `fuzzy`, `nomatch` | Matches address submitted against the address associated with the phone in the source of truth. |
| `phoneCityMatch` | `exact`, `nomatch` | Matches city submitted against the city associated with the phone in the source of truth. |
| `phoneStateMatch` | `exact`, `nomatch` | Matches state submitted against the state associated with the phone in the source of truth. |
| `phoneZipcodeMatch` | `exact`, `nomatch` | Matches zip code submitted against the zip code associated with the phone in the source of truth. |
| `phoneDobMatch` | `exact`, `nomatch` | Matches date of birth submitted against the date of birth associated with the phone. |
| `phoneEmailMatch` | `exact`, `nomatch` | Matches email submitted against the email associated with the phone in the source of truth. |
| `dlNumberCheck` | `exact`, `nomatch` | Matches driver's license number submitted against the number associated with the phone. |
| `dlStateCheck` | `exact`, `nomatch` | Matches driver's license state submitted against the state associated with the phone. |
| `nameRiskLevel` | `low`, `medium`, `high` | Risk level associated with the submitted name. |
| `addressRiskLevel` | `low`, `medium`, `high` | Risk level associated with the submitted address, independent of address matching.
{/* TODO: Confirm with PM. The previous per-source documentation described it as based on a proprietary matching algorithm scored 0-100 against the submitted address, but the API Reference describes it more generally as based on USPS deliverability and address validity signals (Lob-based confidence). Confirm which is accurate for US_TELCO_1 specifically, since the calculation may differ from the tax-ID-anchored sources where addressRiskLevel definitely uses USPS deliverability. */} |
| `phoneLevel` | `low`, `medium`, `high` | Risk level associated with the submitted phone. |
| `overallLevel` | `low`, `medium`, `high` | Overall risk level. See below for calculation logic. |
### overallLevel calculation
`overallLevel` is calculated based on `phoneNameMatch` and `phoneAddressMatch`:
- `low` when `phoneNameMatch` and `phoneAddressMatch` are both `exact`.
- `medium` when any of the following apply:
- `phoneNameMatch` is `exact` AND `phoneAddressMatch` is `fuzzy` or `nomatch`.
- `phoneNameMatch` is `nomatch` AND `phoneAddressMatch` is `fuzzy`.
- `phoneNameMatch` is `fuzzy` AND `phoneAddressMatch` is `fuzzy`.
- `high` when `phoneNameMatch` and `phoneAddressMatch` are both `nomatch`.
Contact your Incode representative to customize the `overallLevel` calculation for your use case.
### Risk level calculations
`nameRiskLevel` and `addressRiskLevel` are calculated from proprietary matching algorithms scored 0-100:
- `low`: score is 70-100.
- `medium`: score is 30-69.
- `high`: score is less than 30.
## US TELCO 2
### Request parameters
| Parameter | Required | Description |
| ------------- | --------- | ---------------------------------------------------------------------- |
| `source` | Mandatory | Must be `US_TELCO_2`. |
| `countryCode` | Mandatory | Must be `US`. |
| `phone` | Mandatory | Phone number in E.164 format (for example, `+14081234567`). |
| `firstName` | Optional | First name of the individual. |
| `surName` | Optional | Last name of the individual. This source does not process middle name. |
| `street` | Optional | Full street including house number and apartment number. |
| `city` | Optional | City of the individual's address. |
| `state` | Optional | Two-letter state code. |
| `postalCode` | Optional | Postal code. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
### Response fields
US TELCO 2 anchors verification on the phone number.
| Field | Statuses | Description |
| ------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phoneMatch` | `exact`, `nomatch` | Whether the phone number exists in the source of truth. |
| `phoneNameMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches name submitted against the name associated with the phone. Does not account for middle name. |
| `phoneAddressMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches address submitted against the address associated with the phone. |
| `phoneCityMatch` | `exact`, `nomatch`, `unknown` | Matches city submitted against the city associated with the phone. |
| `phoneStateMatch` | `exact`, `nomatch`, `unknown` | Matches state submitted against the state associated with the phone. |
| `phoneZipcodeMatch` | `exact`, `nomatch`, `unknown` | Matches zip code submitted against the zip code associated with the phone. |
| `phoneDobMatch` | `exact`, `nomatch` | Matches date of birth submitted against the date of birth associated with the phone. `nomatch` includes cases where no DOB information was available. |
| `phoneCarrier` | String | Phone carrier associated with the submitted phone number. |
| `phoneLineType` | String | Type of phone line (for example, `Mobile`). |
| `phoneLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted phone. |
| `addressRiskLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted address, independent of address matching. |
| `overallLevel` | `low`, `medium`, `high`, `very_high` | Overall risk level, customizable per customer requirements. |
### phoneNameMatch calculation
`phoneNameMatch` uses a proprietary matching algorithm scored from -1 to 100. Does not account for middle name.
- `unknown`: score is -1.
- `nomatch`: score is 0-29.
- `fuzzy`: score is 30-99.
- `exact`: score is 100.
### phoneAddressMatch calculation
`phoneAddressMatch` uses a proprietary matching algorithm scored from -1 to 100.
- `unknown`: score is -1.
- `nomatch`: score is 0-29.
- `fuzzy`: score is 30-69.
- `exact`: score is 70-100. The default exact threshold is 70 to account for slight variations in input such as apartment or house number.
### phoneLevel calculation
`phoneLevel` is calculated from a phone risk score (0-1000, with 1000 as highest risk):
- `low`: score is 500 or less.
- `medium`: score is 501-800.
- `high`: score is 801-900.
- `very_high`: score is 901 or greater.
### addressRiskLevel calculation
`addressRiskLevel` is a signal based on address validity, USPS deliverability, commercial vs. residential classification, and a Lob-based confidence score.
- `low`: The address is valid, over 70% of Lob mailpieces to this address were delivered successfully, recent mailings were successful, and the address is USPS-deliverable (or deliverable to the building's default address but missing secondary unit information).
- `medium`: The address is valid, but either no tracking data exists, or between 40% and 70% of Lob mailpieces were delivered successfully.
- `high`: The address is valid, but less than 40% of Lob mailpieces were delivered successfully and recent mailings were not successful.
- `very_high`: The address is not valid and not deliverable by USPS.
## US TELCO 4
### Request parameters
| Parameter | Required | Description |
| -------------- | --------- | ---------------------------------------------------------------------- |
| `source` | Mandatory | Must be `US_TELCO_4`. |
| `countryCode` | Mandatory | Must be `US`. |
| `phone` | Mandatory | Phone number in E.164 format (for example, `+14081234567`). |
| `firstName` | Optional | First name of the individual. |
| `surName` | Optional | Last name of the individual. This source does not process middle name. |
| `street` | Optional | Full street including house number and apartment number. |
| `city` | Optional | City of the individual's address. |
| `state` | Optional | Two-letter state code. |
| `postalCode` | Optional | Postal code. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
| `emailAddress` | Optional | Email address. |
### Response fields
US TELCO 4 anchors verification on the phone number. It returns match fields at both the aggregate (`phoneNameMatch`, `phoneAddressMatch`) and component (`phoneFirstNameMatch`, `phoneLastNameMatch`, `phoneStreetMatch`) levels.
| Field | Statuses | Description |
| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phoneMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Whether the phone number exists in the source of truth. |
| `phoneFirstNameMatch` | `match`, `fuzzy`, `nomatch`, `unknown` | Matches first name submitted against the value associated with the phone. |
| `phoneLastNameMatch` | `match`, `fuzzy`, `nomatch`, `unknown` | Matches last name submitted against the value associated with the phone. |
| `phoneNameMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches full name against the name associated with the phone. Does not account for middle name. |
| `phoneStreetMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches street submitted against the street associated with the phone. |
| `phoneCityMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches city submitted against the city associated with the phone. |
| `phoneStateMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches state submitted against the state associated with the phone. |
| `phoneZipcodeMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches zip code submitted against the zip code associated with the phone. |
| `phoneAddressMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches full address submitted against the address associated with the phone. |
| `phoneDobMatch` | `exact`, `nomatch`, `unknown` | Matches date of birth submitted against the value associated with the phone. |
| `phoneEmailMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches email submitted against the email associated with the phone. |
| `phoneCarrier` | String | Phone carrier associated with the submitted phone number. |
| `phoneLineType` | String | Type of phone line (for example, `Mobile`). |
| `phoneLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted phone. |
| `phoneRiskLevel` | `low`, `medium`, `high`, `very_high` (with reason codes) | Risk level associated with the submitted phone, with reason codes. Uses the same logic as `phoneLevel`. |
| `emailRiskLevel` | `low`, `medium`, `high` (with reason codes) | Risk level associated with the submitted email.
{/* TODO: Confirm with PM. Existing eKYC Overall Risk Level documentation referenced a 1-6 email risk band scale with EAF1/EAF2/EAF3 reason code interactions and disposable domain checks, but it is unclear whether that logic applies to US TELCO 4's emailRiskLevel field, US CREDIT BUREAU 1's emailLevel field, or both. Provide the calculation rules that apply here. */} |
| `overallLevel` | `low`, `medium`, `high` | Overall risk level, customizable per customer requirements. |
### phoneNameMatch calculation
`phoneNameMatch` is derived from `phoneFirstNameMatch` and `phoneLastNameMatch`:
- `exact`: `phoneFirstNameMatch` and `phoneLastNameMatch` are both `exact` (or `match`).
- `nomatch`: `phoneFirstNameMatch` and `phoneLastNameMatch` are both `nomatch`.
- `unknown`: `phoneFirstNameMatch` and `phoneLastNameMatch` are both `unknown`.
- `fuzzy`: all other cases.
### phoneAddressMatch calculation
`phoneAddressMatch` is derived from the component address fields:
- `exact`: `phoneStreetMatch`, `phoneCityMatch`, `phoneStateMatch`, and `phoneZipcodeMatch` are all `exact`.
- `nomatch`: all four component fields are `nomatch`.
- `unknown`: all four component fields are `unknown`.
- `fuzzy`: all other cases.
### phoneLevel calculation
`phoneLevel` is calculated from a proprietary matching score (-1 to 100):
- `low`: score is 300 or less.
- `medium`: score is 300-600.
- `high`: score is 600-800.
- `very_high`: score is 800 or greater.
## US TELCO 5
### Request parameters
| Parameter | Required | Description |
| -------------- | --------- | ----------------------------------------------------------- |
| `source` | Mandatory | Must be `US_TELCO_5`. |
| `countryCode` | Mandatory | Must be `US`. |
| `phone` | Mandatory | Phone number in E.164 format (for example, `+14081234567`). |
| `firstName` | Optional | First name of the individual. |
| `middleName` | Optional | Middle name of the individual. |
| `surName` | Optional | Last name of the individual. |
| `street` | Optional | Full street including house number and apartment number. |
| `city` | Optional | City of the individual's address. |
| `state` | Optional | Two-letter state code. |
| `postalCode` | Optional | Postal code. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
| `emailAddress` | Optional | Email address. |
| `idNumber` | Optional | Individual's SSN. |
### Response fields
US TELCO 5 anchors verification on the phone number. Compared to US TELCO 4, it adds middle name matching, tax ID matching, and additional metadata fields.
| Field | Statuses | Description |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
| `checkStatus` | String | Outcome of the check. |
| `phoneMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Whether the phone number exists in the source of truth. |
| `phoneFirstNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches first name submitted against the value associated with the phone. |
| `phoneMiddleNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches middle name submitted against the value associated with the phone. |
| `phoneLastNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches last name submitted against the value associated with the phone. |
| `phoneNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches full name against the name associated with the phone. |
| `phoneStreetMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches street submitted against the value associated with the phone. |
| `phoneCityMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches city submitted against the value associated with the phone. |
| `phoneStateMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches state submitted against the value associated with the phone. |
| `phoneZipcodeMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches zip code submitted against the value associated with the phone. |
| `phoneAddressMatch` | `exact`, `fuzzy`, `nomatch` | Matches full address submitted against the value associated with the phone. |
| `phoneDobMatch` | `exact`, `nomatch` | Matches date of birth submitted against the value associated with the phone. |
| `phoneEmailMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches email submitted against the value associated with the phone. |
| `taxIdMatch` | `exact`, `nomatch` | Matches submitted tax ID against the tax ID related to the closest matching identity. |
| `isItin` | `true`, `false` | Whether the returned SSN is an ITIN. |
| `emailType` | String | Type of email (for example, `personal`, `business`). |
| `phoneCarrier` | String | Phone carrier associated with the submitted phone number. |
| `phoneLineType` | String | Type of phone line (for example, `mobile`). |
| `lastPorted` | Date | Date the number was last ported, in `yyyy-mm-dd` format. |
| `activityScore` | Integer | Activity score (0-1000) representing the quality of the phone number. |
| `overallLevel` | `low`, `medium`, `high` | Overall risk level. See below for calculation logic. |
### overallLevel calculation
`overallLevel` is calculated based on `phoneNameMatch`, `phoneDobMatch`, and `taxIdMatch`:
- `low` when `phoneNameMatch` is `exact` AND (`phoneDobMatch` OR `taxIdMatch`) is `exact`.
- `high` when `phoneNameMatch` is `nomatch` AND (`phoneDobMatch` OR `taxIdMatch`) is `nomatch`.
- `medium` for all other combinations.
Contact your Incode representative to customize the `overallLevel` calculation for your use case.
## US CREDIT BUREAU 1
### Request parameters
| Parameter | Required | Description |
| ------------- | --------- | -------------------------------------------------------- |
| `source` | Mandatory | Must be `US_CREDIT_BUREAU_1`. |
| `countryCode` | Mandatory | Must be `US`. |
| `ssn` | Mandatory | Nine-digit US tax ID (SSN). |
| `firstName` | Mandatory | First name of the individual. |
| `middleName` | Optional | Middle name of the individual. |
| `surName` | Mandatory | Last name of the individual. |
| `street` | Mandatory | Full street including house number and apartment number. |
| `city` | Mandatory | City of the individual's address. |
| `state` | Mandatory | Two-letter state code. |
| `postalCode` | Mandatory | Postal code. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
| `email` | Optional | Email address. |
| `phone` | Optional | Phone number in E.164 format. |
### Response fields
US CREDIT BUREAU 1 anchors verification on the tax ID (SSN) but does not perform a direct Social Security Administration lookup. Instead, the submitted attributes (name, DOB, address, email, phone, SSN) are used to find the closest matching identity from third-party data including credit header files, phone records, email records, bankruptcies, deceased data, IP information, and other public records. Match results are then returned against that closest match.
The risk levels returned by this source reflect an assessment of whether the submitted identity is likely to be synthetic. A first-party synthetic identity is one where the applicant provides a true name and DOB but a fictitious SSN (often to obscure other parts of their profile). A third-party synthetic identity is one where the name, DOB, and SSN together describe a fictitious person (commonly used in organized identity fraud). `low` risk levels indicate the submitted identity is unlikely to be synthetic; `high` and `very_high` levels indicate elevated risk of synthetic identity fraud or, for `taxIdLevel`, a name or DOB mismatch against the SSN.
| Field | Statuses | Description |
| ------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `taxIdMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches submitted tax ID against the closest matching identity. |
| `taxIdNameMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches submitted full name (first, middle, last) against the closest matching identity. |
| `taxIdDobMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches submitted date of birth against the closest matching identity. |
| `taxIdStateMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches submitted state against the closest matching identity. |
| `taxIdAddressMatch` | `exact`, `nomatch`, `unknown` | Matches submitted address against the closest matching identity. |
| `taxIdLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the tax ID. |
| `phoneCarrier` | String | Phone carrier associated with the submitted phone number, if phone data is available. |
| `phoneLineType` | `Mobile`, `Landline`, `FixedVOIP`, `NonFixedVOIP`, `Other` | Phone line type, if phone data is available. |
| `phoneLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted phone. |
| `addressRiskLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted address, independent of address matching. |
| `emailLevel` | `low`, `medium`, `high`, `very_high` | Risk level associated with the submitted email. |
| `emailDomainLevel` | `low`, `high` | Risk level associated with the submitted email's domain. |
| `overallLevel` | `low`, `medium`, `high`, `very_high` | Overall risk level. Defaults to the value of `taxIdLevel`. |
### Fuzzy match definitions
US CREDIT BUREAU 1 uses specific fuzzy match rules for each field.
**Fuzzy taxIdNameMatch** is returned when at least one of the following applies:
- First names match exactly.
- Last names match exactly.
- First and last names are swapped and match when unswapped.
- The submitted first and last names appear inside the source-of-truth full name, and the submitted names are at least five characters each. For example, submitted `Joanna Smith` against source-of-truth `Joanna Lucinda Smith`.
- The restricted Damerau-Levenshtein distance between the two names is less than three, and both names are at least five characters.
**Fuzzy taxIdDobMatch** is returned when the DOBs are not an exact match and:
- Two of three components (year, month, day) match exactly (for example, `1987-01-05` vs. `1987-06-05`).
- Month and day are swapped (for example, `1987-12-06` vs. `1987-06-12`).
**Fuzzy taxIdMatch** is returned when the SSNs are not an exact match and their restricted Damerau-Levenshtein distance is three or less.
**Fuzzy taxIdAddressMatch** is returned when any of the following applies:
- Partial match to street data (misspelling of street name, missing street number) and all other address fields match.
- No match on state, but all other address fields match.
- No match on zip code, but all other address fields match.
- No match on city, but all other address fields match.
**Fuzzy taxIdStateMatch** does not exist. State fields return only `exact`, `nomatch`, or `unknown`.
### taxIdLevel calculation
`taxIdLevel` is derived from `taxIdMatch`, `taxIdNameMatch`, and `taxIdDobMatch`:
- `low`: `taxIdMatch`, `taxIdNameMatch`, and `taxIdDobMatch` all return `exact`.
- `medium`: at least one of `taxIdMatch`, `taxIdNameMatch`, or `taxIdDobMatch` returns `fuzzy`.
- `high`: at least one of `taxIdMatch`, `taxIdNameMatch`, or `taxIdDobMatch` returns `nomatch`.
- `very_high`: `taxIdMatch`, `taxIdNameMatch`, and `taxIdDobMatch` all return `nomatch`.
### phoneLevel calculation
`phoneLevel` is calculated from a phone risk score (0-1000, with 1000 as highest risk):
- `low`: score is 500 or less.
- `medium`: score is 501-800.
- `high`: score is 801-900.
- `very_high`: score is 901 or greater.
### addressRiskLevel calculation
`addressRiskLevel` is a signal based on address validity, USPS deliverability, commercial vs. residential classification, and a Lob-based confidence score. It is not based on address verification against the submitted name.
- `low`: The address is valid, over 70% of Lob mailpieces were delivered successfully, recent mailings were successful, and the address is USPS-deliverable (or deliverable to the building's default address but missing secondary unit information).
- `medium`: The address is valid, but either no tracking data exists, or between 40% and 70% of Lob mailpieces were delivered successfully.
- `high`: The address is valid, but less than 40% of Lob mailpieces were delivered successfully and recent mailings were not successful.
- `very_high`: The address is not valid and not deliverable by USPS.
### emailLevel calculation
`emailLevel` is based on a machine-learning model that leverages email age, velocity, network signals, and domain reputation. The risk score is a value from 0-100.
- `low`: score is 20 or less.
- `medium`: score is 21-84.
- `high`: score is 85-98.
- `very_high`: score is greater than 98.
### emailDomainLevel calculation
`emailDomainLevel` uses a machine-learning model to identify high-risk email domains, with a risk score of 0-100.
- `low`: default when a high-risk domain is not identified.
- `high`: score is 90 or greater.
Incode does not have default recommendations for `medium` or `very_high` at the domain level.
## US CREDIT BUREAU 3
{/* TODO: Confirm with PM — the actual minimum required fields for US CREDIT BUREAU 3. Existing source documentation lists source, country, firstName, and surName as mandatory, with dateOfBirth OR phone required as an additional anchor. However, the existing 400 error message reads "name and country are minimum required fields," which implies phone or DOB may not actually be enforced. Confirm the true set of mandatory fields, and whether the DOB-or-phone requirement is enforced at the API level. */}
### Request parameters
| Parameter | Required | Description |
| ------------- | ----------- | ----------------------------------------------------------------------- |
| `source` | Mandatory | Must be `US_CREDIT_BUREAU_3`. |
| `country` | Mandatory | Must be `US`. |
| `firstName` | Mandatory | First name of the individual. |
| `middleName` | Optional | Middle name of the individual. |
| `surName` | Mandatory | Last name of the individual. |
| `dateOfBirth` | Conditional | Format: `yyyy-mm-dd`. Either `dateOfBirth` or `phone` must be provided. |
| `phone` | Conditional | Phone number. Either `dateOfBirth` or `phone` must be provided. |
| `street` | Optional | Street name. |
| `houseNo` | Optional | House number. |
| `city` | Optional | City of the individual's address. |
| `state` | Optional | State. |
| `postalCode` | Optional | Postal code. |
| `email` | Optional | Email address. |
| `idNum` | Optional | SSN (Social Security Number). |
### Response fields
US CREDIT BUREAU 3 anchors verification on the source-of-truth register. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common match field definitions and status values.
| Field | Statuses | Description |
| -------------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `firstNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches first name submitted against the value in the source of truth. |
| `middleNameMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches middle name submitted against the value in the source of truth. |
| `lastNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches last name submitted against the value in the source of truth. |
| `fullNameMatch` | `exact`, `fuzzy`, `nomatch` | Matches full name submitted against the value in the source of truth. |
| `dobMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches date of birth submitted against the value in the source of truth. |
| `streetMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches street name submitted against the value in the source of truth. |
| `houseNoMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches house number submitted against the value in the source of truth. |
| `streetAddressMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches street and house number submitted against the value in the source of truth. |
| `cityMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches city submitted against the value in the source of truth. |
| `stateMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches state submitted against the value in the source of truth. |
| `postalCodeMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches postal code submitted against the value in the source of truth. |
| `fullAddressMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches full address submitted against the value in the source of truth. |
| `idNumMatch` | `exact`, `nomatch`, `nodata` | Matches SSN submitted against the value in the source of truth. |
| `phoneMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches phone submitted against the value in the source of truth. |
| `emailMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches email submitted against the value in the source of truth. |
| `overallLevel` | `low`, `medium`, `high` | Overall risk level. See below for calculation logic. |
### overallLevel calculation
`overallLevel` is calculated based on the submitted full name and at least one identity-anchoring field:
- `low` when `fullNameMatch` is `exact` AND (`dobMatch` OR `fullAddressMatch` OR `idNumMatch` OR `phoneMatch`) is `exact`.
- `high` when `fullNameMatch` and `idNumMatch` are both `nomatch`.
- `medium` for all other combinations.
Contact your Incode representative to customize the `overallLevel` calculation for your use case.
## US ADDRESS 1
### Request parameters
US ADDRESS 1 requires all address fields as mandatory.
| Parameter | Required | Description |
| ------------- | --------- | ---------------------------------------------------------------------- |
| `source` | Mandatory | Must be `US_Address_1`. |
| `countryCode` | Mandatory | Must be `US`. |
| `street` | Mandatory | Full street including house number and apartment number. |
| `city` | Mandatory | City of the individual's address. |
| `state` | Mandatory | Two-letter state code. |
| `postalCode` | Mandatory | Postal code. |
| `firstName` | Optional | First name of the individual. |
| `surName` | Optional | Last name of the individual. This source does not process middle name. |
### Response fields
US ADDRESS 1 anchors verification on the address, using USPS-verified address data. Match results and additional address-quality signals are returned.
| Field | Statuses | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `nameMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches name submitted against the name associated with the address. Does not account for middle name. |
| `streetMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches street submitted against the value in the source of truth. |
| `cityMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches city submitted against the value in the source of truth. |
| `stateMatch` | `exact`, `nomatch`, `unknown` | Matches state submitted against the value in the source of truth. |
| `zipcodeMatch` | `exact`, `nomatch`, `unknown` | Matches zip code submitted against the value in the source of truth. |
| `addressMatch` | `exact`, `fuzzy`, `nomatch`, `unknown` | Matches full address submitted against the value in the source of truth. |
| `deliverability` | `deliverable`, `deliverable_unnecessary_unit`, `deliverable_incorrect_unit`, `deliverable_missing_unit`, `undeliverable` | Represents likelihood that the address is deliverable. See below. |
| `addressValid` | `true`, `false` | Whether the address exists as a real location. See below. |
| `addressRiskLevel` | `low`, `medium`, `high`, `very_high` (with reason codes) | Represents likelihood that the address is deliverable, along with reason codes. |
| `overallLevel` | `low`, `medium`, `high`, `very_high` | Overall risk level, customizable per customer requirements. |
### deliverability values
- `deliverable`: The address is deliverable by USPS.
- `deliverable_unnecessary_unit`: The address is deliverable but the secondary unit information is unnecessary.
- `deliverable_incorrect_unit`: The address is deliverable to the building's default address, but the secondary unit provided may not exist. Mail may not reach the intended recipient.
- `deliverable_missing_unit`: The address is deliverable to the building's default address but is missing secondary unit information. Mail may not reach the intended recipient.
- `undeliverable`: The address is not deliverable by USPS.
### addressValid
`addressValid` indicates whether the address was found in a comprehensive dataset including USPS records, open-source mapping data, and proprietary mail delivery data. This is a broader test than `deliverability`: an address may be valid (exists as a real location) but not deliverable by USPS.
### addressMatch calculation
`addressMatch` is derived from the component address fields:
- `exact`: `streetMatch`, `cityMatch`, `stateMatch`, and `zipcodeMatch` are all `exact`.
- `nomatch`: `streetMatch` is `nomatch` AND (`cityMatch` is `nomatch` OR `zipcodeMatch` is `nomatch`).
- `unknown`: `streetMatch` is `unknown` AND (`cityMatch` is `unknown` OR `zipcodeMatch` is `unknown`).
- `fuzzy`: all other cases.
## US DRIVERS LICENSE 1
US DRIVERS LICENSE 1 verifies submitted driver's license details against state driver's license records. It is commonly used in scenarios that require age verification, such as couriers and delivery services confirming the individual is above the legal age.
US DRIVERS LICENSE 1 currently supports 42 of the 50 US states. The following states are not supported: Alaska, California, Louisiana, Minnesota, New Hampshire, New York, Oklahoma, Pennsylvania, and Utah.
### Request parameters
{/* TODO: Confirm with PM — the current list of supported and unsupported US states, as this may have changed since the existing source documentation was written. Note that the existing docs list nine unsupported states but describe them as "42 of the 50" supported, which does not add up. */}
| Parameter | Required | Description |
| ------------- | --------- | ------------------------------------------------------- |
| `source` | Mandatory | Must be `US_DRIVERS_LICENSE_1`. |
| `countryCode` | Mandatory | Must be `US`. |
| `state` | Mandatory | Two-letter driver's license state (for example, `CA`). |
| `dlNumber` | Mandatory | Driver's license number. Format varies per state. |
| `firstName` | Optional | First name of the individual. |
| `surName` | Optional | Last name of the individual. |
| `dateOfBirth` | Optional | Format: `yyyy-mm-dd`. |
| `dlExpireAt` | Optional | Driver's license expiration date. Format: `yyyy-mm-dd`. |
### Response fields
US DRIVERS LICENSE 1 anchors verification on the driver's license record. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common status values.
| Field | Statuses | Description |
| ----------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
| `dlNumberMatch` | `exact`, `nomatch` | Whether the submitted driver's license number matches the state driver's license record. |
| `dlDobMatch` | `exact`, `nomatch` | Matches date of birth submitted against the driver's license record. |
| `dlNameMatch` | `exact`, `approximatematch`, `nomatch` | Matches name submitted against the driver's license record. |
| `dlExpirationDateMatch` | `exact`, `nomatch` | Matches expiration date submitted against the driver's license record. |
| `dlStateCodeMatch` | `exact`, `nomatch` | Matches state submitted against the driver's license record. |