# 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. This data can include the user's name, email, address, phone, tax ID, date of birth, and nationality. This module can prefill fields from data captured earlier in the flow, such as a scanned 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](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). In Patterns 1 and 2, you add the module to a `FlowConfig` in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with `startFlow()` or `startWorkflow()` as shown on [Run Flows Configured in Dashboard](https://developer.incode.com/docs/android-run-flows-configured-online).

## Add eKYC

Add the module with `addEKYC(ekycModule)`. The fields shown and the verification behavior depend on the eKYC module configuration in your Flow or Workflow in Dashboard.

{/* PM: They can specify the fields shown through the below Configuration Options, in code. But verification behavior must depend on Flow or Workflow? Is there a Process module they can configure in code to do this? */}

```kotlin
flowConfigBuilder.addEKYC(ekycModule)
```
```java
flowConfigBuilder.addEKYC(ekycModule);
```

### Example

The example below builds an `EKYC` module that verifies the name and address fields, sourcing the name from a scanned document, adds it to a `FlowConfig` with a flow tag, and starts an onboarding section.

```kotlin
val ekyc = EKYC.Builder()
    .setVerifyName(true)
    .setVerifyAddress(true)
    .setNameSource(EKYC.DataInputSource.DOCUMENT)
    .build()

val flowConfig = FlowConfig.Builder()
    .setFlowTag("eKYC section")
    .addEKYC(ekyc)
    .build()

IncodeWelcome.getInstance()
    .startOnboardingSection(activityContext, flowConfig, object : OnboardingListener() {
        override fun onEKYCChecksCompleted(ekycResult: EKYCResult) {
            // eKYC checks complete
        }

        override fun onError(error: Throwable) {}

        override fun onUserCancelled() {}

        override fun onOnboardingSectionCompleted(flowTag: String) {}
    })
```
```java
EKYC ekyc = new EKYC.Builder()
    .setVerifyName(true)
    .setVerifyAddress(true)
    .setNameSource(EKYC.DataInputSource.DOCUMENT)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .setFlowTag("eKYC section")
    .addEKYC(ekyc)
    .build();

IncodeWelcome.getInstance()
    .startOnboardingSection(activityContext, flowConfig, new IncodeWelcome.OnboardingListener() {
        @Override
        public void onEKYCChecksCompleted(@NonNull EKYCResult ekycResult) {
            // eKYC checks complete
        }

        @Override
        public void onError(@NonNull Throwable error) {}

        @Override
        public void onUserCancelled() {}

        @Override
        public void onOnboardingSectionCompleted(@NonNull String flowTag) {}
    });
```

## Configuration Options

Configure the module with `EKYC.Builder`. Every field is visible by default. The most common options control which fields appear and where their data comes from.

| Setting                                  | Description                                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `setVerifyName(Boolean)`                 | Shows or hides the name field.                                                                   |
| `setVerifyAddress(Boolean)`              | Shows or hides the address fields.                                                               |
| `setVerifyDateOfBirth(Boolean)`          | Shows or hides the date of birth field.                                                          |
| `setVerifyTaxId(Boolean)`                | Shows or hides the tax ID field.                                                                 |
| `setNameSource(EKYC.DataInputSource)`    | Sets where the name field is populated from: `USER_INPUT`, `DOCUMENT`, or `PROOF_OF_ADDRESS`.    |
| `setAddressSource(EKYC.DataInputSource)` | Sets where the address field is populated from: `USER_INPUT`, `DOCUMENT`, or `PROOF_OF_ADDRESS`. |

`EKYC.createDefault()` returns an instance with all fields visible.

The `DataInputSource` options let you prefill a field from a scanned `DOCUMENT` or a `PROOF_OF_ADDRESS` document instead of `USER_INPUT`. For a field to prefill, the source data must already be available in the flow.

For the complete option set, see `EKYC.Builder` in [API Reference](https://developer.incode.com/docs/android-api-reference).

## Result

eKYC delivers an `EKYCResult` to the `onEKYCChecksCompleted(ekycResult)` callback on the `OnboardingListener`. Key fields include:

- Fields inherited from `BaseResult`:
  - `resultCode`: The `ResultCode` for this result.
  - `error`: When `resultCode` is `ERROR`, the `Throwable` that caused it; otherwise, `null`.
  - `deviceStats`: The `DeviceStats` snapshot of the device state when the result was produced.
  - `motionStatus`: Device motion assessment during capture. One of the following:
    - `UNCLEAR`: Motion could not be determined; the default.
    - `PASS`: Device motion was within acceptable limits.
    - `FAIL`: Excessive device motion was detected.

Errors surface through `OnboardingListener.onError(Throwable)`. eKYC does not define a module-specific exception subtype.

For all fields, see `EKYCResult` in [API Reference](https://developer.incode.com/docs/android-api-reference).