DocumentationAPI Reference
General reference · eKYC Reference

eKYC API Reference

The External Verification (eKYC) endpoint (POST /omni/externalVerification/ekyc) verifies an individual's identity against country-specific data sources and returns a set of match and risk-level fields describing the result. This page explains the response semantics for that endpoint: how to interpret match fields, status values, risk levels, metadata fields, reason codes, error responses, and Risk Add-ons.

For the request contract (headers, request body schema, sample requests), see the External Verification (eKYC) API reference. For per-source response schemas, mandatory fields, and overallLevel calculations, see the country pages in this section. For the Brazil-only Income Verification endpoint (POST /omni/externalVerification/income), see the Brazil country page.

Response field categories

Response fields returned by the eKYC endpoint fall into three categories:

  • Match fields compare a submitted value (name, address, date of birth, and so on) against the value found in the source of truth. Match field names follow one of several patterns depending on how the source anchors verification (see the following section).
  • Risk level fields return aggregate risk assessments for the submitted values (overallLevel, phoneLevel, taxIdLevel, addressRiskLevel, emailLevel).
  • Metadata fields describe attributes of the source-of-truth data itself, rather than match statuses (for example, phoneCarrier, phoneLineType, panStatus, deliverability).

Not all fields appear in every response. The fields returned depend on the source used for the verification.

Match field naming conventions

Different sources anchor verification differently, and the match field names reflect the anchor. Understanding the anchor makes response schemas easier to read.

