# eKYC (Electronic Know Your Customer)

The eKYC (electronic Know Your Customer) module collects and verifies a user's personal identity data against authoritative data sources. The data can include the user's name, email, address, phone, tax ID, date of birth, and nationality. The module can prefill fields from data captured earlier in the flow, such as a scanned document or a proof-of-address document, and validate them against your Incode configuration.

For an overview of this module and how it works, see [eKYC (electronic Know Your Customer)](https://developer.incode.com/docs/ekyc).

How you use this module depends on your integration pattern. When your app defines the steps in code, you add the module to an `IncdOnboardingFlowConfiguration` as shown below; when the flow is defined in Dashboard, you reference it by session token and let the back end drive the steps. See [Integration Approaches](https://developer.incode.com/docs/ios-flow-configuration).

**Availability:** All variants.

## Add eKYC

Add the module with `addEKYC(...)` on your `IncdOnboardingFlowConfiguration`. Call it with no arguments for the default configuration. The default configuration sets every `check<Field>` flag to `false`, so no field is verified unless you explicitly enable it. Pass an `ExternalVerificationConfiguration` to control which fields are checked and where each field's value comes from.

```swift
// Default configuration
flowConfig.addEKYC()

// Custom configuration
flowConfig.addEKYC(
    configuration: ExternalVerificationConfiguration(
        checkName: true,
        nameSource: .document,
        checkAddress: true,
        addressSource: .userInput
    )
)
```

The fields that are shown and how they are verified can also depend on your eKYC module configuration in your Flow or Workflow in Dashboard.

## Configuration Options

`ExternalVerificationConfiguration` exposes the following for each field:

- A `check<Field>: Bool?` toggle: Whether to collect and verify the field. Left `nil`, it behaves as `false`.
- A `<field>Source: DataInputSource?`: Where the field's value is populated from. Optional and defaults to `nil`; when left unset, the user enters the value manually.

Every parameter is optional.

| Field         | Check toggle              | Source                                |
| ------------- | ------------------------- | ------------------------------------- |
| Name          | `checkName: Bool?`        | `nameSource: DataInputSource?`        |
| Email         | `checkEmail: Bool?`       | `emailSource: DataInputSource?`       |
| Address       | `checkAddress: Bool?`     | `addressSource: DataInputSource?`     |
| Phone         | `checkPhone: Bool?`       | `phoneSource: DataInputSource?`       |
| Tax ID/SSN    | `checkSsn: Bool?`         | `ssnSource: DataInputSource?`         |
| Date of birth | `checkDob: Bool?`         | `dobSource: DataInputSource?`         |
| Nationality   | `checkNationality: Bool?` | `nationalitySource: DataInputSource?` |

`DataInputSource` values include:

- `.userInput`: Allow the user to type the value.
- `.document`: Prefill the value from a scanned identity document.
- `.poa`: Prefill from a proof-of-address document.

For a field to prefill from `.document` or `.poa`, the source data must already be available in the flow: for example, an ID or proof-of-address capture must be added earlier. If that source data isn't available, the field is left blank instead of causing an error. The user can enter it manually; **Continue** remains disabled until they do.

## Result

The module delivers an `EKYCResult` to the delegate:

```swift
func onEKYCCompleted(_ result: EKYCResult)
```

`EKYCResult` fields:

- `success: Bool`: `true` when the eKYC checks completed successfully.
- `error: IncdError?`: Set when the operation did not complete successfully; `nil` otherwise.

eKYC does not define a module-specific error type; failures surface through `EKYCResult.error` as an `IncdError`, not through a separate error callback.

<br />