Overview

The nationality user attribute can be added to a service configuration in IDW to collect additional user data or enhance identity verification processes. This attribute is particularly important for government-issued document validation, such as verifying passports during identity proofing.

Configuring the nationality Attribute

The attribute can be configured, and its settings can be adjusted. For example:

• Visibility: Controls whether the attribute is shown to the end user.
• Editability: Determines if the user can update the attribute.
• Optional vs Required: Indicates whether the attribute is mandatory during onboarding or verification flows.

Sources of Input for Nationality

The nationality can be input by users or pre-populated via login flows:

User-Provided

Entered manually via UI (must match the appearance on the official document) ( the nationality is a text input field)

Customer-Populated

• Passed in through login_hint during session initialization
• Input format:
  • Full name (e.g., “American”)
  • ISO 3166-1 alpha-2 (e.g., "US")
  • ISO 3166-1 alpha-3 (e.g., "USA")
  • For reference please refer to this public github for country codes: https://github.com/Imagin-io/country-nationality-list/blob/master/countries.json

Document Verification Vendors

Incode

These vendors support the extraction of the nationality field from official documents, primarily passports.

📘

Note: Driver’s licenses typically do not include nationality and are not suitable for nationality validation.

Verification Workflow

Step-by-Step Flow

• User Input: User provides nationality through one of the supported methods (manual or login_hint).
• Document Upload: User uploads a document (preferably a passport) that includes nationality data.
• Vendor Extraction: Document verification vendor extracts nationality field from the uploaded document.
• Comparison: IDW compares the extracted nationality against the user-provided nationality.

Nationality Comparison Logic

The IDW system performs a comparison between:

• User-inputted nationality
• Vendor-extracted nationality from the document

Normalization Process

If the input was a code (alpha-2 or alpha-3), the system performs a lookup using the AXN database to resolve it to the full native nationality name.

Matching Criteria

The comparison is based on a configurable match threshold percentage.

A match returns a "Pass", while a non-match returns a "Fail".

Match Threshold Configuration

This threshold applies not only to nationality but also to other key identity data comparisons, such as:

• Full name match
• Date of birth match

Policy-Driven Customer Experience

From a customer perspective, the result of the nationality-document match can be leveraged in policy logic to dynamically route users:

Positive Match (Passes Threshold)

Customer can approve the user to move forward with minimal friction.

Negative Match (Fails Threshold)

Customer can step up the user to collect additional data or perform further verification (e.g., asking for another document, triggering manual review).

This allows the business to balance user experience and risk, while dynamically adapting based on the document verification outcome.

Leveraging Extracted Data in Flow Continuity

The IDW solution supports reusing the vendor-extracted data—such as nationality—as user input in future steps within the same verification flow.

Benefits of Reuse:

• Reduces user friction by auto-filling verified values.
• Enhances policy decisioning with verified and trusted data points.
• Maintains consistency across multi-step workflows (e.g., if nationality is later needed for eligibility or compliance rules).

Deployment Support: Hosted & API Models

The nationality attribute verification and validation capability is fully supported across both deployment models:

Gateway-Hosted Solution

• UI and verification orchestration managed by IDW
• Ideal for faster time to market and consistent experience

API Integration Solution

• Full control for customers integrating IDW via APIs
• Enables custom UX while leveraging IDW’s back-end verification and comparison logic

API Request Example - /slverify

Nationality can be added to the /slverify payload request like below:

{
"attributeType": "Nationality",
"dateCreated": "07/21/2023 13:02:03",
"values": {
"nationality": "FR"
}
},

OR

{
"attributeType": "Nationality",
"dateCreated": "07/21/2023 13:02:03",
"values": {
"nationality": "Française"
}
}

Example Use Case

• A user selects “France” from the dropdown.
• They upload a French passport.
• Acuant extracts the nationality as “Française”.
• The system compares the two and returns a high match score.
• Policy approves the user to proceed.
• In a downstream step requiring nationality, the system auto-injects the verified nationality into the workflow—no additional user action required.