DocumentationAPI Reference
General reference · eKYC Reference / eKYC Coverage

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 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 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 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 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.

Was this page helpful?