Anchor Match field pattern Examples of sources
Source of truth register firstNameMatch, dobMatch, idNumMatch, phoneMatch, and so on. Each submitted field is matched against its counterpart in the register. Argentina, Canada, Chile, Greece, Guatemala, Spain, Sweden, United Kingdom (Voter Register), US Credit Bureau 3
Phone number phoneNameMatch, phoneAddressMatch, phoneDobMatch, phoneCityMatch, and so on. Each submitted field is matched against the record associated with the submitted phone number. US Telco 1, US Telco 2, US Telco 4, US Telco 5
Tax ID taxIdMatch, taxIdNameMatch, taxIdDobMatch, taxIdAddressMatch, and so on. Each submitted field is matched against the record associated with the submitted tax ID. US Credit Bureau 1, Brazil Government (BR GOVT 1)
Address nameMatch, streetMatch, cityMatch, stateMatch, zipcodeMatch, addressMatch. Match fields focus on the address itself; the address also carries USPS deliverability and validity signals. US Address 1
Document Document-specific patterns: dlNumberMatch, dlNameMatch, dlDobMatch (driver's license); panNumberMatch, panNameMatch, panStatus (PAN card). US Drivers License, India PAN

See the country pages for the full response schema of each source.

Status values

Match fields return a status indicating the quality of the match. Common status values:

Status Meaning
exact The submitted value exactly matches the value in the source of truth.
fuzzy The submitted value approximately matches the value in the source of truth (per a proprietary algorithm).
approximatematch Alternative label for a fuzzy match, used by some sources (Brazil Government, Guatemala).
nomatch The submitted value does not match the value in the source of truth.
nodata No corresponding value was found in the source of truth to compare against.
unknown The source of truth does not have this information available for comparison.
unabletoverify The specific attribute could not be validated. Used by Brazil Government for address components when the individual has no driver's license record.

See the country pages for source-specific status values and their meanings.

Risk level fields

Risk level fields return aggregate risk assessments. The specific set of risk level fields returned varies by source.

Field Statuses Description
overallLevel low, medium, high, very_high The overall risk level for the verification. Calculation varies by source; see the country pages for source-specific calculation logic.
taxIdLevel low, medium, high, very_high Risk level associated with the submitted tax ID. Returned by tax-ID-anchored sources.
phoneLevel low, medium, high, very_high Risk level associated with the submitted phone number. Returned by phone-anchored sources and by sources that include phone risk scoring.
addressRiskLevel low, medium, high, very_high Risk level associated with the submitted address, independent of address matching. Based on USPS deliverability and address validity data.
emailLevel low, medium, high, very_high Risk level associated with the submitted email address. Based on validity, deliverability, breach history, and behavioral signals.
emailDomainLevel low, high Risk level associated with the submitted email's domain.

overallLevel is customizable per customer requirements. The calculations documented on each country page reflect Incode's default thresholds; contact your Incode representative to adjust thresholds for your use case.

Metadata fields

Some sources return metadata about the source-of-truth data itself, rather than match statuses. Common examples:

Field Type Description
phoneCarrier String The phone carrier associated with the submitted phone number (for example, T-Mobile USA, Verizon).
phoneLineType String The type of phone line (for example, Mobile, Landline, FixedVOIP, NonFixedVOIP).
lastPorted Date Date the phone number was last ported, in yyyy-mm-dd format. Only returned if the number has been ported.
activityScore Integer Activity score (0-1000) representing the quality of a phone number. Higher scores indicate better activity.
panStatus String Status of the PAN card (Active, Inactive). India PAN only.
panHolderType String The type of entity associated with the PAN number (for example, Individual, Business). India PAN only.
deliverability String USPS deliverability status of an address. US Address 1 only.
addressValid Boolean Whether the submitted address exists as a real location in postal, mapping, or delivery data sources. US Address 1 only.

See the country pages for the full set of metadata fields returned by each source.

Reason codes

Some sources return reason codes alongside match fields and risk level fields. Reason codes provide additional context for a match result or risk assessment (for example, indicating that an address matched but is a PO Box, or that a phone number is associated with a high-risk line type).

Reason codes are returned in a reasonCodes array on the relevant field. For the full list of reason codes and their meanings, see eKYC Reason Codes.

Error responses

The eKYC endpoint returns conventional HTTP response codes. Common error scenarios:

  • 400 Bad Request: Missing mandatory fields for the selected source. The response body identifies which field is missing. See each source's request parameters on the country pages for source-specific mandatory fields.
  • 400 Bad Request: Phone number not in international E.164 format (for example, +14081234567). Applies to any source that accepts phone as a parameter.
  • 400 Bad Request: Invalid country value for the selected source. The country parameter must match the expected country code for the source (for example, US, BR, GB, or GL for Risk Add-ons).

For the full list of HTTP response codes and general API error handling, see API responses.

Risk Add-ons

Risk Add-ons are supplementary checks that evaluate the trust and potential risk of a phone number or email address. They are invoked through the standard eKYC endpoint with country: "GL" and a source-specific identifier. Risk Add-ons can be run alongside a country-specific eKYC check or configured as standalone checks under the Global country with the Risk Add-ons Only source (see the eKYC Dashboard configuration page for details).

Phone Check

Source: PHONE_RISK_1

Evaluates a phone number and returns validity, activity, carrier information, and a risk score based on signals such as line type, VOIP or prepaid status, breach exposure, and spam reports.

Response fields:

Field Statuses / Type Description
phoneValid true, false Whether the phone number is properly formatted and valid for the country's carrier ranges.
phoneActive true, false, unknown Whether the phone number is a live, usable, currently active phone number.
phoneVOIP true, false, unknown Whether the phone number is a Voice Over IP (VOIP) or digital phone number.
phonePrepaid true, false, unknown Whether the phone number is associated with a prepaid service plan.
phoneRisky true, false, unknown Whether the phone number is associated with fraudulent activity, scams, robocalls, fake accounts, or similar.
phoneLineType String The type of line associated with the phone number.
phoneCarrier String The carrier associated with the phone number.
phoneLeaked true, false Whether the phone number has recently been exposed in an online database breach.
phoneSpammer true, false Whether the phone number has recently been reported for spam or harassing calls or texts.
phoneFraudScore low, medium, high Fraud score based on a proprietary scale: less than 75 is low, 75-85 is medium, greater than 85 is high.
overallLevel low, medium, high, very_high Aggregate risk assessment. See below for calculation logic.

overallLevel calculation:

  • very_high if phoneValid == false OR phoneActive == false OR phoneRisky == true OR phoneFraudScore == high
  • high if (phoneValid == false OR phoneActive == false) AND (phoneRisky == true OR phoneFraudScore == high)
  • medium if phoneValid == true AND phoneActive == true AND (phoneRisky == true OR phoneFraudScore == medium)
  • low otherwise

Advanced Phone Check

Source: PHONE_RISK_2

Extends Phone Check with additional intelligence signals: porting history, first-seen date in the data partner's network, associated social media platforms, breach history including first and last breach dates, and a digital footprint score. Returns a confidence level alongside the overall risk level.

Response fields:

Field Statuses / Type Description
phoneValid true, false Whether the phone number is valid.
phoneActive true, false Whether the phone number is a live, usable phone number that is currently active.
phonePorted true, false Whether the phone number has been ported.
currentCarrier String Current carrier or service provider.
previousCarrier String Previous carrier or service provider.
lastPorted Date Date the number was last ported in yyyy-mm-dd format. Only present if the number has been ported.
phoneLineType String Type of line (for example, mobile, landline).
isDisposable true, false Whether the phone number is a disposable type.
activityScore Integer Activity score (0-1000) representing the quality of the phone number.
activityDescription String Describes the amount of network activity available.
totalBreaches String Number of breaches the phone number was found in.
firstBreachDate Date Date the number was first found in a data breach.
lastBreachDate Date Date the number was most recently found in a data breach.
multipleBreachExposure true, false Whether the phone number was found in multiple breaches.
connectedPlatforms String Comma-separated list of social media platforms where an account is associated with this phone number.
digitalPresenceScore Integer Digital footprint score (0-1000).
footprintScore Integer Digital footprint score (0-1000). Higher scores indicate better activity and confidence.
phoneName String Name of the person associated with this phone number.
firstSeen Date Date when this phone number was first seen in the data partner's network.
checkStatus String Outcome of the check for the provided phone number.
confidenceLevel low, medium, high, very_high Confidence level in the verification result.
overallLevel low, medium, high, very_high Aggregate risk level for the phone number.

Email Check

Source: EMAIL_RISK_1

Evaluates an email address for validity, deliverability, and fraud risk. Includes signals for breach exposure, email address age, domain age, and legitimate user activity.

Response fields:

Field Statuses / Type Description
emailValid true, false Whether the email address appears valid.
emailDeliverability low, medium, high Likelihood that emails will be delivered to the recipient's mailbox.
emailLeaked true, false Whether the email address was associated with a recent third-party database leak.
emailFirstSeen String Estimated email address age, based on when the address was first discovered.
domainFirstSeen String When the email domain was registered.
emailUserActivity high, medium, low, none Frequency of legitimate purchases, account registrations, and other legitimate online behavior for this address.
emailFraudScore low, medium, high Fraud score: less than 75 is low, 75-85 is medium, greater than 85 is high.
overallLevel low, medium, high, very_high Aggregate risk assessment. See below for calculation logic.

overallLevel calculation:

  • very_high if emailValid == false OR emailDeliverability == low OR emailFraudScore == high
  • high if emailValid == false AND (emailDeliverability == low OR emailFraudScore == high)
  • medium if emailValid == true AND (emailDeliverability == medium OR emailFraudScore == medium)
  • low otherwise

Was this page helpful?