# Enrolment Flow

In order to use our SDK you need an authorization token. Please check our API "[Authorisation](/docs/kyc/uqudo-api/authorisation.md)" in this regard.

The following method should be called when the application is initiated:

```kotlin
UqudoSDK.init(applicationContext)
```

The Uqudo SDK provides a builder class to initiate the "Enrollment Flow". See the example below:

```kotlin
try {
   val authorizationToken = ... // access_token from the API response
   val uqudoIntent = UqudoBuilder.Enrollment()
            .setToken(authorizationToken)
            .add(
                DocumentBuilder(applicationContext)
                    .setDocumentType(DocumentType.PASSPORT)
                    .enableReading(ReadingConfigurationBuilder()
                        .forceReadingIfSupported(true)
                        .build()
                    )
                    .build()
            )
            .enableFacialRecognition()
            .build(this)
        startActivityForResult(uqudoIntent, 101)
} catch( e: Exception ){
    ...
}
```

## **Uqudo Enrollment Builder Configuration**

In order to check if the document type supports the "Enrollment Flow" you can use the following method:

```kotlin
DocumentType.NGA_DL.enrollmentSupported
```

Configuration options provided in the Uqudo Enrolment builder are:

<table><thead><tr><th width="183">Property</th><th width="104">Type</th><th width="102">Optional</th><th width="93">Default</th><th>Description</th></tr></thead><tbody><tr><td>setToken(token)</td><td>String</td><td>No</td><td>null</td><td>See <a href="/pages/M1CogfFsRRAmbNyiAc20">Authorisation</a></td></tr><tr><td>setNonce(nonce)</td><td><p>String</p><p>(max size 64 chars)</p></td><td>Yes</td><td>null</td><td>Nonce provided by the customer mobile application when the SDK is initiated. It is useful to make sure the process has been initiated by the customer mobile application. It should be generated server side.</td></tr><tr><td>setSessionId(sessionId)</td><td><p>String</p><p>(UUID v4)</p></td><td>Yes</td><td>Auto generated</td><td><p>Required during the enrolment process using a QR code, see <a href="/pages/BvyOp3PjkArX13HMjtSz">QR code App</a>.</p><p><strong>Note</strong>: make sure to create always a new session id when you trigger the SDK flow</p></td></tr><tr><td>disableSecureWindow()</td><td>None</td><td>Yes</td><td>false</td><td>Whether to allow users to take screenshots and capture screen recording or not.</td></tr><tr><td>enableFacialRecognition()</td><td>None</td><td>Yes</td><td>none</td><td>Enable facial recognition with the default configuration, see <a href="#facial-recognition-configuration">Facial Recognition Configuration</a><strong>.</strong></td></tr><tr><td>enableFacialRecognition(configuration)</td><td>FacialRecognitionSpecification</td><td>Yes</td><td>none</td><td>Enable facial recognition with a custom configuration, see <a href="#facial-recognition-configuration">Facial Recognition Configuration</a>.</td></tr><tr><td>enableBackgroundCheck(configuration)</td><td>BackgroundCheckSpecification</td><td>Yes</td><td>none</td><td>Enable background check with a custom configuration, see <a href="#background-check-configuration">Background Check Configuration</a>.</td></tr><tr><td>add(document)</td><td>Document</td><td>No</td><td>none</td><td>Add a document to the enrolment process, see <a href="#scan-configuration">Scan Configuration</a>.</td></tr><tr><td>returnDataForIncompleteSession()</td><td>None</td><td>Yes</td><td>false</td><td>When enabled, if the user or the SDK drops the session before completion, the SDK will return the partial data together with the SessionStatus object (see <a href="#handling-the-result">Handling the Result</a>). Please note that you can expect some data only if the user passes at least the scanning step</td></tr><tr><td>enableLookup()</td><td>None</td><td>Yes</td><td>None</td><td><p>Enable third party lookup (Government database). See the supported documents and the data returned here <a href="/pages/64uc90stn9uLQAZ6Jhxr">Lookup object</a></p><p><strong>Note</strong>: this feature requires an additional permission and must be explicitly requested</p></td></tr><tr><td>enableLookup(documentTypes)</td><td>Variable length argument or Array</td><td>Yes</td><td>None</td><td><p>Enable third party lookup (Government database) filtered by document type. For instance, if your KYC process includes more than one document, you can decide to perform the lookup only for one single document. See the supported documents and the data returned here <a href="/pages/64uc90stn9uLQAZ6Jhxr">Lookup object</a></p><p><strong>Note</strong>: this feature requires an additional permission and must be explicitly requested</p></td></tr><tr><td>allowNonPhysicalDocuments()</td><td>None</td><td>Yes</td><td>false</td><td>If enabled allows scanning of non-physical documents (where the SDK doesn't reject scans upon detecting a screen)<br><strong>Note</strong>: Available only on SDK version 3.x and above</td></tr><tr><td>disableTamperingRejection()</td><td>None</td><td>Yes</td><td>false</td><td>If enabled directs the SDK not to dismiss the scan upon detecting tampering, specifically for ID photo tampering detection.<br><strong>Note</strong>: Available only on SDK version 3.x and above</td></tr></tbody></table>

## Scan Configuration

The scanning has some customisation options which can be set using the DocumentBuilder object like below:

```kotlin
DocumentBuilder(applicationContext)
                    .setDocumentType(documentType)
                    .disableHelpPage()
                    .enableReading()
                    .build()
```

Below you can find the configuration options available:

<table><thead><tr><th width="189">Property</th><th width="114">Type</th><th width="106">Optional</th><th width="90">Default</th><th>Description</th></tr></thead><tbody><tr><td>setDocumentType(documentType)</td><td>DocumentType</td><td>No</td><td>None</td><td>Document type to scan. Please refer to the Scan API for <a href="/pages/orr2KPMMK0ld84EOloiL">supported Document Types</a>.</td></tr><tr><td>disableHelpPage()</td><td>None</td><td>Yes</td><td>false</td><td>Disable scanning help page</td></tr><tr><td>enableReading()</td><td>None</td><td>Yes</td><td>None</td><td>Enable reading for the document, e.g. NFC reading of the chip with default configuration, see <a href="#read-configuration">Read Configuration</a>.</td></tr><tr><td>enableReading(configuration)</td><td>ReadingSpecification</td><td>Yes</td><td>None</td><td>Enable reading for the document, e.g. NFC reading of the chip, passing a reading specification object (see below), see <a href="#read-configuration">Read Configuration</a>.</td></tr><tr><td>setFaceScanMinimumMatchLevel(matchLevel)</td><td>Int</td><td>Yes</td><td>None</td><td>Defines the minimum match level that the facial recognition has to meet for scanned pictures related to this document. This configuration takes precedence from the global setting in the facial recognition configuration</td></tr><tr><td>setFaceReadMinimumMatchLevel(matchLevel)</td><td>Int</td><td>Yes</td><td>None</td><td>Defines the minimum match level that the facial recognition has to meet for pictures from the chip (e.g. NFC) related to this document. This configuration takes precedence from the global setting in the facial recognition configuration</td></tr><tr><td>disableExpiryValidation()</td><td>None</td><td>Yes</td><td>false</td><td>Allows to scan expired documents</td></tr><tr><td>enableScanReview(frontSide, backSide)</td><td>Boolean, Boolean</td><td>Yes</td><td>Not enabled</td><td>Enable scan review of the document for the front side, back side or both. After scanning the detected document side is presented to the user for review and confirmation</td></tr><tr><td>enableUpload()</td><td>None</td><td>Yes</td><td>false</td><td><p>Enable manual upload of the document instead of automatic scanning. The user can choose a single PDF that contains the image of the document. For a two-side document the first picture must be the front side and the second picture the back side.</p><p>If enabled, the reading step is automatically disabled<br><br><strong>Note</strong>: This feature has been deprecated since version 3.0.0 and will be removed in a future release of the SDK</p></td></tr><tr><td>enableAgeVerification(minAge)</td><td>Int</td><td>Yes</td><td>-1 (disabled)</td><td>Enable age verification. If the age calculated from the document is not above or equals minAge, the scan fails showing a message to the user accordingly. Min age must be above 0 otherwise is not taken into consideration</td></tr></tbody></table>

## **Read Configuration**

In order to check if the document type supports the reading step (NFC) you can use the following method:

```kotlin
DocumentType.NGA_DL.readingSupported
```

In order to configure specific options for the reading part, see the example below:

```kotlin
....
                DocumentBuilder(applicationContext)
                    .setDocumentType(documentType)
                    .enableReading(
                       ReadingConfigurationBuilder()
                           .forceReading(false)
                           .build()
                 )
                .build()
```

Reading configuration options available:

<table><thead><tr><th width="202">Property</th><th width="97">Type</th><th width="103">Optional</th><th width="82">Default</th><th>Description</th></tr></thead><tbody><tr><td>forceReading(value)</td><td>Boolean</td><td>Yes</td><td>false</td><td>Force the reading part. Users will not be able to skip the reading part. If the device does not support NFC and forceReading is set to true, the uqudo builder will throw and exception that needs to managed by the application</td></tr><tr><td>forceReadingIfSupported(value)</td><td>Boolean</td><td>Yes</td><td>false</td><td>Force the reading part only if NFC is supported. Users will not be able to skip the reading part if NFC is supported. Otherwise, the reading part is skipped and the user taken to the next step.<br><br><strong>Note</strong>: This option has been deprecated in version 3.0.0 and is the default behaviour now</td></tr><tr><td>forceReadingTimeout(timeout)</td><td>Integer</td><td>Yes</td><td>-1 (disabled)</td><td>Defines the timeout in seconds. If the user isn't able to perform the NFC scanning of the document before the timeout expires, a message is shown accordingly and the user is allowed to skip the NFC step.</td></tr></tbody></table>

You can also control the app for devices with NFC or not by turning the feature required as true or false in AndroidManifest.xml. By doing so, the app will only be available to devices with NFC if set true

```xml
<uses-feature
   android:name="android.hardware.nfc"
   android:required="true"
   tools:node="replace" />
```

## **Facial Recognition Configuration**

In order to check if the document type supports facial recognition you can use the following method:

```kotlin
DocumentType.NGA_DL.facialRecognitionSupported
```

**Note**: By default the facial recognition is disabled. You need to enable Facial Recognition explicitly. See the example below:

```kotlin
...
        .enableFacialRecognition(
           FacialRecognitionConfigurationBuilder()
              .setFaceReadMinimumMatchLevel(3)
              .setFaceScanMinimumMatchLevel(2)
              .build()
        )
```

The above example shows how you can disable the help page on the facial recognition part.

Facial Recognition configuration options available:

<table><thead><tr><th width="179">Property</th><th width="76">Type</th><th width="100">Optional</th><th width="89">Default</th><th>Description</th></tr></thead><tbody><tr><td>setScanMinimumMatchLevel(matchLevel)</td><td>Int</td><td>Yes</td><td>None</td><td>Defines the minimum match level that the facial recognition has to meet for scanned pictures</td></tr><tr><td>setReadMinimumMatchLevel(matchLevel)</td><td>Int</td><td>Yes</td><td>None</td><td>Defines the minimum match level that the facial recognition has to meet for pictures from the chip (e.g. NFC)</td></tr><tr><td>enableAuditTrailImageObfuscation(obfuscationType)</td><td>ObfuscationType</td><td>Yes</td><td>None</td><td><p>Enables audit trail image background obfuscation leaving only the face visible. It can be used when there are privacy concerns related to the background of the selfie taken by the user and shared in the SDK result. There are two types of obfuscations:</p><ul><li><strong>FILLED</strong>: the background is entirely replaced</li><li><strong>FILLED_WHITE:</strong> the background is entirely replaced with a wihte background</li><li><strong>BLURRED</strong>: the background is heavily blurred, making sure the objects in the background are not clearly recognizable, but still giving a perception of the environment surrounding the user and therefore still being able to validate the reality of the image. If privacy is a concern, we recommend using this option</li></ul></td></tr><tr><td>setMaxAttempts(maxAttempts)</td><td>Int</td><td>Yes</td><td>3</td><td>Set the max failed facial recognition attempts before dropping the session.<br><strong>Note</strong>: only values between 1 and 3 are taken into consideration.</td></tr><tr><td>allowClosedEyes()</td><td>None</td><td>Yes</td><td>False</td><td>Allows to have closed eyes during facial recognition.</td></tr><tr><td>enableOneToNVerification()</td><td>None</td><td>Yes</td><td>False</td><td>Once activated, following a successful facial recognition (confirming liveness and matching the face), the system initiates a search for the user's selfie within your tenant. If the selfie is not found, it is added, and the indexed facial features are stored in the database. The SDK result includes a unique ID in the face object, along with an indication of whether there was a match with a previously onboarded selfie. It's essential to store this unique ID in your system alongside the user's record, facilitating future searches for users with the same ID. Please be aware that this option requires a specific permission, otherwise, it will be disregarded</td></tr><tr><td>enableActiveLiveness(disableLivenessGesture)</td><td>LivenessGesture</td><td>Yes</td><td>Not enabled</td><td><p>Enable active liveness when performing facial recognition. There are three gestures:</p><ul><li>LivenessGesture.FACE_MOVE</li><li>LivenessGesture.FACE_TILT</li><li>LivenessGesture.FACE_TURN</li></ul><p>Every gesture has two actions associated resulting in a total of six possible actions (move closer, move further, tilt right, tilt left, turn right, turn left). During verification, the SDK will randomly prompt the user to perform one of these actions to continue.<br>The configuration allows you to disable one gesture type, reducing the pool to four actions.<br><strong>Warning</strong>: We recommend enabling this feature only if required for regulatory or compliance purposes, as it may significantly impact user conversion rates.</p></td></tr></tbody></table>

## **Background Check Configuration**

**Note:** This feature requires an additional permission and must be explicitly requested

**Note**: By default the Background Check is disabled. You need to enable Background Check explicitly. See the example below:

```kotlin
...
        .enableBackgroundCheck(
             BackgroundCheckConfigurationBuilder()
               .skipView()
               .build()
         )
```

Background Check configuration options available:

<table><thead><tr><th width="180">Property</th><th width="113">Type</th><th width="99">Optional</th><th width="95">Default</th><th>Description</th></tr></thead><tbody><tr><td>disableConsent()</td><td>None</td><td>Yes</td><td>false</td><td>Disable consent option for the user</td></tr><tr><td>setBackgroundCheckType(type)</td><td>BackgroundCheckType</td><td>Yes</td><td>RDC</td><td><p>Sets the background check type</p><p>RDC</p></td></tr><tr><td>enableMonitoring()</td><td>None</td><td>Yes</td><td>false</td><td>Enable continuous monitoring. See API documentation for details.</td></tr><tr><td>skipView()</td><td>None</td><td>Yes</td><td>false</td><td>If enabled, the step will be skipped, and the SDK will trigger the background check without any user interaction.</td></tr></tbody></table>

## **Handling Exceptions**

The Uqudo SDK will throw certain exceptions which need to be handled by the application. The Exceptions are:

1. IllegalStateException - e.g. enabling reading for a document that doesn’t support reading or required configuration missing
2. UnsupportedDeviceException - e.g. on DocumentBuilder().build() if force reading is enabled and the device doesn’t support NFC
3. InitializationException - thrown when the SDK fails to load native libraries due to a bug on certain Android devices. This exception enables your application to handle the issue gracefully instead of crashing.

## **Handling the Result**

The enrollment result will be available to the application in the calling Activity’s onActivityResult method:

```kotlin
...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data)
   if (resultCode == Activity.RESULT_OK) {
       val result = data?.getStringExtra("data")
   } else if (resultCode == Activity.RESULT_CANCELED) {
       if (data != null) {
         val sessionStatus = data.getParcelableExtra("key_session_status") as SessionStatus
         println("Enrollment failed due to ${sessionStatus.sessionStatusCode.message} at ${sessionStatus.sessionTask.name()}")
       }
   }
}
```

If the resultCode is equals to Activity.RESULT\_OK you can find the SDK result in the data attribute. The string is the JWS, see "[SDK result](/docs/kyc/uqudo-sdk/sdk-result.md)" for details.

If the resultCode is equals to Activity.RESULT\_CANCELED you can find the **SessionStatus** object result in the data attribute under the key “**key\_session\_status**”. The **SessionStatus** contains the following properties:

**sessionStatusCode** as SessionStatusCode enum that contains the following error codes:

1. **USER\_CANCEL** = User canceled the enrollment process
2. **SESSION\_EXPIRED** = Session expired or not found
3. **UNEXPECTED\_ERROR** = Something went wrong. In the message the details of the error
4. **SESSION\_INVALIDATED\_READING\_INVALID\_DOCUMENT** = Session gets invalidated because the digital signature validation fails after reading the data in the chip
5. **SESSION\_INVALIDATED\_CHIP\_VALIDATION\_FAILED** = Session gets invalidated because chip authentication fails (e.g. chip authentication for passports)
6. **SESSION\_INVALIDATED\_READING\_NOT\_SUPPORTED** = Session gets invalidated because the document doesn’t support reading (e.g. no chip available) and the reading step is forced by configuration
7. **SESSION\_INVALIDATED\_FACE\_RECOGNITION\_TOO\_MANY\_ATTEMPTS** = Session gets invalidated because of too many failed facial recognition attempts
8. **SESSION\_INVALIDATED\_CAMERA\_NOT\_AVAILABLE** = Session gets invalidated because the camera is not available
9. **SESSION\_INVALIDATED\_CAMERA\_PERMISSION\_NOT\_GRANTED** = Session gets invalidated because the end user denied camera permission

sessionTask as SessionTask enum that contains the following codes:

1. **SCAN** = The scanning task
2. **READING** = The NFC reading task
3. **FACE** = The facial recognition task
4. **BACKGROUND\_CHECK** = The background check task (only if skipView() is not enabled)

**data** as String that contains the JWS object with the partial data of an incomplete KYC session. Returning the partial data for an incomplete KYC session is disabled by default, please see [Enrollment Builder Configuration](#uqudo-enrollment-builder-configuration) for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uqudo.com/docs/kyc/uqudo-sdk/integration/android/enrolment-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.