# Jumio Documentation

> Jumio Documentation — REST APIs, SDKs, and integration guides for identity verification, credentials, and risk signals.

---

# QuickStart

https://documentation.jumio.ai/docs/quickStart/

# Welcome to Jumio: Quickstart Guide

This introductory guide provides a high-level overview of **Jumio’s end-to-end identity verification platform**, designed to help you quickly and securely onboard users while meeting compliance requirements.

Whether you're integrating identity verification, liveness detection, or document authentication, this guide will walk you through Jumio’s key products and features to help you build your verification flows with confidence and speed.

Our goal is to get you up and running as quickly as possible—so you can start verifying identities and delivering trusted user experiences right away.

---

# ID + Selfie Verification

https://documentation.jumio.ai/docs/quickStart/ID_SelfieVerification

# Quickstart Guide: ID + Selfie Verification

Follow these steps to authenticate, create or update account, launch identity verification workflows, and handle the response.

## Prerequisites

To retrieve your Credentials, log in to the portal and obtain your **client ID** and **client secret**. These are required to authenticate the /token endpoint.

## Step-by-Step Process

### Step 1: Obtain an OAuth2 Bearer Token

- Generate an OAuth2 Bearer token by calling the `/token` endpoint with the POST HTTP method.
- Use **Basic Authentication** with the **client ID** and **client secret** found in the settings section of your Jumio Portal.
- Once obtained, include the token in the `Authorization` header for all subsequent API requests.

:::tip
Refer to the [Authentication documentation](../developer-resources/API/authorization) for the specific endpoint to obtain this token.
:::

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

:::note

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests and reduce integration costs, **do not call the `/auth` endpoint before every transaction**. Instead, **reuse the same access token until it expires**, and request a new one only when needed.
- For testing purposes, you can use Postman's built-in **OAuth 2.0 authorization type** (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
- For a step-by-step walkthrough, check out this [short video guide](https://share.vidyard.com/watch/HZqWPsZAAHaPVRYktaDudf).
  :::

### Step 2: Create or Update an Account

Use the `/accounts` endpoint to initiate a new workflow for either a [new](../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) or an [existing](../developer-resources/API/account#tag/Account/paths/~1api~1v1~1accounts~1%7BaccountId%7D/put) user.

:::info
A workflow defines which Jumio services will process your user's credentials.

:::

#### New User

- US: POST https://account.amer-1.jumio.ai/api/v1/accounts
- EU: POST https://account.emea-1.jumio.ai/api/v1/accounts
- SG: POST https://account.apac-1.jumio.ai/api/v1/accounts

#### Existing User

- US: PUT https://account.amer-1.jumio.ai/api/v1/accounts/{{accountId}}
- EU: PUT https://account.emea-1.jumio.ai/api/v1/accounts/{{accountId}}
- SG: PUT https://account.apac-1.jumio.ai/api/v1/accounts/{{accountId}}

#### Header

```
Accept: application/json
```

#### Example Request

```
{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    key": "10549" //ID + Selfie + Supporting Data
  }
}

```

#### Example Response

```
{
  "timestamp": "ISO-8601 timestamp",
  "account": {
    "id": "string"
  },
  "web": {
    "href": "https://hosted.jumio.com/...",
    "successUrl": "https://yourapp.com/success",
    "errorUrl": "https://yourapp.com/error"
  },
  "sdk": {
    "token": "JWT token"
  },
  "workflowExecution": {
    "id": "string",
    "credentials": [
      {
        "id": "string",
        "category": "ID | DATA | SELFIE | FACEMAP",
        "label": "string",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "JWT token",
          "workflowExecution": "https://api.jumio.ai/.../workflow-executions/{id}",
          "parts": {
            "front": "https://.../parts/FRONT",
            "back": "https://.../parts/BACK",
            "prepared_data": "https://.../parts/PREPARED_DATA",
            "face": "https://.../parts/FACE"
          }
        }
      }
    ]
  }
}
```

### Step 3: Launch the Workflow

The account creation response provides three integration options:

#### Option 1: Use Jumio's Hosted Interface

Use workflowExecution.web.href in one of these ways:

- Redirect: Send users to the URL in a new browser tab
- iFrame: Embed the experience in your webpage
- WebView: Load the URL in a mobile app WebView component

`<iframe src="https://hosted.jumio.com/workflow/abc123" width="100%" height="700"></iframe>`

#### Option 2: Integrate Jumio SDKs

Initialize the SDK using workflowExecution.sdk.token. Refer to the [Jumio SDK documentation](../developer-resources/SDKs/introduction) for implementation details.

#### Option 3: Build Custom Interface with API

Use the workflowExecution.api.workflowExecution endpoint to upload images directly. You'll need to:

- Upload **front, back,** and **selfie** images.
- Finalize the workflow using the **finalization endpoint**.

**_For guidance on using this approach, contact [Jumio support](https://www.jumio.com/contact/support/)._**

### Step 4: Wait for the Callback

Jumio will send a callback when the workflow is complete. This only includes No PII data/non-sensitive data status info, so proceed to retrieve full details. You can check the callback here.

:::note
Callback time varies by workflow—wait accordingly.
:::

### Step 5: Retrieve the Workflow Results

Upon receiving the callback, consume the retrieval API with the GET HTTP method:

- US: `https://retrieval.amer-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}`
- EU: `https://retrieval.emea-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}`
- SG: `https://retrieval.apac-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}`

Once you receive the response from the Retrieval API, parse it to:

- Determine the final status (e.g., passed, rejected, etc.). Learn more about risk scores here.
- Review the extracted document data.
- Take the appropriate next steps based on the results.

#### Example Response

<details>
```
{
    "workflow": {
        "id": "UUID",
        "status": "PROCESSED",
        "definitionKey": "10011",
        "userReference": "MyUser",
        "customerInternalReference": "transaction_1234"
    },
    "account": {
        "id": "UUID"
    },
    "createdAt": "2022-11-28T23:45:02.528Z",
    "startedAt": "2022-11-28T23:50:37.221Z",
    "completedAt": "2022-11-28T23:50:55.232Z",
    "credentials": [
        {
            "id": "UUID",
            "category": "SELFIE",
            "parts": [
                {
                    "classifier": "FACE",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/FACE"
                }
            ],
            "consent": {
                "decisionAccepted": true,
                "collectedBy": "CUSTOMER"
            }
        },
        {
            "id": "UUID",
            "category": "FACEMAP",
            "parts": [
                {
                    "classifier": "FACEMAP"
                },
                {
                    "classifier": "LIVENESS_1",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_1"
                },
                {
                    "classifier": "LIVENESS_3",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_3"
                },
                {
                    "classifier": "LIVENESS_2",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_2"
                },
                {
                    "classifier": "LIVENESS_5",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_5"
                },
                {
                    "classifier": "LIVENESS_4",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_4"
                },
                {
                    "classifier": "LIVENESS_6",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/LIVENESS_6"
                }
            ],
            "consent": {
                "decisionAccepted": true,
                "collectedBy": "CUSTOMER"
            }
        },
        {
            "id": "UUID",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/FRONT"
                },
                {
                    "classifier": "BACK",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/BACK"
                }
            ],
            "consent": {
                "decisionAccepted": true,
                "collectedBy": "CUSTOMER"
            }
        }
    ],
    "decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    },
    "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-11-28T23:50:40.136Z"
    },
    "steps": {
        "href": "https://retrieval.amer-1.jumio.ai/.../steps"
    },
    "capabilities": {
        "extraction": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "DRIVING_LICENSE",
                    "subType": "REGULAR_DRIVING_LICENSE",
                    "issuingCountry": "USA",
                    "firstName": "JOHN JACOB",
                    "lastName": "SMITH",
                    "dateOfBirth": "1969-01-18",
                    "expiryDate": "2025-01-18",
                    "issuingDate": "2019-12-26",
                    "documentNumber": "N1234567",
                    "state": "CA",
                    "gender": "M",
                    "currentAge": "54"
                }
            }
        ],
        "similarity": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    },
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "MATCH"
                    }
                },
                "data": {
                    "similarity": "MATCH"
                }
            }
        ],
        "liveness": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    },
                    {
                        "id": "UUID",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "JUMIO_STANDARD",
                    "predictedAge": 44,
                    "ageConfidenceRange": "14-67"
                }
            }
        ],
        "dataChecks": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ],
        "imageChecks": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    },
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "REPEATED_FACE"
                    }
                },
                "data": {
                    "faceSearchFindings": {
                        "status": "DONE",
                        "findings": [
                            "22771260-8cb0-42a2-a38a-d8f853063cc2",
                            "27232651-4b18-4cf1-8d4a-df0451abc717",
                            "9541ae91-834e-4914-a30d-6534fed4eb6d",
                            "9414413d-2c76-44d2-9052-8876fa327a02"
                        ]
                    }
                }
            }
        ],
        "usability": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
    }
}
```

</details>

For further details, advanced use cases, or support with customization, please refer to the complete [API documentation](../developer-resources/API/) or contact [Jumio support](https://www.jumio.com/contact/support/).

---

# selfie.DONE

https://documentation.jumio.ai/docs/quickStart/selfieDone

# selfie.DONE

selfie.DONE is an innovative and user-friendly verification method that significantly reduces friction in the ID verification process for trusted users. Instead of scanning an ID every time, Jumio can reuse a previously verified ID when no risk is detected.

The user experience flow starts with a **Liveness check**. Based on the result, Jumio either:

- **Reuses a reusable ID** (if the user has already been verified successfully before and is trusted), or
- **Continues with the standard ID verification flow** (if no reusable qualified ID is found or risk is detected).

This provides a faster and smoother user experience while maintaining strong fraud protection.

:::important

- **selfie.DONE requires Jumio Premium Liveness to reuse a previously verified ID.** Premium Liveness ensures strong liveness verification before ID reuse. If it is not enabled, the verification flow automatically continues with the standard ID verification after Liveness.
- **selfie.DONE supports Central and South American countries.** For users located outside these regions, reusable ID searches are not available, and the user must complete a standard ID scan. If you are looking **selfie.DONE support for other regions where you operate please contact [Jumio Support or Jumio Sales](https://support.jumio.com/s/)**.
  :::

## Key Benefits

**1. Faster verification**
For trusted users who have previously completed ID verification, there is no need to scan the same ID again. selfie.DONE reuses a trusted ID, so verification takes less time and feels smoother.

**2. More completed sign-ups**
With fewer steps, more people finish the process. This results in higher conversion rates and lower drop-off rates.

**3. Keep and win more customers**
A simple journey helps you keep existing customers and attract new ones who value speed and ease.

**4. Strong security**
Even when using a stored ID, every check runs against Jumio’s latest fraud models and identity network. You get less friction without compromising on fraud risk protection.

## Supported Channel and Market

- **Channel**: Web SDK and Mobile SDK (API channel not currently supported).

## Prerequisites

selfie.DONE supports past ID reuse based on the data provided for each transaction. To use the latest release of selfie.DONE, customers must meet the following requirements:

- Be natively integrated on the Jumio platform.
- Use the **Web or Mobile SDK channels** for verification.
- Have **Liveness Premium** and **ID Verification** enabled as part of the verification journey.
- Allow **Biometrics (Face) Lookup** and **ID Data Lookup** on the tenant account.

:::important
Reusable ID usage is allowed only for customers utilizing the **Direct Consent model**, where Jumio operates as the Independent Controller.
:::

### Supported Search Criteria

The ability to trigger a reusable ID search depends on different combinations of **user data supplied within [Prepared Data](https://documentation.jumio.ai/docs/references/credentials/#data).** If the required data is not provided or Jumio does not find a matching user, the transaction automatically proceeds with a **new ID scan**. Currently, there are two supported user data options available for selfie.DONE:

1. Name and Date of Birth (Recommended – Global)
2. Country-Specific Identification Number

#### 1. Name and Date of Birth (Recommended – Global)

Use the individual’s full name along with their date of birth. This search criterion is supported globally and is the **recommended default** for searches across all countries within your tenant account’s Accepted IDs configuration.

| **Search Criteria**  | **Applicable Countries**         | **Required Fields in Prepared Data**                                         |
| -------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| Name + Date of Birth | IDs from all supported countries | firstName, middleName (if present on Govtg-issued ID), lastName, dateOfBirth |

:::important

Provide **First Name, Middle Name (if present in Govt. issued ID), Last Name, and Date of Birth** to enable reusable ID search across all supported countries. This is the recommended user data to be supplied for a selfie.DONE.

Unless explicitly required by a country:

- Provide only First Name, Middle Name (if present in Govt. issued ID), Last Name, and Date of Birth.
- Do not include Middle Name, unless it appears explicitly on the official document (e.g., Philippines)
  :::

#### 2. Country-specific Identification Number

selfie.DONE supports **identifier-based reusable ID search** for specific countries using country-specific unique identifiers.

Identifier searches always use an **exact match** strategy.

| **Search Criteria**      | **Applicable Countries** | **Required Prepared Data Fields**      |
| ------------------------ | ------------------------ | -------------------------------------- |
| CPF + Document Country   | Brazil                   | personalNumber (CPF), addressCountry   |
| CURP + Document Country  | Mexico                   | personalNumber (CURP), addressCountry  |
| DNI + Document Country   | Peru, Spain              | personalNumber (DNI), addressCountry   |
| PESEL + Document Country | Poland                   | personalNumber (PESEL), addressCountry |

:::important

- **Country-specific identification numbers** (such as CPF or CURP, etc.) approach should be used when the collection and use of such identifiers is prevalent as part of the onboarding process in a country, and users are okay to provide them. Examples: CPF number in Brazil or CURP in Mexico, etc.
- Identifier-based searches are performed **only if** the Identification Number country is **provided as part of the address country field within** the Prepared data.
- If the country is not provided as part of the addressCountry, the identifier search will not return a match, and the transaction will proceed with a standard ID verification flow.
- Except for Brazil, identifier-based searches (personalNumber + addressCountry) generally have a **lower likelihood of returning a reusable ID** compared to First Name + Middle Name (if present in Govt. issued ID) + Last Name + Date of Birth–based searches.
- In the current version, reusable ID search is limited to transactions originating in Central and South America. Users located in other regions must scan a new ID. If you are looking selfie.DONE support for other regions where you operate please contact [Jumio Support or Jumio Sales](https://support.jumio.com/s/).
  :::

#### 3. Limiting the ID returned by selfie.DONE

**Default limitation on reusable IDs returned**

To maintain consistency with normal ID Verification and customers’ compliance requirements, Jumio always limits the search to the “Accepted IDs” configuration of the tenant account where the transaction is processed.

You can find them listed for your tenant account on Jumio Portal → Settings → Identity Verification → Accepted IDs.

![](./images/defaultLimitation.png)

##### Limiting reusable IDs returned per transaction

Further, to limit the number of returned reusable IDs per transaction, you can use Country and/or Document Type in the ID Credential section of the [Account API](https://documentation.jumio.ai/docs/references/credentials/#specifying-the-document-in-the-account-request). This will limit the returned reusable ID to the provided Country and/or Document Type, if found with Jumio.

**Example**
![](./images/credExample.png)

## How Does This Work?

### Step 1: Data Preparation

Before initiating the verification process, the Customer collects the required information from the user and includes it in the initial Account Initiation call as part of the [Prepared Data](https://documentation.jumio.ai/docs/developer-resources/API/uploadingSupportData#example-prepared-data-body).

#### Recommended (Global)

Provide First Name, Middle Name (if present in Govt. issued ID), Last Name, and Date of Birth to enable a global reusable ID search across all supported countries within your tenant account’s Accepted IDs configuration.

**Example**

- First Name: Jane
- Middle Name: Mary
- Last Name: Doe
- Date of Birth: 1992-08-14

#### Country-specific Identification Number (Alternate approach):

For certain countries, a government-issued identification number may be provided along with the address country. For more details, check [this](#2-country-specific-identification-number) section.

**Example: Brazil-issued Documents**

- Address Country: BRA
- CPF field provided in the personalNumber field of prepared data (no special characters)

**Limiting the search per transaction** -
Check [this](#3-limiting-the-id-returned-by-selfiedone) section to limit the reusable ID returned to specific countries and/or ID types.

### Step 2: Liveness Check

The user performs a **liveness check** to confirm physical presence,

- Instructions are provided to guide the user through the proper face capture process.
- Consent is obtained as required for the transaction.
- Liveness checks detect and flag malicious attempts using photos, videos, or deepfakes.

Hence, when the liveness result is Passed, the face is captured successfully, and the system proceeds to search for an ID using the search criteria. When the qualified IDs are found, Jumio confirms by performing biometric matching against past qualified reusable IDs found. This ensures the highest level of security and accurate data sharing on behalf of the ID owner.

If any risk is flagged during the liveness check, or if no eligible reusable ID is found, the workflow bypasses ID reuse and proceeds with a standard ID verification flow.

### Step 3: User Confirmation

If **one or more eligible reusable IDs are found**, Jumio applies additional security and integrity checks and presents single ID for reuse, which has the highest confidence with respect to that transaction.

**A. The system displays the type of ID identified for reuse.**

- ID Image is not shared with the user

**B. The user can choose to:** - Use this ID to complete the transaction, or

- Initiate a new ID scan and upload a new ID if needed.

User confirmation is required to reuse the previously verified ID.
If no eligible reusable ID is found, or if any risk is detected by Jumio, the user is seamlessly routed to a standard ID verification flow for extraction and verification.
Decision making occurs in the background, and the user remains unaware.

### Step 4: Completing Transaction

#### 1. Using Reusable ID

a. The transaction completes faster since ID verification was already performed.
b. All background processing, including **extraction** and **fraud risk checks**, is executed to ensure security.

- This enables the use of the latest fraud detection models and Jumio’s network knowledge about risky connections.
- Your current integration with Jumio doesn’t change, and ID Verification output format and data are received as usual.
  c. Any other **custom risk checks** — such as Brazil CPF check, Cross Transaction Risk, Device Risk Check, etc are executed as usual if configured as part of the workflow and enabled for the Customer account.

### Step 5: Viewing Reusable ID Usage in Transaction Results

When a transaction is processed through selfie.DONE, i.e., uses a Reusable ID for processing; this is reflected in the transaction results.

On the Jumio Portal, the transaction details page displays a **“Reusable Identity”** section indicating:

- PreVerified ID: Whether a reusable ID was used for the transaction.
- User Accepted: Whether the user accepted the reuse of the previously verified ID during the flow.
- ID Source: Source of reusable ID. Default is Jumio, except Brazil where it can also be Local Datasource.

:::note
If no eligible reusable ID is found, this section will not appear, and the transaction will reflect standard ID verification information.
:::

![Viewing Reusable ID](./images/viewingReusableID.png)

#### Tracking Reusable ID Usage

Reusable ID use can be tracked using the Jumio Retrieval API. Refer to the Retrieval API documentation [here](https://documentation.jumio.ai/developer-resources/api/retrieval#tag/Retrieval/operation/getWorkflowExecutionDetails).

Customers can also identify transactions where a reusable ID was used using **Jumio Portal** in the following ways:

- Explorer page - Filter transactions using the _Pre-Verified ID_ = True/False filter.

![Tracking On Explorer](./images/trackingonExplorer.png)

- Reporting - The _Pre-Verified ID_ field is available as an extractable field in reports.

![Reporting](./images/reporting.png)

## Build a Workflow with selfie.DONE

You can configure and manage the selfie.DONE verification flow directly in the **Jumio Workflow Editor**. This self-service setup lets you define when to reuse a previously verified ID or trigger a new ID verification.

### Steps to Configure

#### Step 1: Open the Workflow Editor in the Jumio Portal.

#### Step 2: Create a new workflow or select an existing one to update.

![Workflow_Editor](./images/1_WorkflowEditor.png)

#### Step 3: In the Workflow Builder, add the following components:

#### Step 3.1: Configure Data Acquisition

- Navigate to Credentials Options and add Data Acquisition as the first step in the workflow.
  ![Credential_Acquisition](./images/2_DataAcquisition.png)

#### Step 3.2: Configure Selfie / Facemap Acquisition

#### For **Facemap Acquisition**, follow the steps below,

- From **Credentials** Options, add a **Facemap Acquisition** step.
- Ensure that the **Web and/or Mobile SDK** is selected as a supported channel.
  ![Facemap_Acquisition](./images/3_FaceMap_Acquiistion.png)

- Ensure that **Storage, Usability,** and **Liveness** are selected as Capabilities.
  ![Facemap_Storage](./images/3_1_FaceMap.png)

#### For **Selfie Acquisition**, follow the steps below,

- From **Credentials** Options, add a **Selfie Acquisition** step.
- Select the **Web and/or Mobile SDK** as the supported channel.
  ![Selfie_Acquisition](./images/4_SelfieAcquistion.png)
- Enable the following capabilities: **Storage, Usability, Liveness, Similarity,** and **Image Checks**.
  ![Selfie_Storage](./images/Step3.png)

#### Step 3.3: Add ID Acquisition

- From Credentials Options, add an ID Acquisition step.
- Under **Advanced Configuration**, select the **Web and/or Mobile SDK** as the supported channel.
  ![ID_Acquiistion](./images/5_IDAcquisistion.png)
- Select Reusable ID as the Acquisition Type.
  ![Reusable_ID](./images/5_1_ReusableID.png)
- Under Basic Configuration, enable the following capabilities: Storage, Usability, Extraction, Image Checks, Data Checks, and Similarity.
  ![IDStorage](./images/dataCheck.png)

#### Step 3.4: Add ID / Identity Verification and Risk Evaluation

- From the **Common** section, add an **ID or Identity Verification** step.
  ![Identity_Verification](./images/6_RiskEvaluation.png)
- From the Common section, add a Risk Calculation step and the End of Workflow step.
  ![RiskCalculation](./images/7_RiskCalculation.png)

#### Step 4: Save and Publish your workflow.

- You will notice that the **Custom Workflow Saved Successfully**.
  ![SavePublish](./images/8_SavePublish.png)

:::info
Include additional elements, such as Lookups or other risk signals, as required.
:::

---

# Doc Proof

https://documentation.jumio.ai/docs/quickStart/docProof

# Quickstart Guide: Doc Proof

This guide outlines the essential steps to integrate Jumio's Doc Proof, utilizing OAuth 2.0 authentication and the Jumio-hosted user experience (Web or SDK). It includes the process of setting up prepared data, launching the workflow, and handling the results.

## Prerequisites

To retrieve your Credentials, log in to the portal and obtain your client ID and client secret. These are required to authenticate the /token endpoint.

## Step-by-Step Process

### Step 1: Authenticate and Get OAuth2 Bearer Token

- Generate an OAuth2 Bearer token by calling the /token endpoint with the POST HTTP method.
- Use Basic Authentication with the client ID and client secret found in the settings section of your Jumio Portal.
- Once obtained, include the token in the Authorization header for all subsequent API requests.

:::note
Refer to the [Authentication documentation](../developer-resources/API/authorization) for the specific endpoint to obtain this token.
:::

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

:::note

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests and reduce integration costs, **do not call the `/auth` endpoint before every transaction**. Instead, **reuse the same access token until it expires**, and request a new one only when needed.
- For testing purposes, you can use Postman's built-in **OAuth 2.0 authorization type** (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
- For a step-by-step walkthrough, check out this **[short video guide](https://share.vidyard.com/watch/HZqWPsZAAHaPVRYktaDudf)**.
  :::

### Step 2: Initiate a Doc Proof Workflow

Use the /accounts endpoint to initiate a doc proof workflow for either a [new](../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) or an [existing](../developer-resources/API/account#tag/Account/paths/~1api~1v1~1accounts~1%7BaccountId%7D/put) user.

:::tip
A workflow defines which Jumio services will process your user's credentials.
:::

#### New User

- US: POST https://account.amer-1.jumio.ai/api/v1/accounts
- EU: POST https://account.emea-1.jumio.ai/api/v1/accounts
- SG: POST https://account.apac-1.jumio.ai/api/v1/accounts

#### Existing User

- US: PUT https://account.amer-1.jumio.ai/api/v1/accounts/{accountId}
- EU: PUT https://account.emea-1.jumio.ai/api/v1/accounts/{accountId}
- SG: PUT https://account.apac-1.jumio.ai/api/v1/accounts/{accountId}

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Request

```
{
    "customerInternalReference":"transaction_1234",
    "workflowDefinition":{
        "key": 10170,
        "credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }
            }
        ]
    },
}
```

- workflowDefinition: Specifies the workflow configuration.
- workflowDefinition.key: Set to 10170 to activate the Doc Proof and Multi Doc Upload Image upload (No fraud checks).
- type: Defines the specific document type to be requested from the user. The Document Code may be, (Bank Statement): "BS", Example (Utility Bill): "UB" etc.,

Note: Refer to the [Supported Documents](../references/credentials/#supported-documents) for the complete and up-to-date list of supported document codes.

#### Example Response

The JSON response will contain URLs and tokens for different integration channels:

- web.href: URL for Jumio's hosted web client. Redirect user or embed in an `<iframe>/WebView`.
- SDK.token: Token for initializing Jumio's Web or Native Mobile SDK.
- API.workflowExecution: Base URL for direct API image uploads.

```
{
    "timestamp": "2025-06-17T15:59:29.997Z",
    "account": {
        "id": "790e9aee-99ee-45ae-8ca4-4f82cf862f31"
    },
    "web": {
        "href": "https://jumio-go.web.emea-1.jumio.ai/web/client?baseUrl=https%3A%2F%2Fweb-sdk.emea-1.jumio.ai%2Fwebsdk%2Fv4%2Fapi&authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg&locale=it"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg"
    },
    "workflowExecution": {
        "id": "0a3ccbad-da8a-4048-a589-81281d1f13f6",
        "credentials": [
            {
                "id": "61ec602b-3f68-40a6-b3b9-db2d1b26a2f5",
                "category": "DATA",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg",
                    "parts": {
                        "prepared_data": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6/credentials/61ec602b-3f68-40a6-b3b9-db2d1b26a2f5/parts/PREPARED_DATA"
                    },
                    "workflowExecution": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6"
                }
            },
            {
                "id": "2dc87b73-3eb4-4828-a840-cd0ce7bbf909",
                "category": "DOCUMENT",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLi2IlNR0nLBpDHSSokKPhJiL2TmR3QvOLqvE_o78M97EOqjLVULSrKYRfM_dhmrxq7Wu-gOofYOogbAQ1BH1Jw5LTyDUfL7os1aCYGFEnAWBQkoaSWRsqjTPwa_R_upz6mfvL5cbtcra1p-ytjJl4YpC4IhIpgSAjMyT32zCm38P0BpwF2J-MAAAA.gFW12xFHHNfXFIUs63KHMiPKnHYkGsvjhoUxGsZJbJj1Wp7lAU4R3DBqPY3TbDj0xRNNAJSGqxlBDi05XlsaBg",
                    "parts": {
                        "document": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6/credentials/2dc87b73-3eb4-4828-a840-cd0ce7bbf909/parts"
                    },
                    "workflowExecution": "https://api.emea-1.jumio.ai/api/v1/accounts/790e9aee-99ee-45ae-8ca4-4f82cf862f31/workflow-executions/0a3ccbad-da8a-4048-a589-81281d1f13f6"
                }
            }
        ]
    }
}

```

### Step 3: Launch the Workflow

The account creation response provides three integration options:

#### Option 1: Use Jumio's Hosted Interface

Use workflowExecution.web.href in one of these ways:

- Redirect: Send users to the URL in a new browser tab
- WebView: Load the URL in a mobile app WebView component
- iFrame: Embed the experience in your webpage

```
<iframe src="https://hosted.jumio.com/workflow/abc123" width="100%" height="700"></iframe>
```

#### Option 2: Integrate Jumio SDKs

Initialize the SDK using workflowExecution.sdk.token. Refer to the Jumio SDK documentation for implementation details.

#### Option 3: Build Custom Interface with API

Use the workflowExecution.api.workflowExecution endpoint to upload images directly.
Finalize the workflow using the finalization endpoint.

**Endpoint URL**

```
PUT https://api.{{region}}.jumio.link/api/v1/accounts/{{accountId}}/workflow-executions/{{workflowExecutionId}}
```

For guidance on using this approach, contact [Jumio support](https://www.jumio.com/contact/support/).

### Step 4: Callback Handling

1. Jumio will send a POST request to the configured callback URL upon workflow completion.
2. You will receive callbacks for Doc Proof once the workflow is completed.
3. The callback payload contains limited information and primarily serves as a notification of workflow completion.

### Step 5: Retrieve Workflow Details

Upon receiving the callback, make an immediate GET request to the Retrieval API. To consume the "Workflow Details," refer to the Retrieval API Endpoint. You will likely need to include a workflow ID (potentially available in the callback or the initial account creation response).

The response retrieved will contain the detailed outcome of the Doc Proof process, including verification status, extracted data (if applicable), and any rejection reasons or error codes.

```
{
   "workflow": {
       "id": "string",
       "status": "PROCESSED",
       "definitionKey": "10026",
       "userReference": "mandatory user reference",
       "customerInternalReference": "transaction_1234"
   },
   "account": {
       "id": "string"
   },
   "createdAt": "2025-06-17T08:35:55.121Z",
   "startedAt": "2025-06-17T08:36:57.629Z",
   "completedAt": "2025-06-17T08:36:58.239Z",
   "credentials": [
       {
           "id": "string",
           "category": "DOCUMENT",
           "parts": [
               {
                   "classifier": "1",
                   "href": "https://retrieval.emea-1.jumio.ai/.../parts/1"
               }
           ]
       }
   ],
   "decision": {
       "type": "PASSED",
       "details": {
           "label": "PASSED"
       },
       "risk": {
           "score": 0.0
       }
   },
   "steps": {
       "href": "https://retrieval.emea-1.jumio.ai/.../steps"
   },
   "capabilities": {}
}

```

For further details, advanced use cases, or support with customization, please refer to the complete [API documentation](../developer-resources/API/) or contact [Jumio support](https://www.jumio.com/contact/support/).

---

# Authentication

https://documentation.jumio.ai/docs/quickStart/authentication

# Quickstart Guide: Authentication

## Prerequisites

To initiate the Jumio Authentication Workflow, you must have an existing basis for verification (i.e., a valid selfie). Examples include:

- A completed workflow with a "PASSED" liveness decision (liveness.decision = PASSED).
- A previously captured selfie using Jumio’s user interface (preferred), or an image enrolled via API.

## Step-by-Step Process

### Step 1: Authenticate and Get OAuth2 Bearer Token

- Generate an OAuth2 Bearer token by calling the `/token` endpoint with the POST HTTP method.
- Use **Basic Authentication** with the **client ID** and **client secret** found in the settings section of your Jumio Portal.
- Once obtained, include the token in the `Authorization` header for all subsequent API requests.

:::tip
Refer to the [Authentication documentation](../developer-resources/API/authorization) for the specific endpoint to obtain this token.
:::

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

:::note

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests and reduce integration costs, **do not call the `/auth` endpoint before every transaction**. Instead, **reuse the same access token until it expires**, and request a new one only when needed.
- For testing purposes, you can use Postman's built-in **OAuth 2.0 authorization type** (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
- For a step-by-step walkthrough, check out this [short video guide](https://share.vidyard.com/watch/HZqWPsZAAHaPVRYktaDudf).
  :::

### Step 2: Update an Account for Authentication

Trigger an account and update by calling the `/accounts` endpoint with the PUT method.

The body must include a valid `workflowDefinition` with key **10014**.

#### Endpoint

```
https://account.{{api_endpoint}}.jumio.ai/api/v1/accounts/{{accountId}}
```

#### Region-Specific Endpoints

<ul>
<li>US: https://account.amer-1.jumio.ai/api/v1/accounts/{{accountId}}</li>
<li>EU: https://account.emea-1.jumio.ai/api/v1/accounts/{{accountId}}</li>
<li>SG: https://account.apac-1.jumio.ai/api/v1/accounts/{{accountId}}</li>
</ul>

#### Example Request

```
{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    "key": 10014
  }
}

```

#### Example Response

```
{
{
   "timestamp": "2025-06-17T15:44:48.584Z",
   "account": {
       "id": "UUID"
   },
   "web": {
       "href": "https://jumio-go.web.emea-1.jumio.ai/web/client?baseUrl=https%3A%2F%2Fweb-sdk.emea-1.jumio.ai%2Fwebsdk%2Fv4%2Fapi&authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMOw4CMQxF0a2g1FiKHdtJ6JBopmUHzq9CQwESSIi9k4EV0F6d916uP493d3AYhaJGn5IEdHtntS5tdkuoQytCoCzAAz1k7gxoRakoshXe-A_HUJtag6GFgUNLkDj2uZUQfbOuXCd-jP4Pr-c-pl5Ou9vd1maX69q3_P3IQoGlCKRYCJgygRETiGCtvgfB0Nz7A6HwtdPnAAAA.Qgkm4uSfXqK5c1bZqZwRz1ZdihFvEWgnfZa6LaldH8mavc-fcLyFShAck72_OIVOPMcDFr_ofH7dBLIFsctcdA&locale=it"
   },
   "sdk": {
       "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMOw4CMQxF0a2g1FiKHdtJ6JBopmUHzq9CQwESSIi9k4EV0F6d916uP493d3AYhaJGn5IEdHtntS5tdkuoQytCoCzAAz1k7gxoRakoshXe-A_HUJtag6GFgUNLkDj2uZUQfbOuXCd-jP4Pr-c-pl5Ou9vd1maX69q3_P3IQoGlCKRYCJgygRETiGCtvgfB0Nz7A6HwtdPnAAAA.Qgkm4uSfXqK5c1bZqZwRz1ZdihFvEWgnfZa6LaldH8mavc-fcLyFShAck72_OIVOPMcDFr_ofH7dBLIFsctcdA"
   },
   "workflowExecution": {
       "id": "UUID",
       "credentials": [
           {
               "id": "UUID",
               "category": "FACEMAP",
               "allowedChannels": [
                   "WEB",
                   "SDK"
               ]
           },
           {
               "id": "UUID",
               "category": "SELFIE",
               "allowedChannels": [
                   "WEB",
                   "SDK"
               ]
           }
       ]
   }
}

```

### Step 3: Complete the Authentication Workflow

#### Option 1: Jumio Hosted Interface

Use workflowExecution.web.href in one of the following ways:

- Redirect to a browser tab
- WebView in a mobile app
- iFrame embedded in your website:

```
<iframe src="https://hosted.jumio.com/workflow/abc123" width="100%" height="700"></iframe>
```

#### Option 2: Jumio SDKs

Use `workflowExecution.sdk.token` to initialize the SDK. Refer to [Jumio’s SDK documentation](../developer-resources/SDKs/introduction) for full implementation guidance.

### Step 4: Retrieve Workflow Details

Use the Workflow Retrieval API to obtain the full outcome.

#### Endpoint URL

```
https://retrieval.{{api_endpoint}}/api/v1/workflow-executions/{{workflow_execution_id}}
```

#### Example Response

```
{
  "workflow": {
    "id": "UUID",
    "status": "PROCESSED",
    "definitionKey": "10014",
    "customerInternalReference": "transaction_1234"
  },
  "account": {
    "id": "UUID"
  },
  ...
  "decision": {
    "type": "PASSED",
    "details": {
      "label": "PASSED"
    },
    "risk": {
      "score": 0.0
    }
  }
}
```

The response retrieved will contain the detailed outcome of the Authentication process.

For further details, advanced use cases, or support with customization, please refer to the complete [API documentation](../developer-resources/API/) or contact [Jumio support](https://www.jumio.com/contact/support/).

---

# Standalone Risk Signal

https://documentation.jumio.ai/docs/quickStart/standaloneRiskSignal

# Quickstart Guide: Standalone Risk Signal

In many workflows, you may need to provide or enhance the data. This typically includes information to activate risk signals (such as phone or email) and may also involve your custom, shared data inputs.

## Prerequisites

To retrieve your Credentials, log in to the portal and obtain your **client ID** and **client secret**. These are required to authenticate the /token endpoint.

## Step-by-Step Process

### Step 1: Authenticate and Get OAuth2 Bearer Token

- Generate an OAuth2 Bearer token by calling the `/token` endpoint with the POST HTTP method.
- Use **Basic Authentication** with the **client ID** and **client secret** found in the settings section of your Jumio Portal.
- Once obtained, include the token in the `Authorization` header for all subsequent API requests.

:::tip
Refer to the [Authentication documentation](../developer-resources/API/authorization) for the specific endpoint to obtain this token.
:::

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

:::note

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests and reduce integration costs, **do not call the `/auth` endpoint before every transaction**. Instead, **reuse the same access token until it expires**, and request a new one only when needed.
- For testing purposes, you can use Postman's built-in **OAuth 2.0 authorization type** (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
- For a step-by-step walkthrough, check out this [short video guide](https://share.vidyard.com/watch/HZqWPsZAAHaPVRYktaDudf).
  :::

### Step 2: Create or Update an Account

Use the `/accounts` endpoint to initiate a new workflow for either a [new](../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) or an [existing](../developer-resources/API/account#tag/Account/paths/~1api~1v1~1accounts~1%7BaccountId%7D/put) user.

:::tip
A workflow defines which Jumio services will process your user's credentials.
:::

#### New User

- US: POST https://account.amer-1.jumio.ai/api/v1/accounts
- EU: POST https://account.emea-1.jumio.ai/api/v1/accounts
- SG: POST https://account.apac-1.jumio.ai/api/v1/accounts

#### Existing User

- US: PUT https://account.amer-1.jumio.ai/api/v1/accounts/{{accountId}}
- EU: PUT https://account.emea-1.jumio.ai/api/v1/accounts/{{accountId}}
- SG: PUT https://account.apac-1.jumio.ai/api/v1/accounts/{{accountId}}

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    key": "10549" //ID + Selfie + Supporting Data
  }
}
```

### Step 3: Initiate a Prepared Data Workflow for the Account

Use the /accounts endpoint with the POST method along with your chosen workflowDefinition.key and customerInternalReference with respective key.

**Endpoint**

```
https://account.{{api_endpoint}}.jumio.ai/api/v1/accounts/{{accountId}}
```

#### Region-Specific Endpoints

- US: https://account.amer-1.jumio.ai/api/v1/accounts/{{accountId}}
- EU: https://account.emea-1.jumio.ai/api/v1/accounts/{{accountId}}
- SG: https://account.apac-1.jumio.ai/api/v1/accounts/{{accountId}}

#### Example Request

The body of the request is a JSON object with the desired or required values. For example:

```
{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    "key": 10148
  }
}

```

#### Example Response

```
{
   "timestamp": "2025-06-17T15:12:06.525Z",
   "account": {
       "id": "UUID"
   },
   "workflowExecution": {
       "id": "UUID",
       "credentials": [
           {
               "id": "UUID",
               "category": "DATA",
               "allowedChannels": [
                   "API"
               ],
               "api": {
                   "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOPQpCMRAE4LukduHtyyabtbO09QbJ_oBgpaKCeHfzvIHlDN_AvJO_Dve0T8hlQVml1dxq2qWuerTZZw-jlRsw1QYkLNDIFNitBxYsHWXjP4zZOhkVWLVPnGsGoUXBFxk2zNcaMfEz_B-uJ4-pb-fLw69b_o0Nh45oDja4A3E4jHkeRpCoObeBnD5fIy12X-AAAAA.2u6Ol6XjKcEpKjXnLkK1C7iwpeCpOgeEEfmgHhtdRvHTo-_EaV75l49-UjkIUZraMY7bP-q9QhPRAxhFUK17-A",
                   "parts": {
                       "prepared_data": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff/credentials/d8e0ac83-4bb4-4d22-b529-67337fe7591c/parts/PREPARED_DATA"
                   },
                   "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff"
               }
           }
       ]
   }
}
```

### Step 4: Upload Prepared Data

Prepared data is uploaded by making a POST request to the prepared_data URL from the account response. The request uses Bearer Token authorization with the token from the account response.

:::note

- If your workflow involves ID, selfie, or document checks that are collected through Jumio’s user interface (SDK or Web), the prepared data must be submitted before initiating these checks.
- To prevent SQL/XML injection threats, the character set `[^<>"/;`%{}|]` is not allowed in the prepared data body values for the following keys: firstName, lastName, middleName, paternalSurname, maternalSurname, email, and phoneNumber.
  :::

#### Prepared Data Upload URL

```
POST /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/PREPARED_DATA
```

#### Example

##### Example 1: Prepared Data: eKYC

```
{
   "firstName": "Cortez",
   "lastName": "Crook",
   "email": "johndoe@gmail.com",
   "phoneNumber": "+8009376310",
   "dateOfBirth": "1990-08-10",
   "socialSecurityNumber": "999999999",
   "sex": "0",
   "address": {
       "line1": "1302 Fayette drive",
       "postalCode": "46816",
       "city": "Fort Wayne",
       "subdivision": "IN",
       "country": "USA"
   },
   "id": {
       "idNumber": "N1244572",
       "type": "DRIVER_LICENSE"
   },
   "kyc": {
       "registrationDate": "2016-06-07",
       "registrationIpAddress": "176.80.185.187"
   }
}
```

##### Example 2: Prepared Data: Email Risk

```
{
   "email": "johndoe@gmail.com"
}
```

#### Example Response

```
{
   "timestamp": "2025-06-17T15:13:54.025Z",
   "account": {
       "id": "UUID"
   },
   "workflowExecution": {
       "id": "UUID"
   },
   "api": {
       "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOPQpCMRAE4LukduHtyyabtbO09QbJ_oBgpaKCeHfzvIHlDN_AvJO_Dve0T8hlQVml1dxq2qWuerTZZw-jlRsw1QYkLNDIFNitBxYsHWXjP4zZOhkVWLVPnGsGoUXBFxk2zNcaMfEz_B-uJ4-pb-fLw69b_o0Nh45oDja4A3E4jHkeRpCoObeBnD5fIy12X-AAAAA.2u6Ol6XjKcEpKjXnLkK1C7iwpeCpOgeEEfmgHhtdRvHTo-_EaV75l49-UjkIUZraMY7bP-q9QhPRAxhFUK17-A",
       "parts": {},
       "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/3efd4278-7468-4979-84dc-7edaf1515a19/workflow-executions/13da4d45-2ca8-4363-940c-e09bdbde26ff"
   }
}
```

### Step 5: Finalize the Transaction

Finalize the workflow using the finalization endpoint

**Endpoint URL**

```
PUT https://api.{{region}}.jumio.link/api/v1/accounts/{{accountId}}/workflow-executions/{{workflowExecutionId}}
```

For guidance on using this approach, contact [Jumio support](https://www.jumio.com/contact/support/).

**Example Response**

```
{
   "timestamp": "2025-06-17T15:19:08.980Z",
   "account": {
       "id": "UUID",
   },
   "workflowExecution": {
       "id": "UUID"
   }
}

```

### Step 6: Wait for the Callback

Jumio will send a callback when the workflow is complete. This only includes No PII data/non-sensitive data status info, so proceed to retrieve full details. You can check the callback [here](../developer-resources/callback).

:::tip
Callback times vary by workflow—please wait accordingly. For Testing purposes you may use Webhooks as mentioned [here](https://webhook.site/).
:::

### Step 7: Retrieve the Workflow Details

Once the workflow is completed and you’ve received the callback, retrieve the full decision and credential results using the workflowExecution endpoint.

```
{
   "workflow": {
       "id": "UUID",
       "status": "PROCESSED",
       "definitionKey": "10066",
       "userReference": "yourUser",
       "customerInternalReference": "transaction_1234"
   },
   "account": {
       "id": "UUID"
   },
   "createdAt": "2025-06-17T15:26:40.485Z",
   "startedAt": "2025-06-17T15:27:25.640Z",
   "completedAt": "2025-06-17T15:27:29.196Z",
   "credentials": [
       {
           "id": "UUID",
           "category": "DATA",
           "parts": [
               {
                   "classifier": "PREPARED_DATA",
                   "href": "https://retrieval.emea-1.jumio.ai/api/.../parts/PREPARED_DATA"
               }
           ]
       }
   ],
   "decision": {
       "type": "REJECTED",
       "details": {
           "label": "TXN_REJECTED"
       },
       "risk": {
           "score": 100
       }
   },
   "steps": {
       "href": "https://retrieval.emea-1.jumio.ai/.../steps"
   },
   "capabilities": {
       "emailVerification": [
           {
               "id": "UUID",
               "credentials": [
                   {
                       "id": "UUID",
                       "category": "DATA"
                   }
               ],
               "decision": {
                   "type": "REJECTED",
                   "details": {
                       "label": "HIGH_RISK"
                   }
               },
               "data": {
                   "emailVerificationStatus": "EmailInexistent",
                   "firstVerifiedAt": "2015-10-27T00:00:00.000Z",
                   "totalHits": "1",
                   "emailExists": false,
                   "domainExists": true,
                   "domainName": "jumio.com",
                   "domainCompany": "Jumio",
                   "domainRiskLevel": "LOW",
                   "domainCreationDate": "2004-03-30T07:07:55.000Z",
                   "advice": "DATA_REVIEW",
                   "domainCountry": "USA",
                   "domainCategory": "Technology",
                   "domainCorporate": true
               }                           }
                       ]
                   }
               ]
           }
       ]
   }
}
```

The response retrieved will contain the detailed outcome of the Prepared Data process.

For further details, advanced use cases, or support with customization, please refer to the complete [API documentation](../developer-resources/API/) or contact [Jumio support](https://www.jumio.com/contact/support/).

---

# Fastfill + Existing Credentials Verification

https://documentation.jumio.ai/docs/quickStart/fastFill

# QuickStart Guide: Fastfill + Existing Credentials Verification
#
Fastfill enables customers to capture and extract ID data quickly and pre-fill user information (first name, last name, date of birth, etc.) without running fraud or authenticity checks.

To maintain complete security, customers must run the full ID Verification workflow **after Fastfill** by using the [Existing Credentials workflow](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/using-existing-credential).

This guide explains how to authenticate, launch Fastfill, extract user data, and complete verification using the previously captured ID.

## Prerequisites

To retrieve your Credentials, log in to the portal and obtain your **client ID** and **client secret**. These are required to authenticate the /token endpoint.

## Step-by-Step Process

### Step 1: Authenticate and Get OAuth2 Bearer Token

- Generate an OAuth2 Bearer token by calling the /token endpoint with the **POST** HTTP method.
- Use **Basic Authentication** with the **client ID and client secret** found in the **settings** section of your customer portal.
- Once obtained, include the token in the Authorization header for all subsequent API requests.

:::note
Refer to the [Authentication documentation](../developer-resources/API/authorization) for the specific endpoint to obtain this token.
:::

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Response

```
{
  "access_token": "<your_token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

:::note

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests and reduce integration costs, **do not call the `/auth` endpoint before every transaction**. Instead, **reuse the same access token until it expires**, and request a new one only when needed.
- For testing purposes, you can use Postman's built-in **OAuth 2.0 authorization type** (under the Authorization tab), which allows you to retrieve and manage tokens automatically across your requests or collections.
- For a step-by-step walkthrough, check out this **[short video guide](https://share.vidyard.com/watch/HZqWPsZAAHaPVRYktaDudf)**.
  :::

### Step 2: Initiate a Fastfill Transaction (Capture + Extraction Only)

Fastfill is used strictly for fast data capture and extraction. It does not perform fraud detection or authenticity checks.
Use the /accounts endpoint to initiate a Fastfill workflow definition (for example, workflow 10172)

:::tip
A workflow defines which Jumio services will process your user's credentials.
:::

#### New User

- US: POST https://account.amer-1.jumio.ai/api/v1/accounts
- EU: POST https://account.emea-1.jumio.ai/api/v1/accounts
- SG: POST https://account.apac-1.jumio.ai/api/v1/accounts

#### Existing User

- US: PUT https://account.amer-1.jumio.ai/api/v1/accounts/{accountId}
- EU: PUT https://account.emea-1.jumio.ai/api/v1/accounts/{accountId}
- SG: PUT https://account.apac-1.jumio.ai/api/v1/accounts/{accountId}

#### Access Token URLs (OAuth2)

<ul>
<li>US: https://auth.amer-1.jumio.ai/oauth2/token</li>
<li>EU: https://auth.emea-1.jumio.ai/oauth2/token</li>
<li>SG: https://auth.apac-1.jumio.ai/oauth2/token</li>
</ul>

#### Header

```
Accept: application/json
```

#### Body (x-www-form-urlencoded)

```
grant_type=client_credentials
```

#### Example Request

```
{
    "customerInternalReference":"transaction_1234",
    "workflowDefinition":{
        "key": 10172,
    },
    "web": {
        "href": "https://hosted.jumio.com/...",
        "successUrl": "https://yourapp.com/success",
        "errorUrl": "https://yourapp.com/error"
    }
}
```

#### Example Response

```
{
    "timestamp": "ISO-8601 timestamp",
    "account": {
        "id": "UUID"
    },
    "web": {
        "href": "href": "https://hosted.jumio.com/fastfill/...",
        "successUrl": "https://yourapp.com/success"
    },
    "sdk": {
        "token": "<token>"
    },
    "workflowExecution": {
        "id": "UUID",
        "credentials": [
            {
                "id": "UUID",
                "category": "ID",
                "label": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "<token>",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>"
                }
            }
        ]
    }
}
```

### Step 3: User Completes Fastfill Flow

The end-user scans their ID. Data such as first name, last name, address, and date of birth is extracted automatically.

#### Key Benefits

- User onboarding becomes very fast (“Registrazione Veloce” in Italian)
- Customer receives highly reliable, machine-extracted data

:::important
Fastfill does not run Fraud checks or Image checks.
:::

### Step 4: Retrieve Extracted Data (Optional)

Use the Retrieval API to fetch the extracted ID data if needed.

```
GET /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}
```

### Step 5: Run Full ID Verification using Existing Credentials

After Fastfill, run a complete Verification workflow using **Existing Credentials**, allowing Jumio to reuse:

- the previously uploaded ID document
- extracted data
- images

This avoids asking the user to resubmit their ID. Use the Existing Credentials workflow, commonly after Fastfill.

**Endpoint URL**

```
PUT https://account.{{region}}.jumio.ai/api/v1/accounts/{accountId}
```

Use a workflowDefinition key representing **ID Verification**, such as **10570** (or any customer-specific verification workflow).

#### Example Request

```
{
  "customerInternalReference": "transaction_1234",
  "workflowDefinition": {
    "key": "10570"
  }
}
```

### Step 6: Workflow Finalization

Once the supporting data has been uploaded, the workflow must be finalized to start the verification process. While integrating via API, you must explicitly call the finalization endpoint.

#### Example Finalization Call

```

curl --location --request PUT 'https://api.amer-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}' \
--header 'Authorization: Bearer xxx'

```

### Step 7: Retrieve Final Verification Result

Once processing is completed, retrieve the full results, including:

- Verification status
- Extracted data
- Images
- Reject reasons (if applicable)

Upon receiving the callback, consume the retrieval API with the GET HTTP method:

- US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}
- EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}
- SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}

Once you receive the response from the Retrieval API, parse it to:

- Determine the final status (e.g., passed, rejected, etc.). Learn more about risk scores here.
- Review the extracted document data.
- Take the appropriate next steps based on the results.

#### Example Response

```
{
    "workflow": {
        "id": "UUID",
        "status": "PROCESSED",
        "definitionKey": "10570",
        "userReference": "MyUser",
        "customerInternalReference": "transaction_1234"
    },
    "account": {
        "id": "UUID"
    },
    "createdAt": "2022-11-28T23:45:02.528Z",
    "startedAt": "2022-11-28T23:50:37.221Z",
    "completedAt": "2022-11-28T23:50:55.232Z",
    "credentials": [
         {
            "id": "UUID",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/FRONT"
                },
                {
                    "classifier": "BACK",
                    "href": "https://retrieval.amer-1.jumio.ai/.../parts/BACK"
                }
            ],
            "consent": {
                "decisionAccepted": true,
                "collectedBy": "CUSTOMER"
            }
        }
    ],
    "decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    },
    "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-11-28T23:50:40.136Z"
    },
    "steps": {
        "href": "https://retrieval.amer-1.jumio.ai/.../steps"
    },
    "capabilities": {
        "extraction": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "DRIVING_LICENSE",
                    "subType": "REGULAR_DRIVING_LICENSE",
                    "issuingCountry": "USA",
                    "firstName": "JOHN JACOB",
                    "lastName": "SMITH",
                    "dateOfBirth": "1969-01-18",
                    "expiryDate": "2025-01-18",
                    "issuingDate": "2019-12-26",
                    "documentNumber": "N1234567",
                    "state": "CA",
                    "gender": "M",
                    "currentAge": "54"
                }
            }
        ],
        "usability": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
    }
}

```

For further details, advanced use cases, or support with customization, please refer to the complete [API documentation](../developer-resources/API/) or contact [Jumio support](https://www.jumio.com/contact/support/).

---

# Introduction

https://documentation.jumio.ai/docs/developer-resources/API/Integration_Intro

# Introduction

This guide outlines the essential steps and best practices for integrating with the Jumio Platform. It begins with key integration prerequisites, followed by instructions on how to authenticate, obtain proper authorization, and create transactions. You'll also learn how to create or update accounts, understand applicable rate limits, and manage credential acquisition workflows.

To support various use cases, the guide covers how to upload support data, initiate batch transactions, and configure callbacks. Additionally, you’ll find details on how to view or retrieve workflow transactions, test with the mock service, and manage end-user consent requirements.

Finally, we include best practices to ensure a smooth implementation, steps to perform a health check, and guidance on how to provide feedback to improve the integration experience.

---

# Integration Prerequisites

https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites

# Integration Prerequisites

Work with your Jumio Account Manager to complete these prerequisites before getting started with the Jumio integration.

## Workflow Key Value(s)

Obtain your workflow key value from your Jumio Account Manager. You will use the workflow key value to trigger your workflow as described in this document.

If your integration will use multiple workflows, obtain all required keys.

## OAuth2 Token Activation for API Integration

Contact your Jumio Account Manager to activate OAuth2 for your account. Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account before an OAuth2 access token can be generated.

## Jumio Platform Configuration

There are **Identity Verification Settings** that need to be configured before starting your Jumio integration. See [About the Identity Verification Settings](/docs/portals/settings/managingUserandTenant#about-the-identity-verification-settings).

## Supported TLS Cipher Suites

The following cipher suites (listed in server-preferred order) are supported by Jumio during the TLS handshake:

- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384

These additional cipher suites are supported for the following domains:

```
portal.<region>.jumio.ai
portal.jumio.ai
*.web.<region>.jumio.ai
web-sdk.<region>.jumio.ai
diws.<region>.jumio.ai
auth.<region>.jumio.ai
```

- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-RSA-CHACHA20-POLY1305

---

# Authenticate

https://documentation.jumio.ai/docs/developer-resources/integration

# Authenticate

You integrate the Jumio Platform with your organization’s website, application, or mobile app when you want to use Jumio’s identity verification technology to ensure that your customers are who they claim to be.

:::info
Before starting your integration, complete the [Jumio Integration Prerequisites](/docs/developer-resources/API/integration-prerequisites). Consult with your Jumio account representative for additional information and assistance.
:::

## Jumio Platform Integration Process

The Jumio Platform integration process outlines the steps required to securely connect your website, application, or mobile app with Jumio’s identity verification services. This process includes authenticating API requests, configuring user accounts, initiating verification workflows, acquiring credentials, and handling transaction updates.

By completing these steps, you enable your application to submit identity verification transactions to the Jumio Platform, track their status, and retrieve verification results in a secure and scalable manner.

## Authenticate API Requests Using OAuth2

- Implement a service to obtain bearer tokens for authorizing API requests via the [Jumio Endpoint](https://documentation.jumio.ai/docs/developer-resources/API/) or use the Java Client Library for automatic token management.

## Enable Credential Acquisition

- Enable credential upload and workflow initiation through the Jumio Web Client, Mobile SDKs, Java Client Library, and/or REST APIs, checkout [Credential Acquisition](/docs/developer-resources/API/credential-acquisition).

- Create or update user accounts using the Rest APIs, checkout [this](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) or the Java Client Library to initiate transactions.

## Handle Callbacks and Retrieve Transactions

- Set up a [Callback service](/docs/developer-resources/callback) for handling status notifications about the transactions.

- [View or Retrieve](/docs/developer-resources/retrieval) workflow transaction.

![Integration Diagram](../../src/images/customerIntegration.png)

---

# Authorization

https://documentation.jumio.ai/docs/developer-resources/API/authorization

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Authorization

:::caution
Basic authentication is currently deprecated for the Jumio REST APIs.
:::

## OAuth 2.0 Authorization and Access Token Generation

All calls to Jumio REST APIs should be authorized using OAuth2 Bearer Tokens. You obtain the bearer token by calling the Access Token URL (OAuth2) for your region with your API token and secret values, which you can find in the Jumio Portal under:

**_Settings > Identity Verification > API credentials > OAuth2 Clients_**

## Transaction-Specific Tokens

:::info
A transaction-specific token is generated when you create or update an account. This token, used for uploading credentials and finalizing the workflow, is included in the response of the account creation or update call.
:::

## Security Best Practices for Token Handling

As a security best practice, requests for bearer tokens should be server-to-server, to avoid making your Client ID and Client secret values available to an end-user’s device. Regardless of the integration channel, the end-user’s device should notify your server when a token is required. Your server should make the call to the Jumio OAuth server, and then pass the token to the end-user device.

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation. Access your Client ID and Client secret from the Portal. See [API Credentials](/docs/portals/settings/IDVSettings#api-credentials).

## Access Token Validity and Refresh

:::important

- OAuth 2.0 access tokens are valid for **60 minutes (3600 seconds)** by default.
- To avoid unnecessary authentication requests, access tokens are cached internally, and consecutive calls may return the same token. To prevent 401 Unauthorized errors, refresh the token a few minutes before it expires. You can check the token’s expiration by decoding it and examining the exp (expiration) and iat (issued at) claims.
- For testing purposes, you can use Postman’s built-in OAuth 2.0 authorization type (under the Authorization tab), which can automatically retrieve and manage tokens across your requests or collections.
  :::

## Transport Security Requirements

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [Supported Cipher Suites](/docs/developer-resources/API/integration-prerequisites#supported-cipher-suites).

## Access Token URLs (OAuth2)

- **US:** `https://auth.amer-1.jumio.ai/oauth2/token`
- **EU:** `https://auth.emea-1.jumio.ai/oauth2/token`
- **SG:** `https://auth.apac-1.jumio.ai/oauth2/token`

## Rate Limits and Error Handling

:::note
Calls with missing, incorrect, or suspicious headers or parameter values will result in `HTTP status code 400 Bad Request Error` or `403 Forbidden`.
`oauth2/token` requests are subject to [Rate Limits](../API/CreateUpdateAccounts/rate-limits). The default rate limit is 10 per second. If the rate limit is reached, a `HTTP 429 Too many requests` status code is returned.
:::

## Example: Request Access Token

<Tabs>
  <TabItem value="curl" label="curl">
```bash
curl --location 'https://auth.amer-1.jumio.ai/oauth2/token'\
    -u CLIENT_ID:CLIENT_SECRET \
    --header 'Accept: application/json'\
    --data-urlencode 'grant_type=client_credentials'
```
  </TabItem> 
  <TabItem value="python" label="Python">
```python
import requests
from requests.auth import HTTPBasicAuth

client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
url = "https://auth.amer-1.jumio.ai/oauth2/token"

response = requests.post(
url,
auth=HTTPBasicAuth(client_id, client_secret),
headers={"Accept": "application/json"},
data={"grant_type": "client_credentials"}
)

````
  </TabItem>
  <TabItem value="java" label="Java Spring Boot">
```java
import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import org.springframework.util.*;

public class OAuthClient {

    public static void main(String[] args) {
        String clientId = "CLIENT_ID";
        String clientSecret = "CLIENT_SECRET";
        String url = "https://auth.amer-1.jumio.ai/oauth2/token";

        RestTemplate restTemplate = new RestTemplate();

        // Set Basic Auth Header
        HttpHeaders headers = new HttpHeaders();
        headers.setBasicAuth(clientId, clientSecret);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        // Create body
        MultiValueMap<String, String> body = new LinkedMultiValueMap<>();
        body.add("grant_type", "client_credentials");

        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(body, headers);

        // Send POST request
        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, request, String.class);

        System.out.println(response.getBody());
    }
}
````

  </TabItem> 
  <TabItem value="php" label="PHP">
```php
<?php
$clientId = "CLIENT_ID";
$clientSecret = "CLIENT_SECRET";
$url = "https://auth.amer-1.jumio.ai/oauth2/token";

$data = http_build_query([
"grant_type" => "client_credentials"
]);

$options = [
    "http" => [
        "header" => [
            "Authorization: Basic " . base64_encode("$clientId:$clientSecret"),
"Content-Type: application/x-www-form-urlencoded",
"Accept: application/json"
],
"method" => "POST",
"content" => $data
]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === FALSE) {
die("Error occurred while making the request.");
}

echo $response;
?>

````
  </TabItem>
  <TabItem value="typescript" label="Typescript">
```typescript
import axios from "axios";
import qs from "qs"; // To encode form data

const clientId = "CLIENT_ID";
const clientSecret = "CLIENT_SECRET";
const url = "https://auth.amer-1.jumio.ai/oauth2/token";

async function fetchToken() {
    try {
        const response = await axios.post(
            url,
            qs.stringify({ grant_type: "client_credentials" }),
            {
                headers: {
                    "Accept": "application/json",
                    "Content-Type": "application/x-www-form-urlencoded",
                },
                auth: {
                    username: clientId,
                    password: clientSecret,
                },
            }
        );

        console.log(response.data);
    } catch (error) {
        console.error("Error fetching token:", error);
    }
}

fetchToken();
````

  </TabItem> 
</Tabs>

---

# Callback Integration

https://documentation.jumio.ai/docs/developer-resources/callback

# Callback Integration

Configure a callback URL to automatically receive notifications about the status of each transaction.

You can set a **global callback URL** in the [Application Settings](../portals/settings/aboutIDVSettings) in the Jumio Portal, or override it per request using the `callbackUrl` as an optional field in the Account creation or update request body, see [Creating or Updating Accounts](./API/CreateUpdateAccounts/creating-and-updating-accounts).

## Best Practices

- Use callbacks to track workflow processing.
- Save the received callback data and respond with **200 OK** to Jumio.
- After receiving callbacks, retrieve transaction details or images using the retrieval APIs, refer [Calling Retrieval APIs](./API/retrieval).

## Callback IP Allowlist

Allowlist the following IP addresses and hostnames for callbacks, and use them to verify that the callback originated from Jumio.

| Data Center Region  | IP Addresses                                                                                                                                   | Callback Hostname          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **US Data Center**  | <ul><li>34.202.241.227</li><li>34.226.103.119</li><li>34.226.254.127</li><li>52.8.136.236</li><li>54.177.61.57</li><li>54.183.15.212</li></ul> | `callback.amer-1.jumio.ai` |
| **EU Data Center**  | <ul><li>34.253.41.236</li><li>35.157.27.193</li><li>52.48.0.25</li><li>52.57.194.92</li><li>52.58.113.86</li><li>52.209.180.134</li></ul>      | `callback.emea-1.jumio.ai` |
| **SGP Data Center** | <ul><li>3.0.109.121</li><li>52.76.184.73</li><li>52.77.102.92</li><li>13.238.100.17</li><li>13.238.203.238</li><li>52.64.132.26</li></ul>      | `callback.apac-1.jumio.ai` |

## Callback Parameters

An HTTP **POST** request is sent to your specified callback URL containing an application/json formatted string with the transaction status and metadata.

| Parameter                         | Type   | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `callbackSentAt`                  | string | UTC timestamp of the callback in the format: `YYYY-MM-DDThh:mm:ss.SSSZ`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `userReference`                   | string | User reference (if set in initiate call)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `workflowExecution`               | object | Contains details about the workflow execution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `workflowExecution.id`            | string | UUID of the workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `workflowExecution.href`          | string | URL to retrieve workflow details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `workflowExecution.definitionKey` | string | Key of the workflow definition that was executed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `workflowExecution.status`        | string | Possible values:<ul><li>`INITIATED`- Transaction created; user has not started the workflow.</li> <li>`PROCESSED`- The workflow has been successfully processed.</li><li>`ACQUISITION_STARTED`- The user has opened the transaction link, and the acquisition started. <strong>Note:</strong> This status is only available if enabled. Please contact Jumio Support to activate it.</li><li>`ACQUIRED`- The user has completed the required verification steps. <strong>Note:</strong> This status is only available if enabled. Please contact Jumio Support to activate it.</li><li>`SESSION_EXPIRED`- The session expired before the user could complete the workflow.</li><li>`TOKEN_EXPIRED`- The access token has expired before the transaction was started.</li></ul> |
| `account`                         | object | Contains account details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `account.id`                      | string | UUID of the account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `account.href`                    | string | URL to retrieve account details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

**Example**

```json
{
  "callbackSentAt": "2025-07-28T14:27:46.776Z",
  "userReference": "string",
  "workflowExecution": {
    "id": "2222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href": "https://retrieval.emea-1.jumio.ai/api/v1/workflow-executions/2222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "definitionKey": "10172",
    "status": "PROCESSED"
  },
  "account": {
    "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href": "https://retrieval.emea-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}
```

---

# View or Retrieve Workflow Transactions

https://documentation.jumio.ai/docs/developer-resources/retrieval

# View or Retrieve Workflow Transactions

Workflow transactions record end-user activity and provide decisions, risk scores, and credential evaluation results. Each transaction includes:

- **Metadata**: Unique transaction ID, account ID, and UTC timestamps.
- **Service Information**: Decisions and scores returned, rules triggered, and credentials evaluated.
- **Transaction decisions and risk scores**: Overall decision, risk score, and rules applied to determine the outcome.

Transactions can be:

- Viewed in the [Jumio Portal](../portals/explorer/viewing-transaction-details).
- Retrieved programmatically via [Retrieval APIs](../developer-resources/retrieval#calling-retrieval-apis).

## Transaction Decisions and Risk Scores

Each executed transaction includes a **decision**. The decision is based on the risk scorethat indicates the overall level of fraud risk for the transaction. The decision is provided as a JSON object in the [Workflow Details](../developer-resources/retrieval#workflow-details) response and can be seen in the Portal.

**Example: Decision Object**

```json
"decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    }
```

### Risk Scores

Scores for transactions range from -1 to 100, with:

- -1 indicating that the workflow was not executed.
- 0 indicating no identified risk.
- 100 indicating extremely high risk.

:::note
Transactions that are started but not completed are assigned a score of -1 and a decision:type value of NOT_EXECUTED. This usually happens when the end-user exits the process before submitting the necessary credentials.
:::

```json
"decision": {
  "type": "NOT_EXECUTED",
  "details": {
    "label": "TOKEN_EXPIRED"
  },
  "risk": {
    "score": -1.0
  }
},
```

### Decision Types

The transactions is assigned a **decision type** value based on the score. By default the decision types are determined as follows:

- PASSED = 0-30
- WARNING = 31-70
- REJECTED = 71-100
- NOT_EXECUTED = -1

:::tip
The decision type thresholds can be configured to meet your needs and risk appetite. Contact [Jumio Support](https://www.jumio.com/contact/support/).
:::

### Decision Details Labels

| Decision Type | Label           | Description                                                                                                                                                                                |
| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PASSED        | PASSED          | Label is the same as the type value.                                                                                                                                                       |
| REJECTED      | REJECTED        | Label is the same as the type value.                                                                                                                                                       |
| WARNING       | WARNING         | Label is the same as the type value.                                                                                                                                                       |
| NOT_EXECUTED  | TOKEN_EXPIRED   | The bearer token obtained from the [Creating or Updating Accounts](../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) response expired prior to finalization. |
| NOT_EXECUTED  | SESSION_EXPIRED | The session expired prior to finalization.                                                                                                                                                 |

### Capability Decisions

Each capability or risk signal that is called by the transaction workflow returns its own risk score and decision type. For transactions that call a single service, the transaction score and decision type are the same as the service score. However, the service is first assigned a decision type based on factors specific to each service, and the service score depends on the decision type:

- PASSED = 0
- WARNING = 50
- REJECTED = 100
- NOT_EXECUTED = -1

See the reference topics listed under [Capabilities Overview](../references/capabilities/) and [Risk Signals](../references/riskSignals/overviewRiskSignals) for descriptions of when and why the decision types are assigned.

For workflows that call multiple services or risk signals, the overall transaction score is calculated from the weighted average of each of the services. Weights are applied so that more significant services and signals have a greater impact on the overall score.

:::info
The values of any rules that are triggered by the transaction also impact the overall score. See [Rules Management](../portals/rules-management/rulesManagement).
:::

## Calling Retrieval APIs

Use the Retrieval APIs to programmatically fetch workflow transactions, credentials, and risk scores, enabling automated access to transaction data.

These APIs provide the following capabilities:

- **Workflow Status**:
  Obtain the processing status of a transaction. Depending on the workflow, a transaction may take several minutes to complete. The Status API helps determine when the transaction details are available.

- **Workflow Details**:
  Retrieve workflow metadata, credentials (including URLs for accessing each credential part), and the capabilities executed during the workflow.

- **Workflow Steps**:
  Get information about each service called during the workflow and the capabilities executed for that service.

- **Individual Workflow Credentials**:
  Access specific credentials associated with a transaction.

- **PDF Transaction Report**:
  Download a transaction report as a PDF via a provided URL.

For the complete API specification see: [Retrieval API Reference](../developer-resources/API/retrieval)

### Retrieval Best Practices and Recommended Retry Policy

Before retrieving transaction details, ensure that the transaction is **complete**:

- If you have implemented a **Callback service**, wait for the callback before requesting the transactions details.
- Alternatively, use the **Workflow Status API**. If the transaction status is:
  - PROCESSED: The transaction is complete, and details/images can be retrieved.
  - SESSION_EXPIRED or TOKEN_EXPIRED: The transaction was unsuccessful, and details will not be available.

**Recommended Retry Policy**

To accommodate any brief interruptions to the retrieval service Jumio recommends you implement a retry policy:

- Start with an initial retry after 40 seconds.
- Allow a maximum of 10 consecutive unsuccessful retrieval attempts after receiving the callback.
- Recommended retry intervals(in seconds):
  `40, 60, 100, 160, 240, 340, 460, 600, 760, 940`

:::important
If the transaction status remains UNPROCESSED after 940 seconds (approx. 15.5 minutes) of retrying using the recommended exponential backoff strategy, you should:

- Stop further retrieval attempts.
- Check the [Jumio Status Page](https://monitor.jumio.com/) for any known incidents or delays.
- If no issue is reported, reach out to [Jumio Support](https://support.jumio.com/s/) for further investigation.

This approach avoids unnecessary load on your system and Jumio's APIs during potential service incidents or processing delays.
:::

### Workflow Status

The Status API returns information about the status of the transaction. This is typically used to verify that the transaction has completed before retrieving the details.

**Example Status Response**

```json
{
  "account": {
    "id": "42ff9aeb-62ce-4481-99bd-b56346a4ba1a",
    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/42ff9aeb-62ce-4481-99bd-b56346a4ba1a"
  },
  "workflowExecution": {
    "id": "c3257562-941c-440c-bc9b-f59478bb48ef",
    "href": "https://retrieval.amer-1.jumio.ai/api/v1/workflow-executions/c3257562-941c-440c-bc9b-f59478bb48ef",
    "definitionKey": "10549",
    "status": "PROCESSED"
  }
}
```

| Parameter                       | Type   | Note                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account                         | object | Possible values:<br /> - account.id<br /> - account.href                                                                                                                                                                                                                                                                                                                                                            |
| account.id                      | string | UUID of the account                                                                                                                                                                                                                                                                                                                                                                                                 |
| account.href                    | string | URL to retrieve account details                                                                                                                                                                                                                                                                                                                                                                                     |
| workflowExecution               | object | Possible values:<br /> - workflowExecution.id<br /> - workflowExecution.href<br /> - workflowExecution.definitionKey<br /> - workflowExecution.status                                                                                                                                                                                                                                                               |
| workflowExecution.id            | string | UUID of the workflow                                                                                                                                                                                                                                                                                                                                                                                                |
| workflowExecution.href          | string | URL to retrieve workflow details                                                                                                                                                                                                                                                                                                                                                                                    |
| workflowExecution.definitionKey | string | Key of the workflow definition which you executed                                                                                                                                                                                                                                                                                                                                                                   |
| workflowExecution.status        | string | Possible values:<br /> - INITIATED<br />Waiting for credentials to be uploaded and the transaction finalized.<br /> - ACQUIRED<br />Transaction has been finalized but processing has not completed.<br /> - PROCESSED<br />The transaction is completed.<br /> - SESSION_EXPIRED<br />The session expired prior to finalization.<br /> - TOKEN_EXPIRED<br />The authorization token expired prior to finalization. |

### Workflow Details

The Execution Details API returns detailed information about:

- The workflow metadata and execution timestamps in UTC:
  - `createdAt`<br />The timestamp when the end user started the customer journey.
  - `startedAt`<br />The timestamp when the workflow execution started, following the call to finalize after all credentials were uploaded.
  - `completedAt`<br />The timestamp when the transaction was completed, the decision was available, and the documents saved.
- An array of the credentials that were evaluated, including URLs for accessing the credential parts.<br />See also: [Credential Reference](../references/credentials/#id) for information about the various types of credentials.

:::tip
If enabled for your tenant, each credential object will include a `"consent"` object with information on if and when the end user consent was obtained. See [Jumio End-User Consent Documentation](../developer-resources/API/end-user-consent).
:::

- The overall decision that was rendered by the workflow.<br />See [Transaction Decisions and Risk Scores](./retrieval#transaction-decisions-and-risk-scores).
- If enabled for your tenant, a `"consent"` object with information on if and when the end user consent was obtained.<br />See [Jumio End-User Consent Documentation](../developer-resources/API/end-user-consent).
- An array of the capabilities that were executed, with details on the decision that was rendered by the capability, and any additional data returned by the capability. See also: [Capabilities Reference](../references/capabilities/).

:::info
Detail requests are subject to Rate Limits.
:::

**Example: Details Response**

<details>

```json
{
  "workflow": {
    "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
    "status": "PROCESSED",
    "definitionKey": "10549",
    "userReference": "MyUser",
    "customerInternalReference": "MyCompany"
  },
  "account": {
    "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
  },
  "createdAt": "2022-11-28T23:45:02.528Z",
  "startedAt": "2022-11-28T23:50:37.221Z",
  "completedAt": "2022-11-28T23:50:55.232Z",
  "credentials": [
    {
      "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
      "category": "SELFIE",
      "parts": [
        {
          "classifier": "FACE",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
        }
      ],
      "consent": {
        "decisionAccepted": true,
        "collectedBy": "CUSTOMER"
      }
    },
    {
      "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
      "category": "FACEMAP",
      "parts": [
        {
          "classifier": "FACEMAP"
        },
        {
          "classifier": "LIVENESS_1",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_1"
        },
        {
          "classifier": "LIVENESS_3",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_3"
        },
        {
          "classifier": "LIVENESS_2",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_2"
        },
        {
          "classifier": "LIVENESS_5",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_5"
        },
        {
          "classifier": "LIVENESS_4",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_4"
        },
        {
          "classifier": "LIVENESS_6",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_6"
        }
      ],
      "consent": {
        "decisionAccepted": true,
        "collectedBy": "CUSTOMER"
      }
    },
    {
      "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
      "category": "ID",
      "parts": [
        {
          "classifier": "FRONT",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT"
        },
        {
          "classifier": "BACK",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
        }
      ],
      "consent": {
        "decisionAccepted": true,
        "collectedBy": "CUSTOMER"
      }
    }
  ],
  "decision": {
    "type": "WARNING",
    "details": {
      "label": "WARNING"
    },
    "risk": {
      "score": 50.0
    }
  },
  "consent": {
    "obtained": "yes",
    "obtainedAt": "2022-11-28T23:50:40.136Z"
  },
  "steps": {
    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/steps"
  },
  "capabilities": {
    "extraction": [
      {
        "id": "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
        "credentials": [
          {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        },
        "data": {
          "type": "DRIVING_LICENSE",
          "subType": "REGULAR_DRIVING_LICENSE",
          "issuingCountry": "USA",
          "firstName": "JOHN JACOB",
          "lastName": "SMITH",
          "dateOfBirth": "1969-01-18",
          "expiryDate": "2025-01-18",
          "issuingDate": "2019-12-26",
          "documentNumber": "N1234567",
          "state": "CA",
          "gender": "M",
          "currentAge": "54"
        }
      }
    ],
    "similarity": [
      {
        "id": "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
        "credentials": [
          {
            "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
            "category": "SELFIE"
          },
          {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "MATCH"
          }
        },
        "data": {
          "similarity": "MATCH"
        }
      }
    ],
    "liveness": [
      {
        "id": "789f4e4a-7c2f-4764-a98d-c519d082ba6d",
        "credentials": [
          {
            "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
            "category": "SELFIE"
          },
          {
            "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
            "category": "FACEMAP"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        },
        "data": {
          "type": "JUMIO_STANDARD",
          "predictedAge": 44,
          "ageConfidenceRange": "32-56"
        }
      }
    ],
    "dataChecks": [
      {
        "id": "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
        "credentials": [
          {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      }
    ],
    "imageChecks": [
      {
        "id": "b336a404-7775-4793-9cf6-30a7e5be1d0b",
        "credentials": [
          {
            "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
            "category": "SELFIE"
          },
          {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID"
          }
        ],
        "decision": {
          "type": "WARNING",
          "details": {
            "label": "REPEATED_FACE"
          }
        },
        "data": {
          "faceSearchFindings": {
            "status": "DONE",
            "findings": [
              "22771260-8cb0-42a2-a38a-d8f853063cc2",
              "27232651-4b18-4cf1-8d4a-df0451abc717",
              "9541ae91-834e-4914-a30d-6534fed4eb6d",
              "9414413d-2c76-44d2-9052-8876fa327a02"
            ]
          }
        }
      }
    ],
    "usability": [
      {
        "id": "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
        "credentials": [
          {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      },
      {
        "id": "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
        "credentials": [
          {
            "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
            "category": "FACEMAP"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      },
      {
        "id": "e991586b-3345-4a2d-bfc3-1690ccb477b3",
        "credentials": [
          {
            "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
            "category": "SELFIE"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      }
    ]
  }
}
```

</details>

### Workflow Steps

The Steps API returns details about the services that were called by the workflow. The response includes a `"steps"` array that contains an object for each service that was called as a workflow step. Each step object contains the decision rendered by that service, a "capabilities" aray that contains an object for each capability that was executed as part of the step, and an array that simply lists the IDs of each capability that was called.

**Example: Steps Response**

<details>

```json
{
  "steps": [
    {
      "id": "73898f70-edd5-4bff-8d15-8f6e9eb81329",
      "name": "ID_IV",
      "decision": {
        "type": "WARNING",
        "details": {
          "label": "WARNING"
        }
      },
      "capabilities": [
        {
          "id": "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
          "category": "usability"
        },
        {
          "id": "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
          "category": "usability"
        },
        {
          "id": "e991586b-3345-4a2d-bfc3-1690ccb477b3",
          "category": "usability"
        },
        {
          "id": "b336a404-7775-4793-9cf6-30a7e5be1d0b",
          "category": "imageChecks"
        },
        {
          "id": "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
          "category": "dataChecks"
        },
        {
          "id": "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
          "category": "extraction"
        },
        {
          "id": "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
          "category": "similarity"
        },
        {
          "id": "789f4e4a-7c2f-4764-a98d-c519d082ba6d",
          "category": "liveness"
        }
      ],
      "capabilityIds": [
        "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
        "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
        "e991586b-3345-4a2d-bfc3-1690ccb477b3",
        "b336a404-7775-4793-9cf6-30a7e5be1d0b",
        "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
        "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
        "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
        "789f4e4a-7c2f-4764-a98d-c519d082ba6d"
      ]
    }
  ]
}
```

</details>

### Workflow Credentials

You can use the GET parts API to download the credential images and data that are associated with a transaction

The fully parameterized URLs for retrieving the credential parts are available in the Workflow Details response.

**Example**

```json
"credentials": [
        {
            "id": "66e0a64a-4afe-4e29-89e7-ae53db4aba93",
            "category": "ID",
            "clientIp": "xx.xx.xxx.xxx",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/6fec5b29-0e4c-42c4-b41f-72dc45307e53/credentials/66e0a64a-4afe-4e29-89e7-ae53db4aba93/parts/FRONT",
                    "captureType": "camera"
                }
            ]
        }
    ],
```

There will be a URL for each uploaded credential part. The part can be downloaded with a GET request to the URL. Authorization requires a valid bearer token for your tenant. See [Authorization](../developer-resources/API/authorization) for information about obtaining the bearer token.

The form of the URLs is:

```
https://retrieval.{data_center}/api/v1/accounts/{accountId}/credentials/{credentialId}/parts/{classifier}
```

#### Classifier Values and Return Types

The response body of a successful request will contain the credential part as it was stored at the conclusion of the transaction.

| Credential | Type             | Classifier Description                                                                                                                                                                                                                                                    |
| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID         | FRONT            | The file may be a PNG or a JPEG, depending on what was uploaded.                                                                                                                                                                                                          |
| ID         | FRONT_WITH_FLASH | If the ID was captured on a mobile device with a flash, the image taken with the flash is available in addition to the non-flash FRONT image.                                                                                                                             |
| ID         | BACK             | The file may be a PNG or a JPEG, depending on what was uploaded.                                                                                                                                                                                                          |
| SELFIE     | FACE             | The file may be a PNG or a JPEG, depending on what was uploaded.                                                                                                                                                                                                          |
| FACEMAP    | LIVENESS\__n_    | The parts for a FACEMAP credential typically include one or several JPEG images that can be downloaded using the URLs with the LIVENESS_n classifiers.                                                                                                                    |
| DOCUMENT   | ORIGIN           | If a PDF was uploaded, it will be available using the URL with the ORIGIN classifier.<br />Individual pages will also be available as JPEG files using URLs with the page number as the classifier. For example, to download the JPEG image of page 2, use:<br />/parts/2 |
| DATA       | PREPARED_DATA    | Contains the extracted and processed data from the uploaded credentials.                                                                                                                                                                                                  |
| DATA       | DEVICE_RISK      | Contains risk-related information about the device used during the transaction.                                                                                                                                                                                           |
| ID         | FRONT_CROPPED    | Cropped image of the front side of the ID captured by the user during the front-side capture process.(Planned for mid January 2026)                                                                                                                                       |
| ID         | BACK_CROPPED     | Cropped image of the back side of the ID captured by the user during the back-side capture process. (Planned for mid January 2026)                                                                                                                                        |
| SELFIE     | FACE_CROPPED     | Cropped image of the user’s face captured during the selfie capture process. (Planned for early-mid February 2026)                                                                                                                                                        |

#### captureType Value

The captureType will only be returned if your tenant is enabled. Contact [Support](https://www.jumio.com/contact/support/) if you are interested in this feature. For ID and Selfie parts, the `captureType` value indicates how the part was captured by the end user. Values may be:

- `camera `if the camera in the end user's device was used to capture the image.
- `upload `if the image was uploaded from the end user's device.

### PDF Generation

The Generate API returns a presigned URL that can be used to download a transaction report as a PDF. This document provides the overall decision and risk score for the transaction as well as the decision and summary information returned by each capability executed by the workflow.

The PDF transaction report is identical to the PDF accessible from the [transaction details](../portals/explorer/viewing-transaction-details) page in the Jumio Portal.

**Example: PDF Generation Response**

```json
{
  "workflowId": "8a68ee36-1663-473c-ae32-924ecdb0f33f",
  "presignedUrl": "https://core-us-prod-kyx-transaction-pdf.s3.us-east-1.amazonaws.com/8a68ee36-1663-473c-ae32-924ecdb0f33f.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIA373BKWO4OBSY5POP%2F20240520%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240520T180143Z&X-Amz-Expires=7200&X-Amz-Security-Token=IQoJb3JpZ2luX2VjELr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLW ..."
}
```

---

# Delete Credentials

https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/deleting-credentials

# Delete Credentials

You can delete the credentials associated with an **account**, or a specific **transaction**. The transaction metadata and decision will not be deleted.

## 1. All Credentials Deletion

You can delete all credentials associated with an account or a specific transaction.

### Ad-Hoc Deletion

Use the following APIs for deleting all credentials for transactions:

- [Delete All Credentials for an Account API](https://documentation.jumio.ai/developer-resources/api/retrieval#tag/Retrieval/operation/deleteAllPIIData) to delete all the credentials associated with the transaction.
- [Delete All Credentials for a Transaction API](https://documentation.jumio.ai/developer-resources/api/retrieval#tag/Retrieval/operation/deletePIIDataForWorkflowExecution) to delete a specific credential part associated with the transaction.

### Deletion via Jumio Portal

You can also delete all credentials for transactions through the Jumio Portal by navigating to the transaction details view.

![](./deleteTransaction.png)

## 2. Retention Period-Based Deletion

You can also contact [Jumio Support](https://support.jumio.com/s/) to set a retention period for all transactions for your tenant for automatic deletion of all credentials. It is normally agreed as part of the account setup process.

### How it Works

Retention policies are configured by contacting Jumio Support
The retention period is typically agreed upon during account setup
Deletion is triggered based on the last activity timestamp within an account (not per individual transaction)

### Key Consideration

This ensures that products such as Authentication continue to function for users who remain active within the retention period.

## 3. Biometrics Credentials Only Deletion

Jumio supports deleting only biometric credentials within transactions, without affecting other data.

### Ad-Hoc Deletion (via API)

Use the following APIs:

- [Delete Only Biometrics for an Account API](https://documentation.jumio.ai/developer-resources/api/retrieval#tag/Retrieval/operation/deleteAllPIIData).
  Deletes biometric credentials for all transactions under an account
- [Delete Only Biometrics for a Transaction API](https://documentation.jumio.ai/developer-resources/api/retrieval#tag/Retrieval/operation/deleteBiometricsDataForWorkflowExecution).  
  Deletes biometric credentials for a specific transaction

:::note
| **What Gets Deleted** | **What Is Retained** |
| -------------------------------------------------------------- | ----------------------------------------------- |
| Face vectors and embeddings | Original images (e.g., selfies or ID documents) |
| Stored biometric templates used for matching or authentication | Transaction metadata |
| | Verification results |
| | Other non-biometric credentials |
:::

### Impact of Biometrics Deletion

Once biometric data is removed:

- Face matching and face lookup can no longer be performed for that transaction
- Authentication and liveness checks cannot reuse previously stored biometric data
- Deleted biometric data is not recreated, even if the transaction is accessed again

### Deletion via Jumio Portal

You can also delete biometric credentials through the Jumio Portal by navigating to the transaction details view.
![](./deleteTransaction.png)

## 4. Retention Period-Based Biometrics Deletion

You can configure automatic deletion specifically for biometric data.

- Requires configuration through Jumio Support
- Applies to all transactions within a tenant
- Typically defined during account setup

:::important

- Retention and deletion policies for credentials containing PII are governed by Data Settings in the Jumio Portal
- Retention-based deletion uses the last activity time within an account, not individual transaction timestamps
- This ensures continued functionality for active users
  :::

:::warning
Credential deletion is permanent and irreversible. Once deleted, the data cannot be recovered.
:::

---

# Test with the Mock Service

https://documentation.jumio.ai/docs/developer-resources/API/test-with-the-mock-service

# Test with the Mock Service

Jumio provides a mock service you can use to generate specific transaction outcomes. This is useful for testing any decision logic you have developed to respond to specific decisions returned by Jumio. Consistently producing the full range of decision values your integration may encounter is often difficult or impossible using actual transactions. By using the mock service you can develop robust sets of tests that use synthetic transactions to produce specific outcomes.

:::tip
The mock service requires a dedicated tenant that is configured to support it. Contact [Jumio Support](https://www.jumio.com/contact/support/) or your account manager to create and configure the tenant if you want to use the mock service. All transactions that are initiated in a tenant that is configured to use the mock service will use the service.
:::

You initiate a synthetic transaction as you would any other transaction, with these differences:

- Use OAuth2 credentials from a tenant configured to support the mock service to obtain the bearer token for authorizing the account request.

- Specify the desired state of the decision in a JSON string passed as the value of the `"customerInternalReference"` key in the body of the account request.

## Example: Synthetic Transaction

The following example shows how to initiate a synthetic ID+Selfie transaction for workflow 10549. The account request body is the same as for a regular transaction, except that the `"customerInternalReference"` value is a string representation of a JSON object that specifies the desired decision state.

### Account Request Body

```
{
	"customerInternalReference": "{\\"customerInternalReference\\":\\"mockuser\\", \\"decisionLabel\\":\\"NFC\_CERTIFICATE\\", \\"credentialWithDecision\\":\\"ID\\", \\"extractionOverrides\\":{\\"firstName\\":\\"JOHN\\", \\"idType\\":\\"PASSPORT\\", \\"issuingCountry\\":\\"USA\\", \\"lastName\\":\\"DOE\\"}}",
	"userReference":"Jumio Documentation",
	"workflowDefinition":{
		"key": 10549
	},
	"userConsent": {
		"userIp": "226.80.211.232",
		"userLocation": {
			"country": "USA",
			"state": "IL"
		},
		"consent": {
			"obtained": "yes",
			"obtainedAt": "2022-07-20T17:20:35.000Z"
		}
	}
}
```

:::note
The `customerInternalReference` value is a string. Therefore quotation marks inside the JSON object must be escaped using a \\ character.
:::

### Decision

The transaction details for a mock transaction are available from the retrieval API or in the Portal. For the account request above, the transaction decision would look like this:

```
	"decision": {
		"type": "REJECTED",
		"details": {
			"label": "MISMATCHING\_DATAPOINTS"
		},
		"risk": {
			"score": 99.0
		}
	},
```

In the `"capabilities"` block the `"dataChecks"` JSON would look like this:

```
		"dataChecks": \[
			{
				"id": "5960c353-614c-445c-9506-219e1a1dbd38",
				"credentials": \[
					{
						"id": "df82c2ed-76e8-4ff9-aa53-270b5a9e3d54",
						"category": "ID"
					}
				\],
				"decision": {
					"type": "REJECTED",
					"details": {
						"label": "MISMATCHING\_DATAPOINTS"
					}
				}
			}
		\],
```

In this case the `"MISMATCHING_DATAPOINTS"` label specified in the account request is only returned by the Data Checks capability. The other workflow capabilities have a `decision.type` value of `"PASSED"` and a `decision.details.label` value of `"OK"`.

:::note
If a workflow capability has a dependency on a capability that is given a `decision.type` of `"REJECTED"`, the dependent capability will have a `decision.type` value of `"NOT_EXECUTED"` and a `decision.details.label` value of `"PRECONDITION_NOT_FULFILLED"`.
:::

### Specifying the Decision State

The value of the `"customerInternalReference"` field in the account request body is a string representation of a JSON object. The fields in the JSON object determine the decision values that will be returned for the mock transaction:

- A fitting decision for the given `"decisionLabel"` value will be applied to any fitting capability in any fitting credential.

- If there are mutliple credentials, the credential can be selected by the `"credentialWithDecision"` value.

- Specific values to be returned in the `capabilities.extraction.data` object can be set in `"extractionOverrides"` value. The value is a nested JSON string.

By default, all decisions for capabilities that do not return the specified `"decisionLabel"` will have a `"type"` value of `"PASSED"` and a `"label"` value of `"OK"`.

Any capabilities that have a dependency on a capability with a mocked `"REJECTED" decision.type` will be set to `"NOT_EXECUTED"`.

| Field                     | Description                                                                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| customerInternalReference | Provides a way to set the value as you would for a regular transaction.                                                                                                                                                                          |
| decisionLabel             | Specifies the decision label you want to appear in the decision. This value will be used to determine the decision for any capability that returns the label, as well as for the overall transaction decision.                                   |
| credentialWithDecision    | Allows you to specify which credential will trigger the decision. For example, if the workflow processes both an ID and a Selfie and both are evaluated by the Usability capability, you can control which Usability instance gets the decision. |
| extractionOverrides       | A nested JSON sting that allows you to override the default Extraction data values.                                                                                                                                                              |

---

# Business Logic Guidelines

https://documentation.jumio.ai/docs/developer-resources/businessLogicGuide

# How to Handle Workflow Results in Jumio?

Handling workflow results effectively is essential to ensure a smooth and secure identity verification process. In Jumio, workflow results provide valuable insights into the outcome of each verification step, enabling your business logic to determine the appropriate next actions for users.

This guide outlines best practices and key considerations for interpreting workflow results and implementing decision logic—helping you streamline user experiences, reduce friction, and maintain compliance and security standards.

## Top-Level Decision Object

The top-level object in the Jumio response consists of a score and a type by default. This logic results from evaluating the applicable capabilities.

Additionally, if configured with a ruleset ID, Jumio can apply a decision-mapping layer that summarizes complex verification outcomes into clear, standardized result codes.

This optional feature makes it easier to understand why a transaction was rejected or flagged by surfacing the underlying reason directly in the top-level response.

- Please ask your Jumio representative for assistance with enabling this, if desired. Doing so will allow the results of the ruleset to be displayed at the top-level workflow response object for easy decisioning.
- Otherwise, your business logic will need to parse through the capabilities in the response to determine where any irregularities occurred (see table [below](#recommended-actions-for-common-verification-outcomes) for common handling decisions for various outcomes).

## Standard Jumio Verification Rules

:::note
Jumio includes some default behavior that you may wish to change. Speak to an Integration Specialist at Jumio to learn about how to align this behavior to your use case requirements.
:::

Some examples include:

- Jumio rejects photocopied documents by default.
- By default, multiple people detection occurs during the liveness detection capability.
- Repeated faces result in **“WARNING”** decisions.
- Jumio does not, by default, return **“WARNING”** decisions for expired documents – this needs to be configured with assistance from your Jumio representative.

## Recommended Actions for Common Verification Outcomes

The following table summarizes common Jumio results and suggested actions for handling them.
These examples are not exhaustive and should be adapted to your specific business logic and risk requirements.

| **Step / Capability**                                                                        | **Jumio Result** | **Common Action**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Risk Score = 0**                                                                           | Low risk         | Indicates low or no detected risk. Approve the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **[Usability](https://documentation.jumio.ai/docs/references/capabilities/usability)**       | REJECTED         | If a transaction comes back with REJECTED for the Usability category, that doesn’t necessarily mean that it’s a fraudulent transaction. It just means that the user wasn’t able to provide suitable images for the transaction, as described by the [specific decision detail label](https://documentation.jumio.ai/docs/references/capabilities/usability#decision-details-labels). Common next steps are to prompt to retry, perhaps on a different channel. For example, if the user formerly completed the transaction on their desktop browser, invite them to try again on their mobile browser, etc.                                                                                                                                                       |
| **[Usability](https://documentation.jumio.ai/docs/references/capabilities/usability)**       | WARNING          | Route accordingly based on your use case requirements for the country/document. Check country settings and evaluate internally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **[Extraction](https://documentation.jumio.ai/docs/references/capabilities/extraction)**     | REJECTED         | Extraction is always either passed or not executed. NOT_EXECUTED can be the result of a competing automation setting configuration. This could be an artifact of an automated extraction issue or a “missing mandatory data point,” e.g., a required data point was not able to be extracted (such as if some glare were blurring the DOB field on a document, etc.).                                                                                                                                                                                                                                                                                                                                                                                             |
| **[Image Checks](https://documentation.jumio.ai/docs/references/capabilities/image-checks)** | REJECTED         | Typically maps to fraud/bad actor. Make your decision a specific function of the decision label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **[Image Checks](https://documentation.jumio.ai/docs/references/capabilities/image-checks)** | WARNING          | There are currently only three WARNING decision labels for this category: <ul><li>Different person</li><li>Repeated face</li><li>Ghost image quality insufficient</li></ul>Additional detail about each of these exceptions is described [here](https://documentation.jumio.ai/docs/references/capabilities/image-checks#decision-details-labels). Each should be uniquely handled with regard to your use case requirements. It is strongly recommended to implement Jumio’s [update account endpoint](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) to minimize the occurrence of repeated faces to only those transactions that are not expected to be affiliated with the same account ID. |
| **[Data Checks](https://documentation.jumio.ai/docs/references/capabilities/data-checks)**   | REJECTED         | Typically maps to fraud/bad actor. However, make your decision a specific function of the decision label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **[Data Checks](https://documentation.jumio.ai/docs/references/capabilities/data-checks)**   | WARNING          | Handle each of these as needed by your use case requirements, as each can be quite particular.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **[Liveness](https://documentation.jumio.ai/docs/references/capabilities/liveness)**         | REJECTED         | Typically maps to fraud/bad actor. Each decision label possibility should be circumstantial and reviewed to align with your specific business use case requirements. Handle individually based on the specific reject reason (e.g., multiple people) to create some exception handling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **[Liveness](https://documentation.jumio.ai/docs/references/capabilities/liveness)**         | WARNING          | Each decision label possibility should be circumstantial and reviewed to align with your specific business use case requirements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **[Similarity](https://documentation.jumio.ai/docs/references/capabilities/similarity)**     | NO_MATCH         | Handle circumstantially.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **[Similarity](https://documentation.jumio.ai/docs/references/capabilities/similarity)**     | NOT_POSSIBLE     | Hyper edge case, handle circumstantially.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

:::note

- A rejection in any single capability will result in a rejection for the entire transaction.
- Many rejection reasons are highly specific and should be treated as edge cases, as they may not always indicate fraudulent behavior. For example, while most **Image Check – REJECTED** decision labels typically suggest potential fraud, the **PUNCHED** decision label may not necessarily imply fraudulent intent.
  :::

:::tip
Need help building this into your code or platform? Contact our [Support team](https://support.jumio.com/s).
:::

---

# Create Transaction

https://documentation.jumio.ai/docs/developer-resources/API/create-transaction

# Create a Transaction

Transaction represents a single instance of a workflow execution (e.g. identity verification) tied to an account. To initiate a transaction, specify the associated account ID, workflow configuration, and any optional metadata. Each transaction is uniquely tracked and managed under its parent account.

---

# Create, Update, or Link Accounts

https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts

# Create, Update or Link Accounts

An account is a unique identifier (UUID) that is used to associate a set of credentials and transactions (i.e. workflow executions) with a customer. Each transaction is associated with one account, and an account can be associated with multiple transactions.

- If you are onboarding a new customer, use the [POST](https://documentation.jumio.ai/docs/developer-resources/API/account) request to create a new account.
- If you are updating an existing account, use the [PUT](https://documentation.jumio.ai/docs/developer-resources/API/account) request, with the account ID value as a path parameter.

:::important

- If you need to **[link an existing credential to an account](../CreateUpdateAccounts/using-existing-credential)** rather than creating a new one, include the existing CredentialID in your request payload.
  :::

For the complete API specification see: [Account API Reference](https://documentation.jumio.ai/docs/developer-resources/API/).

:::note
Creating or updating the account is always done through a REST API call, regardless of the integration channel. Account requests are subject to [Rate Limits](../CreateUpdateAccounts/rate-limits).
:::

## Account Request

The request body for either an account creation or account update request is a JSON object.

### Required Fields

| Field                                                                   | Type   | Max. Length | Notes                                                                                                                                                                      |
| ----------------------------------------------------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| customerInternalReference                                               | string | 100         | Customer internal reference for a request to link it in the customer backend (must not contain any PII). Must not contain any of the following characters: &lt;&gt;"/;`%{} |
| [workflowDefinition](creating-and-updating-accounts#workflowdefinition) | object | 255         | A `key` value is required to specify the workflow for the transaction. Other values may be required, depending on the workflow.                                            |

### Account Request Body Required Fields Example

```json
{
  "customerInternalReference": "myTransactionReference",
  "workflowDefinition": {
    "key": 10549
  }
}
```

### Optional Fields

| Field                                                               | Type   | Max. Length                     | Notes                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------- | ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| userReference                                                       | string | 100                             | Reference for the end user in the customer backend (must not contain any PII)                                                                                                                                                                                                                                          |
| reportingCriteria                                                   | string | 255                             | Additional information provided by a customer for searching and aggregation purposes                                                                                                                                                                                                                                   |
| callbackUrl                                                         | string | 255                             | Definition of the callback URL for this particular request. Overrides callback URL in the Jumio Portal.                                                                                                                                                                                                                |
| tokenLifetime                                                       | string | min: 5m, max: 60d, default: 30m | Should be a valid date period unit definition: s - seconds, m - minutes, h - hours d - days. Example: ‘1d’ / ‘30m’ / ‘600s’. Overrides Authorization token lifetime in the Jumio Portal.                                                                                                                               |
| [web](creating-and-updating-accounts#web)                           | object |                                 | Used to override default values that are configured in the Portal. Only relevant for the WEB channel.                                                                                                                                                                                                                  |
| [userConsent](creating-and-updating-accounts#userconsent)           | object |                                 | If your integration uses [REST APIs for Credential Acquisition](https://documentation.jumio.ai/docs/developer-resources/API/) you must obtain the end-user's consent to share their personal information with Jumio. See: [End-User Consent to Collect Personal Data](/docs/developer-resources/API/end-user-consent). |
| [overrideSettings](creating-and-updating-accounts#overridesettings) | object |                                 | Used to override some tenant settings.                                                                                                                                                                                                                                                                                 |

### workflowDefinition

A workflowDefinition object is required for all requests, and must include a `key` value that specifies the workflow for the transaction.

Additional objects may be required to configure workflows that use some services or risk signals, including:

- [Credentials](creating-and-updating-accounts#credentials) object used to specify a particular type of credential to upload for the transaction. For example, the Document Verification service (standalone workflow 10026), or any workflow that uses the [extraction](../../../references/capabilities/extraction) capability to extract data from a [document](../../../references/credentials/#document) credential.
- [Capabilities](creating-and-updating-accounts#capabilities) object used to specify configuration options for specific capabilities.

#### credentials

An array of the credentials required for the workflow. A credentials array is required if credentials are going to be uploaded by REST API calls. A credentials array is also used to:

##### credentials Object Example (ID)

- Limit the sets of [ID](../../../references/credentials/#id) types and countries that are presented to end user during the customer journey. For example, the following limits the end user to choosing either USA or Canada, and either Driving License or ID Card. No other options are presented.

```json
"credentials": [
    {
        "category": "ID",
        "country": {
                "predefinedType": "DEFINED",
                "values": ["USA", "CAN", "BRA"]
        },
        "type": {
            "predefinedType": "DEFINED",
            "values": ["DRIVING_LICENSE", "ID_CARD"]
        },
        "subType": {
            "predefinedType":"DEFINED",
            "values":["DIGITAL_DRIVING_LICENSE_PDF"]
        }
    }
]
```

:::info

- The `subType` field is only available **for Web integrations** and supports the following values: <ul><li>`DIGITAL_DRIVING_LICENSE_PDF`- This option requires `country: "BRA"` and `type: "DRIVING_LICENSE"`. </li> <li>`EIDAS`- This option requires `country: <any supported EU country>` and `type: "DIGITAL_IDENTITY"`.</li> </ul>
- In the Web Client, if exactly one country + document type combination is preconfigured in the credentials array, the document-type selection screen will be skipped, and the user will proceed directly to uploading that document.
- If multiple country and/or document type options are preconfigured, then the Web Client will show a limited selection screen, displaying only those predefined countries and document types to the end user.
  :::

##### credentials Object Example (Document)

- Specify a [document](../../../references/credentials/#document) credential to use with a Document Verification workflow such as 10026. In this case the type and country must be specified to enable the [extraction](../../../references/capabilities/extraction) capability. For example, the following is required to enable the extraction of expected values from a Bank Statement from the USA:

```json
"credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }  
            }
        ]
```

##### credentials Object Example (FACEMAP)

Specify a FACEMAP credential to use with an Authentication workflow such as 10549. In this case, the category must be set to "FACEMAP" and a type must be specified to determine the FACEMAP source.
Possible values for the FACEMAP type include:

- JUMIO_STANDARD
- JUMIO_PREMIUM

For example, the following configuration is required to enable the use of Jumio Standard FACEMAP:

```json
"credentials" : [{
    "category" : "FACEMAP",
    "type" : {
        "values" : ["JUMIO_STANDARD"]
    }
}]
```

| Field    | Type   | Notes                                                                                                                                                                                                                                                                                                                                  |
| -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id       | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                |
| category | string | Credential category. Possible values:<ul><li>ID</li> <li>DOCUMENT</li> <li>FACEMAP</li> </ul> It is not common to specify a FACEMAP. Consult with your account representative for additional information.                                                                                                                              |
| country  | object | Defined at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: `ISO 3166-1 alpha-3 country code`                                                                                                                                                                                                   |
| type     | object | Defined number of credential type codes. Possible values:<ul><li>ID_CARD</li> <li>DRIVING_LICENSE</li> <li>PASSPORT</li> <li>VISA</li><li>DIGITAL_IDENTITY</li></ul>                                                                                                                                                                   |
| subType  | object | The `subType` field is only available **for Web integrations** and supports the following values: <ul><li>`DIGITAL_DRIVING_LICENSE_PDF`- This option requires `country: "BRA"` and `type: "DRIVING_LICENSE"`. </li> <li>`EIDAS`- This option requires `country: <any supported EU country>` and `type: "DIGITAL_IDENTITY"`.</li> </ul> |

#### capabilities

Provide values for capabilities that require additional configuration properties.

| Field                                                                                     | Type   | Notes                                                                                      |
| ----------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| [watchlistScreening](creating-and-updating-accounts#watchlistscreening)                   | object | Override the default search profile.                                                       |
| [documentVerification](creating-and-updating-accounts#documentverification)               | object | Configure additional capabilities to use with Document Verification.                       |
| [ekycCheck](creating-and-updating-accounts#ekyccheck)                                     | object | Used to specify a 1+1 or 2+2 search.                                                       |
| [workflowDecision](creating-and-updating-accounts#workflowdecision)                       | object | Used to specify a ruleset to use instead of the default ruleset configured for the tenant. |
| [ruleset](creating-and-updating-accounts#ruleset-to-work-with-default-scoring-deprecated) | object | Override the default ruleset used by the workflow.                                         |

##### watchlistScreening

Used to configure the [Watchlist Screening](../../../references/capabilities/watchlist) capability by overriding the default searchProfile. Consult your Jumio representative for additional information.

```json
"capabilities":{
    "watchlistScreening": {
    }
}
```

:::info
searchProfile is the alphanumeric string that is the identifier for your searchProfile.
:::

##### documentVerification

Used to disable Extraction in cases where a Document is uploaded to be stored but extracting the data is not required. Consult your Jumio representative for additional information.

```json
"capabilities": {
    "documentVerification": {
        "enableExtraction": "false"
    }
}
```

##### ekycCheck

Includes a `searchType `value. Allowed values are:

- `one` if requesting a 1+1 check
- `two `if requesting a 2+x2 check

```json
"capabilities": {
    "ekycCheck": {
        "searchType": "one"
    }
}
```

##### workflowDecision

Used to specify a ruleset to use instead of the default ruleset configured for the tenant.

```json
"capabilities": {
    "workflowDecision": {
        "riskScoreRulesetId": "81c616b7-d47e-4cb2-8c4f-17267f2106f3"
    }
}
```

##### ruleset to work with default scoring (deprecated)

:::info
Sending rules using the workflowDecision object is preferred over using a ruleset for most cases. This flow is only to handle exceptions.
:::

Used to specify one or more rulesets to use instead of the default ruleset(s) used by the workflow.

```json
"capabilities": {
    "ruleset": {
        "ids": ["id1", "id2", "id3"]
    }
}
```

The values in the "ids" array are the ruleset IDs of the rulesets you want to use. See also: [Working with Rules](../../../portals/rules-management/working-with-rules#rules).

#### web

These values are only relevant for the WEB channel. They are used to override the default values that are configured in the Portal. See [Application Settings.](https://documentation.jumio.ai/docs/portals/settings/aboutIDVSettings)

| Field      | Type   | Max. Length | Notes                                                                                                                                     |
| ---------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| successUrl | string | 1900        | URL to which the browser will send the end user at the end of a successful web acquisition user journey. Overrides default success URL.\* |
| errorUrl   | string | 1900        | URL to which the browser will send the end user at the end of a failed web acquisition user journey. Overrides default error URL.\*       |
| locale     | string | 5           | Renders content in the specified language. Overrides Default locale.                                                                      |

:::note
Success and error URLs provided through an Account request are less restrictive than the defaults. For example, local domains and schemes for deep linking are supported.
:::

##### web Object Example

```json
"web":{
 "successUrl":"https://www.yourcompany.com/success",
 "errorUrl":"https://www.yourcompany.com/error",
 "locale":"es"
}
```

### userConsent

Checkout [End-User Consent to Collect Biometric Data](/docs/developer-resources/API/end-user-consent) for details.

#### User Consent JSON

```json
"userConsent": {
 "userIp": "226.80.211.232",
 "userLocation": {
   "country": "USA",
   "state": "IL"
 },
 "consent": {
   "obtained": "yes",
   "obtainedAt": "2022-07-20T17:20:35.000Z"
 }
}
```

### overrideSettings

You can override the following tenant settings for a transaction on the Web Client, the Web SDK and Mobile SDK:

| Field                   | Type    | Notes                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `crossDeviceOnly`       | boolean | Specifies whether credential acquisition must be completed on a mobile device. Possible values: <ul><li>`true`, </li> <li>`false`.</li> </ul>                                                                                                                                                                                                       |
| `crossDeviceOption`     | string  | Specifies how a mobile device receives the connection. Possible values: <ul><li>`DEFAULT` – end user can choose email or QR code;</li> <li>`QR_ONLY` – only the QR code option is shown; </li> <li>`EMAIL_ONLY` – only the email option is shown.</li> </ul>                                                                                                 |
| `allowedCaptureMethod`  | string  | Specifies which capture method(s) are allowed for document submission during the verification flow. Possible values: <ul><li> `ALL` – Allows both live capture (photobooth) and file upload;</li> <li>`PHOTOBOOTH` – Allows only live capture using the device camera.</li> </ul> |
| `skipNFC`               | boolean | Specifies whether the NFC process is triggered after a document scan. Possible values: <ul><li>`true` – The NFC process is skipped.</li> <li>`false` – The NFC process is triggered when supported by the document.</li> </ul> |


#### overrideSettings Object Example

```json
{
 "customerInternalReference":"myCompany",
 "overrideSettings":{
     "crossDeviceOnly": true,
     "crossDeviceOption":"QR_ONLY",
     "allowedCaptureMethod":"ALL",
     "skipNFC": true
 },
 "workflowDefinition":{
     ...
 }
}
```

## Account Responses

The response from the API includes the UUID and additional information you will need for the transaction, including:

- The account ID and the workflow execution ID for the transaction. These values are used for [viewing or retrieving Workflow Transactions](../../retrieval).
- The fully parameterized URL for the [Web Client](../../web-client/).
- The authorization token you will need if you are using one of the [Mobile SDKs](../../SDKs/mobile-sdk/introduction-mobile).
- Details about the credentials that need to be provided for evaluation by the workflow. This includes data that will be used by the integration channel to upload the credential and associate it with the account.
  :::tip
  Workflows that evaluate multiple instances of the same type of credential can provide a "label" value to distinguish between the instances.
  :::
- The URLs you will use if you are [Uploading Credentials](../../API/credentials#tag/Credentials) using the REST APIs.

<details> 
    <summary>Example Account Response</summary>

```json
{
  "timestamp": "2022-11-28T23:45:02.536Z",
  "account": {
    "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
  },
  "web": {
    "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&locale=en-US"
  },
  "sdk": {
    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
  },
  "workflowExecution": {
    "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
    "credentials": [
      {
        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
        "category": "ID",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
          "parts": {
            "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
            "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
        }
      },
      {
        "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
        "category": "FACEMAP",
        "allowedChannels": ["WEB", "SDK"]
      },
      {
        "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
        "category": "SELFIE",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
          "parts": {
            "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
        }
      }
    ]
  }
}
```

</details>

:::note
For ID and Selfie credentials upload JPEG or PNG files with a maximum size of 15 MB and the following image resolution limits:

| Image Type         | Resolution (min) | Resolution (max) | Additional Requirements                                                            |
| ------------------ | ---------------- | ---------------- | ---------------------------------------------------------------------------------- |
| **Document Image** | 563x355 px       | 8000x8000 px     | The document must be at least **512 px wide** and **323 px high**.                 |
| **Selfie Image**   | 480x640 px       | 8000x8000 px     | The face must be at least **320 px tall** and cover **at least 15%** of the image. |

:::

---

# Use Existing Credentials

https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/using-existing-credential

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Use Existing Credentials

In the Jumio platform, customers can reuse ID, Selfie, and Facemap Credentials from previous transactions for subsequent transactions—whether performed via web, mobile, or API channels.

To be eligible for reuse, two conditions must be met,

- The original Credential must have successfully passed usability checks.
- Explicit user consent must have been obtained for the data.

:::note
This feature supports the entire Credential, not individual parts of it.
If a workflow does not require any new Credentials and all existing Credentials are reused, the workflow will be automatically finalized. In this case, you can initialize the workflow using the account update API and either wait for the callback or call retrieval directly.
:::

## Consent Requirement

Consent must be enabled to use this feature. The original transaction, in which the credential was provided to KYX, must include recorded consent.

## Channel Support

Existing-credential workflows are supported through API and SDK channels. Use these channels to ensure proper functionality.

## Multi-Credential Support

Workflows function best when each credential type is provided only once. Ensure there’s no duplication of credential types in the same workflow.

## Credential Support

| Credential | Existing Credential Supported | Preconditions                      |
| ---------- | ----------------------------- | ---------------------------------- |
| ID         | Yes                           | Usability PASSED, Consent Provided |
| FACEMAP    | Yes                           | Usability PASSED, Consent Provided |
| SELFIE     | Yes                           | Usability PASSED, Consent Provided |

## Setting Up a Workflow with Existing Credentials

When creating a workflow in Jumio Designer, you can select whether to use an existing credential.

### Initialization

- By default, the latest credential for that category on the account will be used.
- If the credential (ID, SELFIE, FACEMAP) is usable, it will be applied automatically; otherwise, an error will occur during initialization.
- You can also specify a credential explicitly using its credential identifier (`uuid`), which is included in the retrieval response of previous workflows.

### Auto-Finalization

If all credentials are existing, the workflow will be finalized automatically. After performing an account update, you do not need to call the finalization API.

**Sample workflows: 10112, 10113, 10114, 10115**
![](./workflow.png)

## Sample Requests

### Request 1: Account update – default (latest credential used)

This request uses the normal account update payload. The latest credential of each type will be used automatically if usable.

### Request 2: Account update – specific credential IDs

This request explicitly specifies which credential IDs to use for the transaction.

<Tabs>
  <TabItem value="latest" label="Request 1: Account Update – Default (Latest Credential Used)">

```json
{
  "customerInternalReference": "myTransactionReference",
  "workflowDefinition": {
    "key": 10113
  },
  "userConsent": {
    "userIp": "xxx.80.211.xxx",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2023-03-20T17:20:35.000Z"
    }
  },
  "userReference": "myUserReference"
}
```

</TabItem>

<TabItem value="specific" label="Request 2: Account Update – Specific Credential IDs">

```json
{
  "customerInternalReference": "myTransactionReference",
  "workflowDefinition": {
    "key": 10113,
    "credentials": [
      {
        "category": "ID",
        "id": "dfxcv-faddf-cdfsfds-sdsdfa"
      },
      {
        "category": "FACEMAP",
        "id": "asdfdfxcv-faddfdsf-cdfsfds-sdsd234"
      }
    ]
  },
  "userConsent": {
    "userIp": "xxx.80.211.xxx",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2023-03-20T17:20:35.000Z"
    }
  },
  "userReference": "myUserReference"
}
```

</TabItem> </Tabs>

## Sample Responses

### Case 1: When some credentials need to be uploaded

In this scenario, some credentials already exist, while others must be uploaded by the end user. The account update response includes upload links only for the credentials that require new uploads.

### Case 2: When all credentials already exist

If all required credentials are available, no upload links are included and processing starts immediately. Finalization is not required.

<Tabs>
  <TabItem value="Some Crendentials" label="Case 1">

```json
{
  "timestamp": "2023-09-08T06:30:52.164Z",
  "account": {
    "id": "89d585b9-ab3e-4de8-bb39-d79ecda2bfa7"
  },
  "workflowExecution": {
    "id": "bc6d862e-a1ae-40fa-9781-8fc755f75976",
    "credentials": [
      {
        "id": "b701e6c5-b74c-434a-866a-ef1f084a4d80",
        "category": "ID",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "<>",
          "parts": {
            "front": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976/credentials/b701e6c5-b74c-434a-866a-ef1f084a4d80/parts/FRONT",
            "back": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976/credentials/b701e6c5-b74c-434a-866a-ef1f084a4d80/parts/BACK"
          },
          "workflowExecution": "https://api.emea-1.jumio.link/api/v1/accounts/89d585b9-ab3e-4de8-bb39-d79ecda2bfa7/workflow-executions/bc6d862e-a1ae-40fa-9781-8fc755f75976"
        }
      },
      {
        "id": "b701e6c5-b74c-434a-866a-ef1f084a4d80",
        "category": "SELFIE",
        "allowedChannels": []
      }
    ]
  }
}
```

</TabItem>

  <TabItem value="All Credentials" label="Case 2">
  
  ```json
  {
    "timestamp": "2023-09-08T06:30:52.164Z",
    "account": {
        "id": "89d585b9-ab3e-4de8-bb39-d79ecda2bfa7"
    },
    "workflowExecution": {
        "id": "bc6d862e-a1ae-40fa-9781-8fc755f75976",
        "credentials": [
            {
                "id": "b701e6c5-b74c-434a-866a-ef1f084a4d80",
                "category": "ID",
                "allowedChannels": []
            }
        ]
    }
}
```
</TabItem>
</Tabs>

## Sample Error Responses

### Error 1: Account initiate used instead of account update

```json
{
  "type": "about:blank",
  "title": "Bad Request: Workflow [10113] requires [ID, SELFIE] existing credentials therefore no new account can be created. The update account endpoint has to be used instead",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts"
}
```

### Error 2: Account update used but credentials are unusable

```json
{
  "type": "about:blank",
  "title": "Bad Request: Workflow 10115 requires [ID] existing credentials but  [ID] are unusable for the account 02e2c457-9424-43dd-b691-c1a9167a4144",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts/02e2c457-9424-43dd-b691-c1a9167a4144"
}
```

### Error 3: Account update used but credential ID is invalid

```json
{
  "type": "about:blank",
  "title": "Bad Request: JSON parse error: Cannot deserialize value of type `java.util.UUID` from String dfxcv-faddf-cdfsfds-sdsdfa: UUID has to be represented by standard 36-char representation",
  "status": "400",
  "detail": "[]",
  "instance": "/api/v1/accounts/02e2c457-9424-43dd-b691-c1a9167a4144"
}
```

:::warning
If an eIDAS digital ID is used instead of a physical ID, the system does not have access to the ID face, meaning (face comparison) Similarity Checks cannot be performed. The actual ID image is also not returned. Additionally, the data points returned may differ when using an eIDAS digital ID. For risk scoring, this limitation may need to be addressed in your rules configuration. Credential reusability is also not supported when using an eIDAS digital ID.
:::

---

# Credential Acquisition

https://documentation.jumio.ai/docs/developer-resources/API/credential-acquisition

# Credential Acquisition: Customer Journey

Your end users must upload the required credentials and trigger the workflow that evaluates the credentials. Jumio refers to this process as the **"customer journey"** and provides several integration channels you can use to implement it. These include:

- [Web Client](../web-client) offers intuitive guidance for your end-users and handles interactions with their camera and other device features.
- [Jumio SDKs](../SDKs/Overview_of_SDKs) offer a complete default customer journey with options for customization.
- [REST APIs](../API/) for credential uploads and workflow finalization, giving you full control over the customer journey.

Depending on the workflow, you may also upload [supporting data](../../references/glossaries#supporting-data) in addition to an ID, Document, Selfie, and/or Facemap. Supporting data is used for enhanced fraud detection and to provide additional validation checks for extracted data. See [Uploading Supporting Data](../API/uploadingSupportData).

:::note

- Regardless of which implementation channel(s) you choose to use, all transactions are initiated by a REST API call to create or update an account. See [Creating or Updating Accounts](../../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts). The response from the call includes the tokens and URLs described in the following topics.

- Jumio software is currently not designed to work with kiosk solutions. Features such as taking a picture of the ID document and selfie will not function properly and may impact the user experience, quality, and accuracy. This includes iPads or other tablets that are operating in a mounted setup.
  :::

---

# Upload Supporting Data

https://documentation.jumio.ai/docs/developer-resources/API/uploadingSupportData

# Upload Support Data

Supporting data are values that are uploaded in addition to other credential types to support fraud detection and improve identity verification.

## Examples of Supporting Data

For example, uploading the following:

- End user name
- Phone number
- Email address
  These values are typically not available from ID data alone and can be used to check against lists of known or suspected fraudulent actors.

## Types of Supporting Data

Supporting data is typically either:

- Entered by the end-user as form data prior to initiating the Jumio customer journey.
- Retrieved from data stored previously.

:::note
Use the **[Uploading Prepared Data](./../API/credentials#tag/Credentials)** guide to submit supporting data via the PREPARED_DATA URL.”
:::

Once the supporting data is uploaded, Jumio acquires any remaining credentials and executes the **verification workflow**.

![](../../img/SupportData.png)

## Supporting Data Values

The following values can be uploaded as [Prepared Data](../../references/credentials/#data).

| **Key**               | **Type**         | **Mandatory** | **Description**                                        |
| --------------------- | ---------------- | ------------- | ------------------------------------------------------ |
| `firstName`           | `string`         | yes           | First name of the subject.                             |
| `lastName`            | `string`         | yes           | Last name of the subject.                              |
| `email`               | `string($email)` | yes           | Primary email address of the subject.                  |
| `phoneNumber`         | `string`         | yes           | Primary phone number of the subject in E.164 format.   |
| `dateOfBirth`         | `LocalDate`      | yes           | Date of birth in `YYYY-MM-DD` format only.             |
| `address`             | `Object`         | yes           |                                                        |
| `address.line1`       | `string`         | yes           |                                                        |
| `address.line2`       | `string`         | no            |                                                        |
| `address.city`        | `string`         | yes           | City of residence as it appears on the ID.             |
| `address.postalCode`  | `string`         | yes           | Postal or zip code.                                    |
| `address.subdivision` | `string`         | no            | City subdivision of residence as it appears on the ID. |
| `address.country`     | `string`         | yes           | Country in ISO-3166-1 Alpha-3 Code format.             |

## Example Prepared Data Body

```
{
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+15031234567",
    "email": "email@gmail.com",
    "dateOfBirth": "1972-11-16",
    "address": {
        "line1": "12345 SW Address Ln",
        "postalCode": "12345",
        "city": "Any Town",
        "subdivision": "OR",
        "country": "USA"
    }
}
```

---

# Batch Transactions - Jumio

https://documentation.jumio.ai/docs/developer-resources/batch/batch-transactions

# Batch Transactions

You can initiate multiple transactions and upload the required credentials as a batch using SFTP and CSV files. This process supports uploading **ID, Selfie, and document images**, as well as supporting prepared data to improve verification and fraud detection.

:::note
This feature must be enabled for your tenant, contact [Jumio Support](https://www.jumio.com/contact/support/). The feature is only available to customers using the Jumio Platform and Portal. It is not available to customers using Netverify or other older Jumio products.
:::

When batch processing is enabled for your tenant you can access the `Jumio Portal / Settings / Identity Verification / Batch Uploads` page. From which you can:

- Generate the **SSH Key** for secure SFTP uploads. See [Batch Credentials](#batch-credentials).
- Select **OAuth2 credentials** to authorize batch transactions.
- Check the status of batch jobs you have run and locate processed transactions. See [Batch Status and Locating Processed Transactions](#batch-status-and-locating-processed-transactions).

The batch files are uploaded to a folder identified by a UUID. See [Batch Uploads](#batch-uploads) for details on file formats, naming the folder, initiating the processing, and troubleshooting problems.

![](images/BatchUploadPage.png)

## Batch Credentials Setup

For the Batch Credentials Setup navigate to Jumio Portal / Settings / Identity Verification / Batch Uploads page select Batch Credentials tab and do the following:

- Select the **OAuth2 credentials** that will be used to authorize the transactions in the batch.
- Generate the **SSH Key pairs** you will use to connect to the Jumio SFTP server.

![](images/GenerateSSHKey.png)

### OAuth2 Credentials for Batch Transactions

Select the Oauth2 credentials that will be used to authorize the batch transactions.

:::info
You must select an active credential defined in the Jumio Portal / Settings / Identity Verification / Api Credentials / OAuth2 Clients page, with permissions to both **Initiate** and **Retrieve &amp; Delete**.
:::

1. Navigate to the Jumio Portal / Settings / Identity Verification / Batch Uploads page and select the **Batch Credentials tab**.
2. From the API Credential drop-down list select the credential you want to use. The list will show all active credentials, so be sure and select a credential with with permissions to both **Initiate** and **Retrieve &amp; Delete**.
3. Click **Save** and apply the credentials for all batch transactions.

The selected credential will be used to authorize all batch transactions for the tenant. You can update the credential at any time by creating a new credential in the OAuth2 Clients page and repeating the steps above.

### SSH Key Generation for SFTP

Generate the SSH key pair that will be used to encrypt data transfers between your SFTP client and the Jumio server for your tenant.

1. Navigate to the Jumio Portal / Settings / Identity Verification / Batch Uploads page and select the **Batch Credentials tab**.
2. Click **Generate new SSH Key**.
3. In the Generate new SSH Key dialog, verify that the **Merchant GUID for your tenant and your email** are correct, and click **Confirm**.
4. Copy both private and public keys from the SSH Key Pair dialog and store them securely where they can be accessed by your SFTP client. **Add Private Key to a \*.pem file** (example “sshkey.pem”) within your system to use within SFTP client for authentication

:::important
After you close the SSH Key Pair dialog the keys will no longer be available. If you lose the private key you must generate a new one.
:::

5. Close the dialog, and note the SFTP URL that is displayed. This is the URL you will connect to from your SFTP client.

:::info
The SSH key is valid for 30 days. Lost keys require generating a new key.
:::

## Batch Uploads

To upload a batch and initiate the transaction processing:

1. Connect to the SFTP server for your tenant from your SFTP Client. See [SFTP Client](#sftp-client).
2. Create a folder with a UUID for the name. See [Create Folder with UUID Name](#create-folder-with-uuid-name).
3. Upload a CSV file with the transaction data. See [CSV File Format](#csv-file-format).
4. If the transactions require ID, Selfie, and/or Document images upload the archive file. See [Images](#images).
5. Upload a file named DONE to initiate processing.

Monitor the status of the batch job in the Jumio Portal / Settings / Identity Verification / Batch Uploads page. See [Batch Status and Locating Processed Transactions](#batch-status-and-locating-processed-transactions).

### SFTP Client

In your SFTP client connect to the server for your tenant using the **SFTP URL** shown in the Jumio Portal / Settings / Identity Verification / Batch Uploads / Batch Credentials tab:

![](images/SFTPUrl.png)

Use the generated SSH Key for the connection. You will log into a home folder dedicated to your organization.

:::tip
Disable the **resume transfer** and **timestamp preservation** features if they are supported by your SFTP client.
:::

#### Create Folder with UUID Name

After connecting to the server create a folder on the server, using a UUID as the folder name. For example:

```
096c7aef-c3dd-4427-9f93-f64295b8f2d6
```

UUID generators are available in most programming languages.

#### Examples: UUID Generators

```
Python

import uuid
random_uuid = uuid.uuid4()

```

```
NodeJS

import crypto from 'crypto';

function uuidv4() {
  return ([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g, c =>
    (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> c / 4).toString(16)
  );
}

const randomUUID = uuidv4();
```

```
Java

import java.util.UUID;
UUID randomUUID = UUID.randomUUID();
```

```
.NET

Guid randomUUID = Guid.NewGuid();
```

:::note
If you are creating a folder manually, you can also search and utilize one of “UUID Generator” websites available online.
:::

### CSV File Format

Create a CSV (comma separated values) file with one header row and a row for each transaction in the batch.

#### Sample CSV File

**Download the sample file [here](/files/input.csv).**

#### Example Batch CSV File

```
workflowDefinitionKey,accountId,riskScoreRulesetId,customerInternalReference,userReference,frontImage,backImage,faceImage,document1,document1Country,document1Types,userConsentUserIp,userConsentUserLocationCountry,userConsentUserLocationState,userConsentConsentObtained,userConsentConsentObtainedAt,preparedData.firstName,preparedData.lastName,preparedData.phoneNumber,preparedData.email,preparedData.address.line1,preparedData.address.postalCode,preparedData.address.city,preparedData.address.subdivision,preparedData.address.country
10015,7473ba2b-473c-4e71-b2ad-b7040b6bcb13,,test reference 1,user12762573,FRA_ID_front.jpg,FRA_ID_back.jpg,,,,,226.80.211.232,USA,CA,yes,2022-07-20T17:20:35.000Z,,,,,,,,,
10011,,,test reference 2,user23827923,FRA_ID_front.jpg,FRA_ID_back.jpg,FRA_ID_face.jpg,,,,226.80.211.232,USA,CA,yes,2022-07-20T17:20:35.000Z,,,,,,,,,
10010,,133e9f99-519b-481b-9d92-6fdcabb75b98,test reference 3,user12861249,,,,,,,226.80.211.232,USA,CA,yes,2022-07-20T17:20:35.000Z,Roger,Jackson,4.31503E+12,abhiabhiabhi@gmail.com,12345 SW Address Ln,12345,Any Town,OR,USA
10232,7473ba2b-473c-4e71-b2ad-b7040b6bcb13,,test reference 4,user12762573,,,,USA_SSC.jpeg,USA,SSC,226.80.211.232,USA,CA,yes,2022-07-20T17:20:35.000Z,Roger,Jackson,4.31503E+12,abhiabhiabhi@gmail.com,12345 SW Address Ln,12345,Any Town,OR,USA
,,,test reference 5,user98734538
```

:::caution

- Please be cautious while using MS-Excel for CSV file handling as it tends to change formatting for certain fields when saved, which may make the CSV file invalid.
- There must be no more than 10,000 rows in the CSV file.
- If there is any field which has comma (,) included, it needs to be put within double quotes (“”) to ensure file format remains valid.
- The csv filename needs to be "input.csv". Any other filename will not be accepted.
  :::

#### Field Description

| Field                              | Required | Description                                                                                                                                                                                                                                   |
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflowDefinitionKey`            | yes      | The workflow key. Default is `10015`.                                                                                                                                                                                                         |
| `customerInternalReference`        | yes      | Customer internal reference for a request to link it in the customer backend (must not contain any PII). Must not contain any of the following characters: `` <>"/;\`%{} ``                                                                   |
| `accountId`                        | no       | Used only in case of Account Update and not a new Account Creation. Refers to Jumio-provided Account ID in response to Account Creation step. [More info](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts). |
| `riskScoreRulesetId`               | no       | Used to specify a ruleset to use instead of the default ruleset configured for the tenant. [More info](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).                                                    |
| `userReference`                    | no       | Reference for the end user in the customer backend (must not contain any PII). Must not contain any of the following characters: `` <>"/;\`%{} ``                                                                                             |
| `frontImage`                       | no       | File name of the front image, including path relative to the CSV file, if it is present in a subdirectory within the UUID directory. The file must be in the uploaded images.                                                                 |
| `backImage`                        | no       | File name of the back image, including path relative to the CSV file, if it is present in a subdirectory within the UUID directory. The file must be in the uploaded images.                                                                  |
| `faceImage`                        | no       | File name of the face (selfie) image, including path relative to the CSV file, if it is present in a subdirectory within the UUID directory. The file must be in the uploaded images.                                                         |
| `document1`                        | no       | For workflows with document verification. File name of the document, including path relative to the CSV file. File format and requirements: [see here](/docs/references/credentials/#document).                                               |
| `document1Country`                 | no       | ISO 3166-1 alpha-3 country code of the document's origin. Used for document verification.                                                                                                                                                     |
| `document1Types`                   | no       | Type of the document being processed. Supported types listed [here](/docs/references/credentials/#document).                                                                                                                                  |
| `userConsentUserIp`                | no\*     | If applicable, [consent](../API/end-user-consent) is required similar to API channel.                                                                                                                                                         |
| `userConsentUserLocationCountry`   | no\*     | If applicable, [consent](../API/end-user-consent) is required similar to API channel.                                                                                                                                                         |
| `userConsentUserLocationState`     | no\*     | If applicable, [consent](../API/end-user-consent) is required similar to API channel.                                                                                                                                                         |
| `userConsentConsentObtained`       | no\*     | If applicable, [consent](../API/end-user-consent) is required similar to API channel.                                                                                                                                                         |
| `userConsentConsentObtainedAt`     | no\*     | If applicable, [consent](../API/end-user-consent) is required similar to API channel.                                                                                                                                                         |
| `preparedData.firstName`           | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.lastName`            | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.phoneNumber`         | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.email`               | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.dateOfBirth`         | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.address.line1`       | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.address.postalCode`  | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.address.city`        | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.address.subdivision` | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |
| `preparedData.address.country`     | no\*\*   | May be required if you are [uploading supporting data](../API/uploadingSupportData).                                                                                                                                                          |

:::info

- Populating the userConsent fields conforms to the requirements described in [End-User Consent to Collect Personal Data](../API/end-user-consent).
- Any prepared data fields required by the workflow can be uploaded through the csv. Use the `preparedData` format in the header row. Some prepared data fields are required if you are [Uploading Supporting Data](../API/uploadingSupportData).
  :::

### Images

Upload all images referenced in the CSV file to the folder created with the UUID name. See also [Uploading Credentials](#batch-credentials) for additional information on image requirements.

## Batch Status and Locating Processed Transactions

You can see details about the batch job in the the Jumio Portal / Settings / Identity Verification / Batch Uploads page.

### Status

| Status Name                                | Comment                                                                                                                    |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| CREATED                                    | Initial job creation                                                                                                       |
| IN_PROGRESS                                | Job execution initialized                                                                                                  |
| IN_PROGRESS_INGEST                         | Validating the input file and ingesting into the database for processing                                                   |
| IN_PROGRESS_PROCESS                        | Create/upload credentials and finalize workflows based on data from the ingest step                                        |
| IN_PROGRESS_WAITING_PROCESSED_CONFIRMATION | All workflows are created, credentials uploaded, and finalized; now waiting for PROCESSED messages for each workflow       |
| COMPLETED                                  | Job execution received the target amount of workflow PROCESSED messages                                                    |
| COMPLETED_WITH_ERROR                       | At least one of the workflows has been errored out. See [Error Messages](../batch/batch-transactions#error-messages)       |
| ERROR                                      | An error is encountered in the middle of a job execution. See [Error Messages](../batch/batch-transactions#error-messages) |

### Error Messages

Download the job information to see error messages.

![](images/downloadBatchErrors.png)

There can be two error categories:

- If input file validation fails.
- If specific transactions have a processing error.

#### File Validation Errors

If the input file validation has errors (for example, if a required column is missing), no workflows will be executed. Fix the issue with the file and create a new batch job.

#### File Validation Error Message Example

![](images/error-message-example.png)

#### File Validation Error Messages

| Error Name             | Detail Present to User | Can User Self-Repair | Comment                                                                                                                                                               |
| ---------------------- | ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INPUT_FILE_NOT_FOUND` | YES                    | YES                  | Either the `input.csv` is not found or an image file referenced within `input.csv` is not found.                                                                      |
| `INVALID_CSV`          | YES                    | YES                  | The CSV is invalid. This could be due to: <ul><li>A string is too long</li><li>Not all headers and data are present</li><li>Other reason causing invalidity</li></ul> |
| `INVALID_FILE_SIZE`    | YES                    | YES                  | Either the `input.csv` exceeds the allowed file size, or one of the images referenced within `input.csv` exceeds the allowed file size.                               |

### Transaction Processing Errors

Transactions from the input CSV are processed sequentially by the row number. If a transaction causes an error, the batch job will not stop and will continue processing all subsequent records.
To identify any failures, you must download the error logs for the completed job. It will also show the total number of records, how many succeeded, and how many failed.
These logs contain the error details for each problematic transaction, and you only need to correct and resubmit the specific records listed in them under a new Batch Upload job.

![](images/transaction_processing_error.png)

#### Transaction Processing Error Message Example

![](images/sample_transaction_processing_error.png)

#### Transaction Processing Error Messages

| Error Name                        | Detail Present to User | Can User Self-Repair | Comment                                                                                                                                                                         |
| --------------------------------- | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JUMIO_WORKFLOW_API`              | NO                     | NO/YES               | This is an internal error, due to the Jumio API not being able to complete the workflow process.                                                                                |
| `JUMIO_WORKFLOW_API_UNAUTHORIZED` | NO                     | NO/YES               | The Jumio API rejected the workflow request with Unauthorized (401). <ul><li>The stored credential may no longer be valid or available</li><li>May need to be updated</li></ul> |
| `JUMIO_WORKFLOW_API_FORBIDDEN`    | NO                     | NO/YES               | The Jumio API rejected the workflow request with Forbidden (403). <ul><li>The stored credential may not have the required permissions</li><li>May need to be updated</li></ul>  |
| `INGEST_ERROR`                    | NO                     | NO                   | This is due to some unexpected input validation error other than the ones listed above. Contact [Support](https://www.jumio.com/contact/support/).                              |
| `PROCESS_ERROR`                   | NO                     | NO                   | This is due to some unexpected processing error while reading the raw records and creating workflows. Contact [Support](https://www.jumio.com/contact/support/).                |
| `NO_AVAILABLE_EXECUTOR`           | NO                     | NO                   | Contact [Support](https://www.jumio.com/contact/support/).                                                                                                                      |

### Locating Processed Transactions

You can retrieve all processed transactions using the same Request Reference you see on the status page as a "filter" criteria within the "Reporting Criteria" field in [explorer](../../portals/explorer/work_with_transaction_table#filtering-data-in-the-explorer) page on Jumio Portal.

![](images/processedBatchTransactions.png)

:::info
Remember, batch transactions use the API Channel.
:::

---

# End-User Consent

https://documentation.jumio.ai/docs/developer-resources/API/end-user-consent

# End-User Consent to Collect Personal Data

End-user consent is required whenever Jumio collects or processes personal data as part of an Identity Verification workflow. This includes both government-issued **ID documents** and **biometric data**. Collecting consent ensures that the end user understands _what personal data is being captured, why it is required, and how it will be used_.

## When End-User Consent Is Required

By default, Jumio retrieves and acts as the data controller for end-user credentials used in Identity Verification services. Transactions that include collecting [ID](/docs/references/credentials/#id) or biometric credentials, such as a [Selfie](/docs/references/credentials/#selfie) or [Facemap](/docs/references/credentials/#facemap), require end-user consent prior to uploading the data.

If your integration implements the customer journey using the Web Client or the default SDK UIs, user consent management is built into the UI.

If your integration uses the mobile SDK with custom UIs, see the **Consent Handling** section of the integration guides for the [Mobile SDK](/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile):

- [Android Controller and Consent Handling](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#controller-handling)
- [iOS Controller and Consent Handling](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#controller-handling)

If your integration uses REST APIs to upload credentials, you are responsible for obtaining the end user's consent, as described below.

If you require access to the consent details for a transaction, see [Retrieving Consent Details](../API/end-user-consent#retrieving-consent-details).

## Incorporating Consent Language and Linking to Jumio’s Privacy Notice in Your UI

If you are using the API channel, you must incorporate explicit consent collection language and a link to Jumio’s Privacy Notice in your application, along with mechanisms for collecting the consent data (for example, checkboxes or buttons) prior to acquiring the end-user's credentials:

> “I consent to Jumio collecting, processing, and sharing my personal information, which may include biometric data, as set out in its [Privacy Notice](https://www.jumio.com/legal-information/privacy-notices/online-services-notice/).”

:::info
The Jumio Privacy Notice is at: [https://www.jumio.com/legal-information/privacy-notices/online-services-notice/](https://www.jumio.com/legal-information/privacy-notices/online-services-notice/).
:::

### Example Screen Showing Consent Language

![Example Screen Showing Consent Language](../../../src/images/StartVerificationConsentExample.png)

## Populating the User Consent JSON

The user consent data must be added to the body of the Account creation or update request, as shown in the following example:

```json
"userConsent": {
    "userIp": "226.80.211.232",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2022-07-20T17:20:35.000Z"
    }
}
```

:::tip
If the credential is rejected you can add or update the `userConsent` object and re-submit using the Account Update API.
:::

See also:

- [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts)
- [Account API Reference](/docs/developer-resources/API/account)

## Processor

By default Jumio acts as a data controller for the end-user credentials. In some cases Jumio will act as a data processor. For a description of how the European Union defines data controller and data processor for purposes of complying with GDPR rules checkout: [What is a data controller or a data processor?](https://commission.europa.eu/law/law-topic/data-protection/reform/rules-business-and-organisations/obligations/controllerprocessor/what-data-controller-or-data-processor_en)

Even if Jumio is acting as a data processor, if the end user is located inside the United States and biometric data is collected on the API channel, consent language must still be presented to the end user, and populating the userConsent object is mandatory. If not provided or not accepted the transaction will be rejected during the credential upload. However, implicit consent is allowed, instead of requiring the user to explicitly check a box. The following is an example of how consent may be presented to the end user, but you may use your own custom language as long as the required elements are present:

:::tip
By clicking **“Start”** you consent to Jumio collecting, processing, and sharing your personal information, which may include biometric data, pursuant to its Privacy Notice.
:::

## Retrieving Consent Details

By default details about if and when the end user consent was obtained are not provided in the Workflow Details. If you require access to the user consent details contact your Jumio Account Manager or Technical Support to enable retrieval for your tenant. Once it is enabled the data will be included in the workflow details response.

If enabled, the workflow details response will include:

- A consent JSON object for the transaction, including the UTC timestamp for when the consent was obtained:

  ```
      "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-11-28T23:50:40.136Z"
      },
  ```

- A consent JSON object for each credential:

  ```
              "consent": {
                  "decisionAccepted": true,
                  "collectedBy": "CUSTOMER"
              }
  ```

---

# Direct Consent Requirements

https://documentation.jumio.ai/docs/developer-resources/API/direct-consent-requirements

# Direct Consent Requirements

If you are utilizing the API or Custom UI SDK for data acquisition, Jumio requires you to incorporate specific language, collect consent on behalf of Jumio, and provide Jumio with a record of the consent. This page summarizes the requirements for collecting consent on Jumio’s behalf.

## Consent Requirements

<details>
<summary>Why does consent need to be collected from the end user?</summary>

As a data controller, Jumio relies on consent to process personal information for Jumio Services.

</details>

---

<details>
<summary>What type of consent is required?</summary>

End users must provide direct consent to **Jumio’s collection and sharing of personal information, including biometric data**.

</details>

---

<details>
<summary>What do I need to do?</summary>

Display the required consent language with a control for explicit, affirmative action — such as a checkbox or radio button that the end user must toggle before they can proceed.

**The required language is as follows and must include the link to Jumio’s privacy notice:**

> “I consent to Jumio collecting, processing, and sharing my personal information, which may include biometric data, pursuant to its [Privacy Notice](https://www.jumio.com/legal-information/privacy-notices/online-services-notice/).”

</details>

---

<details>
<summary>Will a transaction be rejected if the consent parameters are not populated?</summary>

An end user should not be allowed to proceed with verification without providing consent. If a transaction is sent to Jumio without the required consent parameters, the transaction will be rejected.

</details>

---

<details>
<summary>Will Jumio review the implementation prior to deployment?</summary>

Yes, Jumio will ask you to submit a screenshot of the user journey to ensure the applicable language and checkbox (or other control) is included.

</details>

---

<details>
<summary>Will the consent language need to be presented before every transaction an end user initiates per customer?</summary>

Jumio requires direct consent from users each time they go through the journey in ID Verification or Identity Verification.

If you use Jumio Authentication, we require users to give direct consent the first time they authenticate. This consent is good for three years, after which you will need to request new consent from them.

</details>

## API Requirements

<details>
<summary>What type of consent parameters are required for the API?</summary>

If you are utilizing the Jumio API for data acquisition:

- Incorporate the required consent language (including a link to Jumio’s Privacy Notice) and a checkbox or similar active control into the user consent flow.
- Populate the IP address and end user's current location for each transaction.
- Populate the API consent parameters (i.e., consent, timestamp, IP address) for each transaction to confirm that consent has been granted to Jumio.

</details>

---

<details>
<summary>Where can I find the technical implementation documentation?</summary>

- See **[End-User Consent to Collect Personal Data](../API/end-user-consent)**.
- For older Netverify versions of the API (v2): **[Netverify ID Verification Web Implementation Guide](https://jumio.mcoutput.com/netverify/Content/Netverify/performNetverify%20Implementation.htm#end-user-consent-for-biometric-data-in-api)**.
- For older KYX versions of the API (v3): **[Implementation Guide KYX (v3)](https://jumio.mcoutput.com/v3/Content/v3/Introduction.htm#End-User_Consent_for_Biometric_Data)**.

</details>

---

## Custom UI Requirements

:::info
For customers using a custom UI with manual User Consent submission, the system ensures the consent is not older than three years. If the consent has expired, an error screen will appear.
:::

<details>
<summary>What type of consent parameters are required for the Custom UI SDK?</summary>

If you are utilizing the Jumio Custom UI SDK for data acquisition:

- Incorporate the required consent language (including the link to Jumio’s Privacy Notice) and checkbox or similar active control into the user consent flow.
- Initiate the Custom UI SDK as described in the technical documentation to receive applicable consent requirements for the transaction.
- Return a response containing the consent text, privacy notice URL, consent type, and consent status, as defined within the technical specifications, for each transaction to confirm that consent has been granted to Jumio.

</details>

---

<details>
<summary>Does it apply to all versions of the Custom UI SDK?</summary>

This is applicable for SDK versions **4.5 and above**.  
If you are using an SDK version earlier than 4.5, it will require an update to the latest version.

</details>

---

<details>
<summary>Where can I find the technical implementation documentation?</summary>

See the Integration Guide for your integration:

- **Android**: [Android Controller and Consent Handling](../SDKs/mobile-sdk/mobile-sdk-android-master/docs/integration_guide#consent-handling)
- **iOS**: [iOS Controller and Consent Handling](../SDKs/mobile-sdk/mobile-sdk-ios-master/docs/integration_guide#consent-handling)

</details>

---

# Best Practices

https://documentation.jumio.ai/docs/developer-resources/bestPractices/Overview_bestPractices

# Best Practices

- **Use the Health Check API** regularly to ensure Jumio services are operational before initiating transactions.
- **Provide feedback** on transactions when Jumio’s automated decision differs from your internal evaluation—this helps improve accuracy and flags discrepancies for review.
- Feedback enhances system learning and ensures alignment between Jumio outcomes and your business rules.

## 1.1 Environment Setup

- Maintain separate Development, Staging, and Production environments.
- Use unique API keys for each environment.
- Test extensively in staging before deploying to production.

## 1.2 Secure API Key & Credential Management

- Store API keys in secure locations (environment variables, secrets managers).
- Never expose API keys in client-side code.
- Rotate API keys periodically and revoke immediately if compromised.
- Restrict API key permissions to least privilege and limit usage to specific IPs/endpoints.

## 1.3 Network Security

- Enforce HTTPS for all API calls.
- Perform strict SSL/TLS verification.

## 1.4 Handling Network Errors, Timeouts & Retries

- Implement retry mechanisms with exponential backoff.
- Limit retry attempts and handle failures gracefully.
- Define request timeouts and inform users of delays.

## 1.5 Version Management & Updates

- Always use the latest stable API version.
- Monitor Jumio documentation for updates and deprecations.
- Test compatibility before upgrading.

---

# Health Check

https://documentation.jumio.ai/docs/developer-resources/bestPractices/health-check

# Health Check

Use this API to check the status of the Jumio services.

## HTTP Request Method

**GET**

- US: https://status.amer-1.jumio.ai
- EU: https://status.emea-1.jumio.ai
- SG: https://status.apac-1.jumio.ai

Health Status Request Example

```
> curl https://status.apac-1.jumio.ai
```

## Health Check Response

<details>
<summary>Response</summary>
| Field | Type | Note |
| --- | --- | --- |
| status | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details | object | Possible values:<br />- details.api<br />- details.callback<br />- details.mobile<br />- details.processing<br />- details.retrieval<br />- details.web |
| details.api | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details.callback | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details.mobile | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details.processing | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details.retrieval | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
| details.web | string | Possible values:<br />- UP<br />- DEGRADED<br />- DOWN |
</details>

### Response Examples

#### Status: UP

```
{"status":"UP","details":{}}
```

#### Status: DEGRADED

```
{
  "status":"DEGRADED",
  "details": {
    "mobile":"DEGRADED",
    "callback":"DEGRADED"
  }
}
```

#### Status: DOWN

```
{
  "status":"DEGRADED",
  "details": {
    "mobile":"DEGRADED",
    "callback":"DEGRADED"
  }
}
```

---

# Provide Feedback

https://documentation.jumio.ai/docs/developer-resources/bestPractices/provide-feedback

# Provide Feedback

After Jumio has processed a transaction, you can provide feedback on the decision automatically assigned by the workflow. If you believe a decision requires clarification or correction, you can assign a feedback status to the transaction and a reason for the feedback. When you provide such feedback, you are essentially tagging the transaction to note the discrepancy between the status assigned by Jumio and the status your organization has determined should be applied.

For transactions that evaluate an [ID credential](/docs/references/credentials/#id), providing feedback will affect subsequent transactions in your tenant, and all other tenants belonging to the same Jumio customer, that involve the same ID. The same ID is determined by matching criteria including:

- issuingCountry
- ID type
- documentNumber
- firstName
- lastName
- dateOfBirth

If the feedback status was:

**NOT_FRAUD:** If you mark an ID as **NOT_FRAUD**, any subsequent transaction with matching ID data will be approved by the lookup components such as,

- Data Lookup [Data Checks](/docs/references/capabilities/data-checks)
- Face Lookup ([Data Checks](/docs/references/capabilities/data-checks) + [Image Checks](/docs/references/capabilities/image-checks)) components.

Both lookup mechanisms incorporate customer feedback, so marking an ID as NOT_FRAUD directly influences these two components.  
However, **this does not override other independent fraud or data-quality checks** within the workflow. A transaction may still be rejected due to:

- MISMATCHING_DATAPOINTS
- ID_DATA_INVALID
- Or any other [Data Checks](/docs/references/capabilities/data-checks) or [Image Checks](/docs/references/capabilities/image-checks) that is **not part of the Lookup mechanisms**

This clarifies that NOT_FRAUD only affects Data Lookup and Face Lookup, while all other checks continue to operate independently.

**FRAUD:** For any subsequent transactions with a matching ID the transaction will be rejected. The Data Checks capability decision will be REJECTED and the decision details label will be CUSTOMER_FEEDBACK.

:::tip
The transaction feedback feature is an optional feature that Jumio customers may elect to use at their sole discretion. By using this feature you acknowledge and agree that Jumio relies on the information provided by you for this feature and that Jumio has no knowledge of the accuracy and correctness of such information.

Accordingly, you shall not use this feature for illegal, unethical, or discriminatory purposes, and you assume sole responsibility and liability for any consequences of your use of this feature. Jumio disclaims all liability for any harm or damage arising out of or in connection with your use of the Transaction Feedback feature.
:::

Jumio provides a Feedback API you can use to submit the feedback for a transaction. Use a PUT request to provide the feedback status and reason values. The request body is a JSON object.

## Feedback via Jumio Portal

You can submit feedback through the **Jumio Portal**, checkout [Transaction Feedback](../../portals/explorer/viewing-transaction-details#provide-feedback-on-a-transaction).

## Feedback Request Body Example

```
{
  "status": "FRAUD",
  "reason": "FIRST_PARTY_FRAUD"
}
```

## Feedback Request Fields

| Field  | Type   | Required | Notes                                                                                                                                                                                                                                                                                                                                                                                                |
| ------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status | string | yes      | The allowed status values are:<ul><li> **FRAUD**: Indicates that the ID data should be rejected in future transactions</li><li>**NOT_FRAUD**: Indicates that the ID data should be accepted in future transactions.</li><li>**NA**: Use this when you have previously submitted feedback for the same ID data but no longer want the previously set value to apply to future transactions.</li></ul> |
| reason | string | no       | The reason for setting the status value. A reason is required if the status value is FRAUD. Refer the table below.                                                                                                                                                                                                                                                                                   |

### Reason Values and Descriptions

| Reason                 | Description                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not_Available          | No reason provided. Select this option if you have already submitted a feedback reason but wish to remove it.                                                                                                  |
| Account_Takeover       | Unauthorized access to a user's account, often through hacking or stolen credentials.                                                                                                                          |
| Company_Policy         | Risks associated with non-compliance or violation of internal company policies and procedures.                                                                                                                 |
| First_Party_Fraud      | Deceptive activities where a legitimate account holder intentionally engages in fraud.                                                                                                                         |
| Government_Regulations | Risks arising from failure to comply with laws and regulations set by government authorities.                                                                                                                  |
| Identity_Fraud         | Unauthorized use of someone's personal information to commit fraudulent activities.                                                                                                                            |
| Insider_Fraud          | Fraudulent activities carried out by individuals within an organization, exploiting internal access.                                                                                                           |
| Money_Laundering       | Concealing the origins of illegally obtained money, often involving complex financial transactions.<br /> If this reason is provided the feedback will not influence subsequent transactions with the same ID. |
| Payment_Fraud          | Unauthorized or fraudulent transactions involving the use of payment methods.<br />If this reason is provided the feedback will not influence subsequent transactions with the same ID.                        |
| Phishing               | Fraudulent attempts to obtain sensitive information, such as usernames and passwords, by posing as a trustworthy entity.                                                                                       |
| Synthetic_ID_Fraud     | Creation of fictitious identities using a combination of real and fake information for fraudulent purposes.                                                                                                    |
| Third_Party_Fraud      | Fraudulent activities initiated by external entities not directly associated with the organization.                                                                                                            |

## Feedback in Transaction Details API Response

If you have provided feedback on a transaction the feedback is available in the [Workflow Details](/docs/developer-resources/retrieval#workflow-details) response. The response body will include a `feedback` key with a JSON object containing fields for the `status`, `reason`, and a `providedAt` timestamp.

```
  },
  "feedback": {
    "status": "FRAUD",
    "reason": "FIRST\_PARTY\_FRAUD",
	"providedAt": "2024-07-24T17:37:29.349Z"
  },
```

---

# Rate Limits

https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/rate-limits

# Rate Limits

Rate limits apply to a tenant. These API requests are governed by rate limits that protect the stability and performance of the system. The following are:

## Authorization Requests

The default rate limit for [authorization](../../API/authorization) requests for bearer tokens is 10 per second.

If the rate limit is reached a `HTTP 429 Too many requests` status code is returned.

## Account Requests

The default rate limit for Account requests that initiate a new transaction is one per second, per tenant. The system builds in some flexibility to accommodate higher bursts for short durations, and you can contact Jumio Support if you require higher burst rates than the defaults allow.

If the rate limit is reached a `HTTP 429 Too many requests` status code is returned, as shown in the following example:

```
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Request limit exceeded"
}
```

:::info
Jumio Netverify customers (created after March 2024) are subject to a default rate limit of 5 initiate requests per 5 seconds. Customers (created prior to March 2024) without an existing custom rate limit are subject to a default rate limit of 15 initiate requests per 5 seconds.
:::

## Retrieval Requests

The default rate limit for requests to retrieve transaction details is fifteen per second, per tenant.

:::info
For retrieval requests, customers created after March 2024 have a default rate limit of 75 requests every 5 seconds. Customers created before March 2024 have a higher default limit of 225 requests every 5 seconds.
:::

---

# API Endpoints

https://documentation.jumio.ai/docs/developer-resources/API/

# API Endpoints in Jumio

Jumio provides a set of REST API endpoints that enable seamless integration for account management, credential handling, data retrieval, and real-time status checks. Each endpoint is designed to support secure and efficient workflows for identity verification and related operations.

- **[Account API](https://documentation.jumio.ai/developer-resources/api/account)** – Manage account setup, updates, and configuration to control how Jumio services interact with your systems.

- **[Credentials API](https://documentation.jumio.ai/developer-resources/api/credentials)** – Handle secure creation, management, and rotation of API credentials for authentication.

- **[Retrieval API](https://documentation.jumio.ai/developer-resources/api/retrieval)** – Fetch identity verification results, images, and related data for completed transactions.

- **[Status Endpoint API](https://documentation.jumio.ai/developer-resources/api/status-endpoint)** – Get real-time updates on the processing status of identity verification requests.

- **[Aggregate API](https://documentation.jumio.ai/developer-resources/api/aggregateAPI)** - Provides a synchronous experience.

## REST APIs for Credential Acquisition

In addition to the REST APIs for Creating or Updating Accounts and Viewing or Retrieving Workflow Transactions that are used for all integration channels, Jumio provides REST APIs for:

- [Uploading Credentials](#uploading-credentials)
- [Workflow Finalization](#workflow-finalization) to execute the transaction workflow once the credentials have been uploaded.

:::tip
If you use the APIs to upload credentials to Jumio you must first obtain the end-user's consent on Jumio's behalf. See to [Collect Personal Data](/docs/developer-resources/API/end-user-consent) and [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).
:::

### Uploading Credentials

URLs with the correct path parameters and authorization bearer tokens for these APIs are available from the `workflowExecution:credentials` objects in the response from the account creation or update call, as shown in the following example:

```
{
  "timestamp": "2022-11-28T23:45:02.536Z",
  "account": {
    "id": "<ACCOUNT_ID>"
  },
  "web": {
    ...
  },
  "sdk": {
    ...
  },
  "workflowExecution": {
    "id": "<WORKFLOW_EXECUTION_ID>",
    "credentials": [
      {
        "id": "<CREDENTIAL_ID_1>",
        "category": "ID",
        "allowedChannels": [
          "WEB",
          "API",
          "SDK"
        ],
        "api": {
          "token": "<JWT_TOKEN>",
          "parts": {
            "front": "<FRONT_PART_URL>",
            "back": "<BACK_PART_URL>"
          },
          "workflowExecution": "<WORKFLOW_EXECUTION_URL>"
        }
      },
      {
        "id": "<CREDENTIAL_ID_2>",
        "category": "FACEMAP",
        "allowedChannels": [
          "WEB",
          "SDK"
        ]
      },
      {
        "id": "<CREDENTIAL_ID_3>",
        "category": "SELFIE",
        "allowedChannels": [
          "WEB",
          "API",
          "SDK"
        ],
        "api": {
          "token": "<JWT_TOKEN>",
          "parts": {
            "face": "<FACE_PART_URL>"
          },
          "workflowExecution": "<WORKFLOW_EXECUTION_URL>"
        }
      }
    ]
  }
}
```

| Credential Type                   | Minimum Resolution | Maximum Resolution | Additional Requirements                                                             |
| --------------------------------- | ------------------ | ------------------ | ----------------------------------------------------------------------------------- |
| **Document Image** (Front & Back) | 563 × 355 px       | 8000 × 8000 px     | The document in the image must be at least **512 px wide** and **323 px high**.     |
| **Selfie Image**                  | 480 × 640 px       | 8000 × 8000 px     | The face must be at least **320 px tall** and occupy at least **15%** of the image. |

For the complete API specification see: [Credentials and Finalization APIs](/docs/developer-resources/API/credentials).

## Uploading Prepared Data

Some workflows accept raw data values that identify the end user. Your integration needs to capture this data and upload it as a credential type called **Prepared Data**. The account response includes an object in the credentials array with a category of DATA and an api object with:

- A token value for authorizing the upload.
- A parts object with a prepared_data value that is the URL to upload the data.

Use a POST request and provide the values as a JSON. See the PREPARED_DATA endpoint [here](/docs/developer-resources/API/credentials#tag/Credentials).

### Example: Prepared Data Credential Object in Account Response

```
"credentials": [
  {
    "id": "e62dc87d-bc8a-4933-8ace-05acc3c8a379",
    "category": "DATA",
    "allowedChannels": [
      "API"
    ],
    "api": {
      "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOQ4CMQxA0bukxpIztmOHDlHRcoM4S8dSIMEIcXfC3ID26_136K_DI-xD1IjEiTQtbGEXSq2nNvuIWYh6g84ygBMqGBICC0fLtXlvG99wwahKlSC5T-LI4KQEKshuTQiXNvFz9H94Pfcx9WU93i73cl1_afuzpGicGhThPn9DMFsQSkZXZS8x1_D5AkAD7yrjAAAA.2qBHxwy43HMorgyrnL2AUOP_igbBNplBg8ZX9U-MeoPPek4mHTf_C4E9Ubbx4qehkyahdskiK1CCkLChrfqNpA",
      "parts": {
        "prepared_data": "https://api.amer-1.jumio.ai/api/v1/accounts/f19533ed-e45f-4607-8030-454189cdbed8/workflow-executions/a01773c3-6bb0-4b04-b373-7504b8d5302d/credentials/e62dc87d-bc8a-4933-8ace-05acc3c8a379/parts/PREPARED_DATA"
      },
      "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/f19533ed-e45f-4607-8030-454189cdbed8/workflow-executions/a01773c3-6bb0-4b04-b373-7504b8d5302d"
    }
  }
]
```

See also: [Capabilities Reference](../../references/capabilities/).

### Workflow Finalization

Once the required credentials are uploaded, you can call the finalization API to trigger the workflow execution.

If you are using the web client or mobile SDKs, the finalization call is made automatically once the required credentials have been received.

**Example Finalization Call**

```
curl --location --request PUT 'https://api.amer-1.jumio.ai/api/v1/accounts/3adef3f9-b892-4f9c-9b81-f16e5e87230d/workflow-executions/692701a5-eedc-45ca-adb6-213c2f3c7acc' \
--header 'Authorization: Bearer xxx'
```

For the complete API specification see: [Credentials API Reference](/docs/developer-resources/API/credentials).

---

# Account API

https://documentation.jumio.ai/developer-resources/api/account

Account API reference — create, update, and manage end-user accounts.

_OpenAPI specification — see the rendered reference at https://documentation.jumio.ai/developer-resources/api/account for the full schema._

---

# Credentials API

https://documentation.jumio.ai/developer-resources/api/credentials

Credentials API reference — manage credential references attached to accounts.

_OpenAPI specification — see the rendered reference at https://documentation.jumio.ai/developer-resources/api/credentials for the full schema._

---

# Retrieval API

https://documentation.jumio.ai/developer-resources/api/retrieval

Retrieval API reference — fetch transaction results and supporting data.

_OpenAPI specification — see the rendered reference at https://documentation.jumio.ai/developer-resources/api/retrieval for the full schema._

---

# Status Endpoint

https://documentation.jumio.ai/developer-resources/api/status-endpoint

Status endpoint reference — health and availability checks.

_OpenAPI specification — see the rendered reference at https://documentation.jumio.ai/developer-resources/api/status-endpoint for the full schema._

---

# Aggregate API

https://documentation.jumio.ai/developer-resources/api/aggregateAPI

Aggregate API reference — combined orchestration endpoints.

_OpenAPI specification — see the rendered reference at https://documentation.jumio.ai/developer-resources/api/aggregateAPI for the full schema._

---

# SDK Reference

https://documentation.jumio.ai/docs/developer-resources/SDKs/Overview_of_SDKs

# Jumio SDKs

Jumio offers a set of powerful SDKs to help you seamlessly integrate identity verification and biometric workflows into your applications. These SDKs are designed to be flexible, secure, and easy to implement, whether you're working on a web platform or mobile apps.

## Web SDK

The [Jumio Web SDK](https://documentation.jumio.ai/docs/developer-resources/SDKs/web-sdk/introduction-web) provides a fully functional default implementation out of the box, making it easy to get started quickly. It also includes robust options for customization and extension, allowing you to tailor the user experience to fit your brand and workflow needs. You can:

- Customize the look and feel to match your design system.
- Control the flow and steps of the verification journey.
- Integrate with your backend services to handle callbacks and token management.

## Mobile SDKs

Jumio provides dedicated Mobile SDKs for [iOS](https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/README_iOS) and [Android](https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/README_Android), allowing you to embed the verification experience directly into your native apps. These SDKs offer:

- A complete, ready-to-use default implementation of the verification journey.
- A responsive and intuitive UI optimized for mobile platforms.
- Extensive customization options, including custom themes, localization, and flow control.
- Support for offline scenarios and device capability checks.

The [mobile SDKs](https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile) are ideal for delivering a smooth, app-native experience with minimal setup, while still offering the flexibility to deeply customize the process as needed.

## Maintenance and Support

For details on SDK versioning, deprecation timelines, and compatibility guarantees, refer to the [SDK Maintenance and Support Policy](https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/maintenance_policy). This document outlines how Jumio maintains and supports its SDKs across platforms to ensure stability and security.

---

# Mobile SDKs

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile

# Mobile SDKs

Jumio provides mobile SDKs to support integrations on mobile devices. The SDKs and documentation are available from GitHub, and include example applications.

- [Native iOS SDK](../mobile-sdk/mobile-sdk-ios-master/README_iOS)
- [Native Android SDK](../mobile-sdk/mobile-sdk-android-master/README_Android)
- [React Native Plugin](../crossplatform/mobile-react-master/README_React)
- [Flutter Plugin](../crossplatform/mobile-flutter-master/README_Flutter)
- [Apache Cordova Plugin](../crossplatform/mobile-cordova-master/README_Cordova)

The authorization token to initialize the SDK is available from the sdk:token value of the response from the account creation or update call, as shown in the following example:

Example SDK Token

```

{
   "timestamp": "2022-11-28T23:45:02.536Z",
   "account": {
      "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
   },
   "web": {
      ...
    },
   "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
    },
```

---

# Native Android SDK

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/README_Android

![Header Graphic](./docs/images/jumio_feature_graphic.jpg)

<div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
  <a href="#release-notes">
    <img src="https://img.shields.io/github/v/release/Jumio/mobile-sdk-android?style=flat" alt="Version" />
  </a>
  <a href="https://jumio.github.io/mobile-sdk-android/">
    <img src="https://img.shields.io/github/v/release/Jumio/mobile-sdk-android?label=API%20doc&color=green&style=flat" alt="API Doc" />
  </a>
  <a href="#copyright">
    <img src="https://img.shields.io/badge/license-commercial-3D3D3D?style=flat" alt="License" />
  </a>
  <a href="#general-requirements">
    <img src="https://img.shields.io/badge/platform-Android-lightgrey?style=flat" alt="Platform" />
  </a>
  <a href="#general-requirements">
    <img src="https://img.shields.io/badge/API%20level-24+-orange?style=flat" alt="API Level" />
  </a>
  <a href="#integration">
    <img src="https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Frepo.mobile.jumio.ai%2Fcom%2Fjumio%2Fandroid%2Fcore%2Fmaven-metadata.xml?style=flat" alt="Maven" />
  </a>
</div>

# Overview

The Jumio Software Development Kit (SDK) provides you with a set of tools and UIs (default or custom) to develop an Android application perfectly fitted to your specific needs.

Onboard new users and easily verify their digital identities by making sure the IDs they provide are valid and authentic. Extract data from ID documents completely automatically and within seconds. Confirm that users really are who they say they are by having them take a quick selfie and match it to their respective documents. Jumio uses cutting-edge biometric technology to make sure there is an actual, real-life person in front of the screen.

![SDK Overview](docs/images/images_overview/overview_android_4.9.0.png)

Using the Jumio SDK will allow you to create the best possible solution for your individual needs, providing you with a range of different services to choose from.

---

## Get Started

Please note that [basic setup](#basics) is required before continuing with the integration of any of the following services.

### Jumio SDK Integration

Jumio KYX platform and related services are a secure and easy solution that allows you to establish the genuine identity of your users in your mobile application, by verifying their passports, government-issued IDs and actual liveness in real-time. Very user-friendly and highly customizable, it makes onboarding new customers quick and simple.

:arrow_right:&nbsp;&nbsp;[SDK INTEGRATION GUIDE](docs/integration_guide.md)
:arrow_right:&nbsp;&nbsp;[Changelog](docs/changelog.md)
:arrow_right:&nbsp;&nbsp;[Transition Guide](docs/transition_guide.md)

#### Previous SDK Versions

If you need information on older SDK versions, please refer to:

- [3.9.2](https://github.com/Jumio/mobile-sdk-android/tree/v3.9.2)
- [3.9.1](https://github.com/Jumio/mobile-sdk-android/tree/v3.9.1)
- [3.9.0](https://github.com/Jumio/mobile-sdk-android/tree/v3.9.0)

### Code Documentation

Full API documentation for the Jumio Android SDK can be found [here](https://jumio.github.io/mobile-sdk-android).

### FAQ

Link to Jumio Android SDK FAQ can be found [here](docs/integration_faq.md).

### Known Issues

List of known issues can be found [here](docs/known_issues.md).

---

## Quickstart

This section provides a quick overview on how to get started with the [Android sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample) that can be found here on Github. You will need a **commercial Jumio License** to successfully run any of our examples; for details, contact (sales@jumio.com). You will also need an up-to-date Android Studio version to open and try out the sample project.

Start by downloading the [Android sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample) from the Jumio Github repo. You can either clone the repository (using SSH or HTTPS) to your local device or simply download everything as a ZIP.

Once you’ve got the sample application downloaded and unzipped, open Android Studio. Choose **Import project** and navigate to where you’ve saved your sample application. Select the **JumioMobileSample folder** and open it.

Android Studio will now start to import the project. This might take a bit of time. Make sure to wait until the Gradle Build has finished and the application is properly installed!

The Android sample application contains the package `com.jumio.sample`, which consists of:

- `MainActivity.kt`
- `xml/`
  - `CustomUIActivity.kt`
  - `adapter/`
    - `CustomConsentAdapter.kt`
    - `CustomCountryAdapter.kt`
    - `CustomDocumentAdapter.kt`

To use the Jumio Sample Application you need an SDK Token. If you haven't done so already, please refer to the [Authentication and Encryption section](#authentication-and-encryption) for more details on how to obtain your SDK token.
To add your individual SDK token to the application copy/paste it to the token input field once the application is started.

**Note:** We strongly recommend not storing any credentials inside your app! We suggest loading them during runtime from your server-side implementation.

Once you start up the sample application, you'll be given the option of trying out the Jumio SDK. The sample application needs camera permissions, which will be prompted for automatically once you try to start the SDK via one of the buttons. If you deny camera permissions, you won't be able to use the SDK.

---

## Basics

### General Requirements

The minimum requirements for the SDK are:

- Android 7.0 "Nougat" (API level 24) or higher
- AGP version 8.10.1 or higher
- Gradle version 8.11.1 or higher
- Internet connection
- Jumio KYX

:::note

- SDK 4.17.0 will be the last SDK version supporting Android 6 (API level 23). All subsequent SDK versions will require at least Android 7.0 "Marshmallow" (API level 24).
- SDK 4.14.0 will be the last SDK version supporting Android 5 (API level 21). All subsequent SDK versions will require at least Android 6.0 "Marshmallow" (API level 23).
- Starting with SDK 4.9.0 the minimum required compile SDK version is 34. Also Gradle 8 is **required** to build the SDK!
:::

The following architectures are supported in the SDK:

- ARMv7 processor with Neon
- ARM64-v8a

:::note
Currently, x86 and x86_64 are _not_ supported. You get an _UnsatisfiedLinkError_ if app and CPU architecture do not match or the CPU architecture is not supported.
:::

You will need a **commercial Jumio License** to run any of our examples. For details, contact sales@jumio.com.

### Authentication and Encryption

:::note
**As of version 4.0.0 and onward, the SDK can only be used in combination with Jumio KYX. API v2 as well as using API token and secret to authenticate against the SDK will no longer be compatible.**
:::

Before starting a session in our SDK, an SDK token has to be obtained. Please refer to out [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/Integration_Intro) for further details. To authenticate against the API calls, an OAuth2 access token needs to be retrieved from the Jumio Portal.

Within the response of the [Account Creation or Account Update](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) API, a SDK token is returned, which needs to be applied to initiate the mobile SDK.

#### Authentication with OAuth2

Your OAuth2 credentials are constructed using your API token as the Client ID and your API secret as the Client secret. You can view and manage your API token and secret in the Jumio Portal under:

- **Settings > API credentials > OAuth2 Clients**

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation.

##### Access Token URL (OAuth2)

- US: `https://auth.amer-1.jumio.ai/oauth2/token`
- EU: `https://auth.emea-1.jumio.ai/oauth2/token`
- SG: `https://auth.apac-1.jumio.ai/oauth2/token`

The [TLS Protocol](https://tools.ietf.org/html/rfc5246) is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [supported cipher suites](https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites#supported-cipher-suites).

:::note
Calls with missing, incorrect or suspicious headers or parameter values will result in HTTP status code **400 Bad Request Error** or **403 Forbidden**.
:::

##### Request Access Token (OAuth2)

```bash
curl --request POST --location 'https://auth.amer-1.jumio.ai/oauth2/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-raw 'grant_type=client_credentials' \
    --basic --user CLIENT_ID:CLIENT_SECRET
```

##### Response Access Token (OAuth2)

```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

##### Access Token Timeout (OAuth2)

Your OAuth2 access token is valid for 60 minutes. After the token lifetime is expired, it is necessary to generate a new access token.

#### Workflow Transaction Token Timeout

The token lifetime is set to 30 minutes per default. It can be configured via the [Jumio Portal](https://documentation.jumio.ai/docs/portals/settings/aboutIDVSettings) and can be overwritten using the API call (`tokenLifetime`). Within this token lifetime the token can be used to initialize the SDK.

As soon as the workflow (transaction) starts, a 15 minutes session timeout is triggered. For each action performed (capture image, upload image) the session timeout will reset, and the 15 minutes will start again.

After creating/updating a new account you will receive a `sdk.token` (JWT) for initializing the SDK. Use this SDK token with your Android code:

```kotlin
sdk = JumioSDK(context: Context).apply {
  token = "YOUR_SDK_TOKEN"
  dataCenter = "YOUR_DATACENTER"
}
```

### Permissions

The following permission is optional:

```xml
<uses-permission android:name="android.permission.VIBRATE"/>
```

:::note
On devices running Android Marshmallow (6.0) and above, you need to acquire `android.permissions.CAMERA` dynamically before initializing the SDK.
:::

Use `JumioSDK.hasAllRequiredPermissions(context: Context)` to make sure the Jumio SDK has all required permissions. In case this method returns `false`, use the method `JumioSDK.getMissingPermissions(context: Context)`, which will return an array list containing String values of all missing permissions. Request any missing permissions using the `ActivityCompat.requestPermissions()` method.

### Integration

Use the SDK in your application by including the Maven repositories with the following `build.gradle` configuration in Android Studio:

```groovy
repositories {
	google()
	mavenCentral()
	exclusiveContent {
		forRepository {
			maven {
				url 'https://repo.mobile.jumio.ai'
			}
		}
		filter {
			includeGroup "com.jumio.android"
		}
	}
}
```

Check the Android Studio [sample projects](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/) to learn the most common use.

### Proguard

The Proguard settings should be applied automatically as they are defined as consumer Proguard rules within the SDK. The current rules can also be found in the [Sample app](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/proguard-rules.pro).

#### Mandatory

The following Proguard Keep rules have to be added to the application hosting the Jumio Android SDK:

```text
# Jumio
-keep class com.jumio.** { *; }
-keep class jumio.** { *; }
```

#### Optional

The following Proguard Keep rules have to be added to the application hosting the Jumio Android SDK if the corresponding dependencies have been added:

```text
# Tensorflow
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**

# JMRTD
-keep class org.jmrtd.** { *; }
-keep class net.sf.scuba.** { *; }
-keep class org.bouncycastle.** { *; }
-keep class org.ejbca.** { *; }
-dontwarn java.nio.**
-dontwarn org.codehaus.**
-dontwarn org.ejbca.**
-dontwarn org.bouncycastle.**
-dontwarn module-info

# Dynamic Delivery Module
-keepclassmembers class com.google.android.play.core.splitinstall.SplitInstallHelper {
  *** loadLibrary(android.content.Context,java.lang.String);
}

-keep,includedescriptorclasses class com.jumio.ale.swig.** {
  *** swigDirectorDisconnect();
}
```

#### Dexguard

There might be additional rules necessary in case Dexguard is used:

```text
# SplitInstallHelper
	-loadslibrary com.google.android.play.core.splitinstall.SplitInstallHelper cpuinfo
	-loadslibrary com.google.android.play.core.splitinstall.SplitInstallHelper aleInterface

# Keep native resources
	-keepresourcefiles **/libcpuinfo.so
	-keepresourcefiles **/libaleInterface.so
	-keepresourcefiles **/libyuv_android.so
	-keepresourcefiles **/libtensorflowlite_jni.so
```

#### R8 Full Mode

For information regarding R8 `fullMode`, please refer to our FAQ section [here](docs/integration_faq.md#r8-full-mode).

### Language Localization

Our SDK supports [default Android localization features](https://developer.android.com/training/basics/supporting-devices/languages.html) for different languages. All label texts and button titles in the SDK can be changed and localized by adding the required Strings you want to change in a `strings.xml` file in a `values` directory for the language and culture preference that you want to support. You can check out strings that are modifiable [within our Sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml).

Jumio SDK products support the following languages:

_Afrikaans, Arabic, Bulgarian, Burmese, Chinese (Simplified), Chinese (Traditional), Croatian, Czech, Danish, Dutch, Estonian, English, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Khmer, Korean, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese, Portuguese (Brazil), Romanian, Russian, Serbian (Cyrillic), Serbian (Latin), Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese, Zulu_

Our SDK supports accessibility features. Visually impaired users can now enable **TalkBack** or increase the **text size** on their device. The accessibility strings that are used by TalkBack contain _accessibility_ in their key and can be also modified in `strings.xml`.

## ML Models

The Jumio SDK utilizes ML Models to enable client-/server-side verification.

Required models can be provided by downloading and adding them manually to the bundle or preloading them. The SDK will load them on demand if none of the previous is applied.

Loading the models in advance will improve startup time of the SDK.

For more details, please refer to our [integration guide](docs/integration_guide.md#ml-models).

## Document Verification

As of Android SDK 4.3.0, Document Verification functionality is available.
This functionality allows users to submit a number of different document types (e.g. a utility bill or bank statement) in digital form and verify the validity and authenticity of this document.

Documents can be submitted using one of two ways: Taking a photo of the document or uploading a PDF file.
For more details, please refer to our [integration guide](docs/integration_guide.md#jumio-document-credential).

#### Supported Documents:

- BC (Birth certificate)
- BS (Bank statement)
- CAAP (Cash advance application)
- CB (Council bill)
- CC (Credit card)
- CCS (Credit card statement)
- CRC (Corporate resolution certificate)
- CUSTOM
- HCC (Health care card)
- IC (Insurance card)
- LAG (Lease agreement)
- LOAP (Loan application)
- MEDC (Medicare card)
- MOAP (Mortgage application)
- PB (Phone bill)
- SEL (School enrollment letter)
- SENC (Seniors card)
- SS (Superannuation statement)
- SSC (Social security card)
- STUC (Student card)
- TAC (Trade association card)
- TR (Tax return)
- UB (Utility bill)
- VC (Voided check)
- VT (Vehicle title)
- WWCC (Working with children check)

:::note
To enable the use of this feature, please contact [Jumio support](https://support.jumio.com).
:::

## Digital Identity

As of Jumio Android SDK 4.5.0, users may use their Digital Identity to verify their identity.
For now 'ID by Mastercard' is the only Digital Identity provider currently supported by our SDK.

If you want to enable Digital Identity verification for your account please [contact us](https://support.jumio.com).
In case you are already set up to use Digital Identity verification within your app, check out the integration steps explained [here](docs/integration_guide.md#digital-identity-did).

## Analytics With Datadog

Analytic feedback and diagnostics enable us to continually improve our SDK and its performance, as well as investigate potential issues. With the Jumio SDK, we use [Datadog](https://github.com/DataDog/dd-sdk-android) as an optional tool to collect diagnostic information. Data collected includes specific SDK information like version numbers, started and finished SDK instances and scan workflows, thrown exceptions and error information, as well as other mobile events. Please note that gathering analytics data requires user consent due to legal regulations such as GDPR. The consent is granted when our MLA is accepted.

To benefit from Datadog, add the following dependency to your `build.gradle` file:

```groovy
implementation "com.jumio.android:datadog:${SDK_VERSION}"
```

:::note
Datadog has been removed in SDK 4.13.0.
:::

---

## Security

All SDK related traffic is sent over HTTPS using TLS and public key pinning. Additionally, the information itself within the transmission is also encrypted utilizing **Application Layer Encryption** (ALE). ALE is a Jumio custom-designed security protocol that utilizes RSA-OAEP and AES-256 to ensure that the data cannot be read or manipulated even if the traffic was captured.

---

## Release Notes

See our [Change Log](docs/changelog.md) for more information about our current SDK version and further details.

## Maintenance and Support

Please refer to our [SDK maintenance and support policy](docs/maintenance_policy.md) for more information about Mobile SDK maintenance and support.

### Two-factor Authentication

If you want to enable two-factor authentication for your Jumio Portal, [contact us](https://support.jumio.com). Once enabled, users will be guided through the setup upon their first login to obtain a security code using the Google Authenticator app.

### Licenses
The source code and software available on this website (“Software”) is provided by Jumio Corp. or its affiliated group companies (“Jumio”) "as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Jumio be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services, loss of use, data, profits, or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this Software, even if advised of the possibility of such damage.

In any case, your use of this Software is subject to the terms and conditions that apply to your contractual relationship with Jumio. As regards Jumio’s privacy practices, please see our privacy notice available here: [Privacy Policy](https://www.jumio.com/privacy-center/privacy-notices/online-services-notice/).

The software contains third-party open source software. For more information, see [licenses](licenses).

This software is based in part on the work of the Independent JPEG Group.

### Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com. The [Jumio online helpdesk](https://support.jumio.com) contains a wealth of information regarding our services including demo videos, product descriptions, FAQs, and other resources that can help to get you started with Jumio.

### Copyright

&copy; Jumio Corporation, 100 Mathilda Place Suite 100 Sunnyvale, CA 94086

---

# Integration Guide

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/integration_guide

![Header Graphic](images/jumio_feature_graphic.jpg)

# Integration Guide for Android SDK

Jumio’s products allow businesses to establish the genuine identity of their users by verifying government-issued IDs in real-time. ID Verification, Selfie Verification and other services are used by financial service organizations and other leading brands to create trust for safe onboarding, money transfers and user authentication.

## Release Notes

Please refer to our [Change Log](changelog.md) for more information. Current SDK version: **4.18.0**

For technical changes that should be considered when updating the SDK, please read our [Transition Guide](transition_guide.md).

## Code Documentation

Full API documentation for the Jumio Android SDK can be found [here](https://jumio.github.io/mobile-sdk-android/).

## Setup

The [basic setup](../README_Android.md#basics) is required before continuing with the following setup for the Jumio SDK. If you are updating your SDK to a newer version, please also refer to:

:arrow_right:&nbsp;&nbsp;[Changelog](changelog.md)  
:arrow_right:&nbsp;&nbsp;[Transition Guide](transition_guide.md)

### Dependencies

The [SDK Setup Tool](https://jumio.github.io/mobile-configuration-tool/out/) is a web tool that helps determine available product combinations and corresponding dependencies for the Jumio SDK, as well as an export feature to easily import the applied changes straight into your codebase.

[![Jumio Setup](images/setup_tool.png)](https://jumio.github.io/mobile-configuration-tool/out/)

Below you can find a list of dependencies that can be added to your application to enable different functionality of the Jumio SDK. Some modules are mandatory, others are optional.

If an optional module is **not linked**, some functionalities may not be available, but the library size will be reduced. The [Sample app](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/) apk size is currently around **12.21 MB**.

```groovy
// [Mandatory] Jumio Core library
dependencies {
	implementation "com.jumio.android:core:4.18.0"
	...
}

// [Optional] Extraction methods
dependencies {
	implementation "com.jumio.android:docfinder:4.18.0"          // Autocapture library, includes all previous scanning methods
	implementation "com.jumio.android:barcode-mlkit:4.18.0"      // Barcode scanning library, assists Autocapture
	implementation "com.jumio.android:nfc:4.18.0"                // NFC scanning library, assists Autocapture
	implementation "com.jumio.android:liveness:4.18.0"           // Face Liveness library
	implementation "com.jumio.android:digital-identity:4.18.0"   // Digital Identity verification library
  	...
}

// [Optional] Jumio Default UI
dependencies {
	implementation "com.jumio.android:defaultui:4.18.0"
	...
}

// [Optional] Additional functionality
dependencies {
	implementation "com.jumio.android:camerax:4.18.0"         // CameraX library
  	...
}
```

In addition to specifying individual dependencies, you can also use a BOM (Bill of Materials) to manage all the dependency versions at once. By using BOM, you ensure that all the dependencies are automatically aligned to the correct versions, reducing the need to manually update version numbers across your dependencies.

```groovy
dependencies {
		implementation platform("com.jumio.android:bom:4.18.0")
		implementation "com.jumio.android:core"
		implementation "com.jumio.android:barcode-mlkit"
		implementation "com.jumio.android:camerax"
		implementation "com.jumio.android:defaultui"
		implementation "com.jumio.android:digital-identity"
		implementation "com.jumio.android:docfinder"
		implementation "com.jumio.android:liveness"
		implementation "com.jumio.android:nfc"
}
```

#### Autocapture

The module `com.jumio.android:docfinder` offers one generic scanning method across all ID documents, providing a more seamless capture experience for the end user. The SDK will automatically detect which type of ID document is presented by the user and guide them through the capturing process with live feedback.
The models can be bundled with the app directly to save time on the download during the SDK runtime. Please see section [ML Models](#ml-models) for more information.

#### Certified Face Liveness

Jumio uses Certified Liveness technology to determine liveness. Link `com.jumio.android:liveness` module in order to use Jumio Liveness.
Please note: `com.jumio.android:camerax` will be linked transitively when `com.jumio.android:liveness` is linked.

#### Barcode Scanning

In order to benefit from barcode scanning functionality included in the `com.jumio.android:docfinder` dependency, please add `com.jumio.android:barcode-mlkit` to your `build-gradle` file.

This dependency includes `com.google.android.gms:play-services-mlkit-barcode-scanning` library - if your application includes **other Google ML-kit libraries**, it might be necessary to override meta-data specified in the application tag of the `play-services-mlkit-barcode-scanning` manifest by [merging multiple manifests](https://developer.android.com/studio/build/manage-manifests#merge-manifests):

```xml
<meta-data
  android:name="com.google.android.gms.vision.DEPENDENCIES"
  android:value="barcode"
  tools:replace="android:value" />
```

#### NFC Scanning

In order to benefit from NFC scanning functionality included in the `com.jumio.android:docfinder` dependency, please add `com.jumio.android:nfc` to your `build-gradle` file.

### SDK Version Check

Use `JumioSDK.sdkVersion` to check which SDK version is being used.

### Root Detection

For security reasons, applications implementing the SDK should not run on rooted devices. Use either the below method or a self-devised check to prevent usage of SDK scanning functionality on rooted devices.

```kotlin
JumioSDK.isRooted(context: Context)
```

:::note
Please be aware that the JumioSDK root check uses various mechanisms for detection, but doesn't guarantee to detect 100% of all rooted devices.
:::

### Device Supported Check

Use the method below to check if the current device platform is supported by the SDK.

```kotlin
JumioSDK.isSupportedPlatform(context: Context)
```

### Privacy Notice

If you submit your app to the Google Play Store a [Prominent Disclosure](https://support.google.com/googleplay/android-developer/answer/11150561) explaining the collected [User Data](https://support.google.com/googleplay/android-developer/answer/10144311) is required. The collected user data also needs to be declared in your [Data Safety Form](https://play.google.com/console/developers/app/app-content/data-privacy-security) and the [Privacy Policy](https://play.google.com/console/developers/app/app-content/privacy-policy) related to your application.

Other stores might require something similar - please check before submitting your app to the store.

Please see the [Jumio Privacy Policy for Online Services](https://www.jumio.com/legal-information/privacy-notices/jumio-corp-privacy-policy-for-online-services/) for further information.

### Digital Identity (DID)

In case Digital Identity Verification has been enabled for your account you can add the `com.jumio.android:digital-identity` dependency to your application. This will enable you to make use of DID verification within the SDK.

Over the course of DID verification the SDK will launch an according third party application representing your Digital Identity. Communication between both applications (your integrating application and the Digital Identity application) is done via a so-called "deep link". For more information on deep link handling on Android please check out their [official guide](https://developer.android.com/training/app-links).

#### Deep Link Setup

To enable your app specific deep link, our support team has to setup an according scheme of your choice for you. This scheme will be used by the SDK to identify your application while returning from the DID provider's application. For the scheme basically any string can be used, however it is recommended that it is unique to your application in some way. A suggestion would be your company name.

Following snippet shows how the deep link needs to be setup in your application's `AndroidManifest.xml` file:

```xml
<activity
	android:name="com.jumio.app.HostingActivity"
	android:exported="true"
	android:launchMode="singleTask"
	android:theme="@style/Theme.Jumio">
	<intent-filter>
		<action android:name="android.intent.action.VIEW" />

		<category android:name="android.intent.category.DEFAULT" />
		<category android:name="android.intent.category.BROWSABLE" />

		<data android:scheme="&lt;your-app-scheme&gt;" />
	</intent-filter>
</activity>
```

Please note that the properties `android:exported="true"` and `android:launchMode="singleTask"` need to be specified as well. The first parameter basically tells the Android system that your `Activity` can be found by the system and other applications. By specifying `launchMode="singleTask"` any already running task for this `Activity` will be resumed (instead of creating a new instance). Both are requirements so that the SDK can handle the according deep link correctly.

In case you are using Jumio's Default UI in your app (see section [Default UI](#default-ui)) you also need to specify `tools:replace="android:exported"` to `JumioActivity`'s `<activity>` tag like so:

```xml
<activity
	android:name="com.jumio.defaultui.JumioActivity"
	android:exported="true"
	android:launchMode="singleTask"
	tools:replace="android:exported">
	<intent-filter>
		...
	</intent-filter>
</activity>
```

As deep link handling happens on `Activity` level, the according data needs to be forwarded to the SDK via `Activity.onNewIntent()`. The following code snippet shows how this can be achieved. **If you're using Jumio's Default UI you can ignore this step**.

```kotlin
override fun onNewIntent(intent: Intent) {
	super.onNewIntent(intent)

	intent.data?.let { deepLink ->
		val activeScanPart = scanPart ?: return

		JumioDeepLinkHandler.consumeForScanPart(deepLink, activeScanPart)
	}
}
```

### Risk Signal: Device Risk

If you want to include risk signals into your application, please check our [Risk Signal guide](https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRisk).

#### Iovation setup

To integrate the device risk vendor Iovation into your application, please follow the [Iovation integration guide](https://github.com/iovation/deviceprint-SDK-android).

#### API call

To provide Jumio with the generated Device Risk blackbox, please follow the [Device Risk API guide](https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRiskwithRestAPI).

## ML Models

By default, required models get downloaded by the SDK if not provided via the assets folder or preloaded.

### Bundling models in the app

You can download our encrypted models and add them to your assets folder for the following modules.

:::warning
Make sure not to alter the downloaded models (name or content) before adding them to your assets folder.
:::

#### DocFinder

If you are using the `com.jumio.android:docfinder` module, find the required models [here](https://cdn.mobile.jumio.ai/android/model/normalized_ensemble_passports_v2_float16_quant.enc) and [here](https://cdn.mobile.jumio.ai/android/model/mobile-classifier-model-1.0.0.enc).

#### Liveness

If you are using the `com.jumio.android:liveness` module, find the required model [here](https://cdn.mobile.jumio.ai/android/model/liveness_sdk_assets_v_1_1_5.enc).

### Preloading models

In version `4.9.0` we introduced the [`JumioPreloader`][jumiopreloader]. It provides functionality to preload models without the JumioSDK being initialized. To do so call:

```kotlin
with(JumioPreloader) {
	init(`<Your Context>`) // init with Context
	preloadIfNeeded()
}
```

The [`JumioPreloader`][jumiopreloader] will identify which models are required based on your configuration.

Preloaded models are cached so they will not be downloaded again. To clean the models call:

```kotlin
with(JumioPreloader) {
	init(`<Your Context>`) // init with Context
	clean()
}
```

:::warning
`clean` should never be called while the SDK is running!
:::

To get notified that preloading has finished, you can implement [`JumioPreloadCallback`][jumiopreloadcallback] methods and set the callback as follows:

```kotlin
with(JumioPreloader) {
	init(`<Your Context>`) // init with Context
	setCallback(`<Your callback>`)
	...
	// followed by preloadIfNeeded() for example
}
```

## Initialization

### Requesting a Token (via OAuth2)

Your OAuth2 credentials are constructed using your API token as the Client ID and your API secret as the Client secret. You can view and manage your Client ID and secret in the Jumio Portal under:

- **Settings &lt; API credentials &lt; OAuth2 Clients**

Client ID and Client secret are used to generate an OAuth2 access token. Send a workflow request using the acquired OAuth2 access token to receive the SDK token necessary to initialize the Jumio SDK.

OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation. For more details, please refer to [Authentication and Encryption](../README_Android.md#authentication-and-encryption).

### Initializing the Jumio SDK

Use your acquired SDK token and your according datacenter to initialize the `JumioSDK`:

```kotlin
const val YOUR_SDK_TOKEN = ""
const val YOUR_DATACENTER = ""

val context: Context = ...
sdk = JumioSDK(context).apply {
	token = "YOUR_SDK_TOKEN"
	datacenter = "YOUR_DATACENTER"
}
```

Data center is set to `"US"` by default. If your customer account is in the EU data center, use `"EU"` instead. Alternatively, use `"SG"` for Singapore.

:::tip
We strongly recommend storing all credentials outside of your app! We suggest loading them during runtime from your server-side implementation.
:::

## Configuration

Every Jumio SDK instance is initialized using a specific [`sdk.token`][token]. This token contains information about the workflow, credentials, transaction identifiers and other parameters. Configuration of this token allows you to provide your own internal tracking information for the user and their transaction, specify what user information is captured and by which method, as well as preset options to enhance the user journey. Values configured within the [`sdk.token`][token] during your API request will override any corresponding settings configured in the Jumio Portal.

### Workflow Selection

Use ID verification callback to receive a verification status and verified data positions (see [Callback section](https://documentation.jumio.ai/docs/developer-resources/callback)). Make sure that your customer account is enabled to use this feature. A callback URL can be specified for individual transactions (for URL constraints see chapter **Jumio Callback IP Addresses**). This setting overrides any callback URL you have set in the Jumio Portal. Your callback URL must not contain sensitive data like PII (Personally Identifiable Information) or account login. Set your callback URL using the `callbackUrl` parameter.

Use the correct [workflow definition key](https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/standardServices) in order to request a specific workflow. Set your key using the `workflowDefinition.key` parameter.

```json
{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": "X"
  },
  "callbackUrl": "YOUR_CALLBACK_URL"
}
```

For more details, please refer to our [Workflow Description Guide](https://support.jumio.com/hc/en-us/articles/4408958923803-KYX-Workflows-User-Guide).

:::note
Selfie Verification requires portrait orientation in your app.
:::

### Transaction Identifiers

There are several options in order to uniquely identify specific transactions. `customerInternalReference` allows you to specify your own unique identifier for a certain scan (max. 100 characters). Use `reportingCriteria`, to identify the scan in your reports (max. 100 characters). You can also set a unique identifier for each user using `userReference` (max. 100 characters).

For more details, please refer to the **Account Request** section in our [KYX Guide](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).

```json
{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": "X"
  },
  "reportingCriteria": "YOUR_REPORTING_CRITERIA",
  "userReference": "YOUR_USER_REFERENCE"
}
```

:::note
Transaction identifiers must not contain sensitive data like PII (Personally Identifiable Information) or account login.
:::

### Preselection

You can specify issuing country using [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country codes, as well as ID types to skip selection during the scanning process. In the example down below, Austria ("AUT") and the USA ("USA") have been preselected. PASSPORT and DRIVER_LICENSE have been chosen as preselected document types. If all parameters are preselected and valid and there is only one given combination (one country and one document type), the document selection screen in the SDK can be skipped entirely.

For more details, please refer to the **Account Request** section in our [KYX Guide](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).

```json
{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
	"key": X,
	"credentials": [
	  {
		"category": "ID",
		"type": {
		  "values": [
			"DRIVING_LICENSE",
			"PASSPORT"
		  ]
		},
		"country": {
		  "values": [
			"AUT",
			"USA"
		  ]
		}
	  }
	]
  }
}
```

Digital Identity documents can also be preselected by specifying `"DIGITAL_IDENTITY"` as the type. To narrow down to a specific digital identity subtype, use the optional `"subType"` field with a single value. Supported subtypes are: `EIDAS`, `DIGITAL_DRIVING_LICENSE_PDF`. If only one digital identity type is available for the preselected country (and no physical documents), the document selection screen in the SDK can be skipped entirely.

```json
{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
	"key": X,
	"credentials": [
	  {
		"category": "ID",
		"type": {
		  "values": [
			"DIGITAL_IDENTITY"
		  ]
		},
		"subType": {
		  "values": [
			"EIDAS"
		  ]
		},
		"country": {
		  "values": [
			"AUT"
		  ]
		}
	  }
	]
  }
}
```

### Miscellaneous

Use [`cameraFacing`][camerafacing] attribute of [`JumioScanView`][jumioscanview] to configure the default camera and set it to `FRONT` or `BACK`.

```kotlin
scanView.cameraFacing = JumioCameraFacing.FRONT
```

## SDK Workflow

### Retrieving Information

The SDK returns a [`JumioResult`][jumioresult] object which contains the result of the finished workflow. Extracted ID data will not be returned by default - please contact **Jumio Customer Service** at [support@jumio.com](mailto:support@jumio.com) in case this is needed.

The following tables give information on the specification of all data parameters and errors:

- [`JumioIDResult`][jumioidresult]
- [`JumioFaceResult`][jumiofaceresult]
- [`JumioRejectReason`][jumiorejectreason]
- [`JumioError`][jumioerror]

#### Class **_JumioIDResult_**

| Parameter        | Type                         | Max. length | Description                                                                                                                                                            |
| :--------------- | :--------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| issuingCountry   | String                       | 3           | Country of issue as [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code                                                                |
| idType           | String                       |             | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA as provided or selected                                                                                                |
| idSubType        | String                       |             | Sub type of the scanned ID                                                                                                                                             |
| firstName        | String                       | 100         | First name of the customer                                                                                                                                             |
| lastName         | String                       | 100         | Last name of the customer                                                                                                                                              |
| dateOfBirth      | String                       |             | Date of birth                                                                                                                                                          |
| issuingDate      | String                       |             | Date of issue                                                                                                                                                          |
| expiryDate       | String                       |             | Date of expiry                                                                                                                                                         |
| documentNumber   | String                       | 100         | Identification number of the document                                                                                                                                  |
| personalNumber   | String                       |             | Personal number of the document                                                                                                                                        |
| gender           | String                       |             | Gender M, F or X                                                                                                                                                       |
| nationality      | String                       |             | Nationality of the customer                                                                                                                                            |
| placeOfBirth     | String                       | 255         | Place of birth                                                                                                                                                         |
| country          | String                       |             | Country of residence                                                                                                                                                   |
| address          | String                       | 64          | Street name of residence                                                                                                                                               |
| city             | String                       | 64          | City of residence                                                                                                                                                      |
| subdivision      | String                       | 3           | Last three characters of [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) or [ISO 3166-2:CA](https://en.wikipedia.org/wiki/ISO_3166-2:CA) subdivision code |
| postalCode       | String                       | 15          | Postal code of residence                                                                                                                                               |
| mrzLine1         | String                       | 50          | MRZ line 1                                                                                                                                                             |
| mrzLine2         | String                       | 50          | MRZ line 2                                                                                                                                                             |
| mrzLine3         | String                       | 50          | MRZ line 3                                                                                                                                                             |
| curp             | String                       |             | The Clave Única de Registro de Población (CURP) identity code for Mexican documents.                                                                                   |
| extractionMethod | [JumioScanMode][jumioscanmode] |             | Extraction method used during scanning                                                                                                                                 |
| imageData        | JumioImageData               |             | Wrapper class for accessing image data of all credential parts from an ID verification session. This feature has to be enabled by your account manager.                |

#### Class **_JumioFaceResult_**

| Parameter        | Type                         | Max. length | Description                                                                                                                                             |
| :--------------- | :--------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| passed           | Boolean                      |             |
| extractionMethod | [JumioScanMode][jumioscanmode] |             | Extraction method used during scanning (FACE_MANUAL, JUMIO_LIVENESS)                                                                                    |
| imageData        | JumioImageData               |             | Wrapper class for accessing image data of all credential parts from an ID verification session. This feature has to be enabled by your account manager. |

#### Class **_JumioRejectReason_**

List of all possible **_reject reasons_** the SDK could return if Instant Feedback is used:

:::info
Please be aware that the list of reject reasons that get returned depends on server-side configuration for every individual merchant.
:::

| Code | Message              | Description                                        |
| :--- | :------------------- | :------------------------------------------------- |
| 104  | DIGITAL_COPY         | Document appears to be a digital copy              |
| 200  | NOT_READABLE         | Document is not readable                           |
| 201  | NO_DOC               | No document could be detected                      |
| 206  | MISSING_BACK         | Backside of the document is missing                |
| 214  | MISSING_FRONT        | Frontside of the document is missing               |
| 401  | UNSUPPORTED_DOCUMENT | Document is not supported                          |
| 501  | INVALID_CERTIFICATE  | Document certificate could not be validated        |
| 2001 | BLURRY               | Document image is unusable because it is blurry    |
| 2003 | MISSING_PART_DOC     | Part of the document is missing                    |
| 2004 | HIDDEN_PART_DOC      | Part of the document is hidden                     |
| 2005 | DAMAGED_DOCUMENT     | Document appears to be damaged                     |
| 2006 | GLARE                | Document image is unusable because of glare        |

#### Error Codes

List of all **_error codes_** that are available via the `code` and `message` properties of the [`JumioError`][jumioerror] object. The first letter (A-J) represents the error case. The remaining characters are represented by numbers that contain information helping us understand the problem situation (format: [xx][yyyy]).

|    Code     | Message                                                            | Description                                                   |
| :---------: | :----------------------------------------------------------------- | :------------------------------------------------------------ |
| A[xx][yyyy] | We have encountered a network communication problem                | Retry possible, user decided to cancel                        |
| B[xx][yyyy] | Authentication failed                                              | Secure connection could not be established, retry impossible  |
|  C[xx]0401  | Authentication failed                                              | API credentials invalid, retry impossible                     |
|  E[xx]0000  | Connection error                                                   | Retry possible, user decided to cancel                        |
|  F[xx]0000  | Scanning not available at this time, please contact the app vendor | Resources cannot be loaded, retry impossible                  |
|  G[xx]0000  | Cancelled by end-user                                              | No error occurred                                             |
|  H[xx]0000  | The camera is currently not available                              | Camera cannot be initialized, retry impossible                |
|  I[xx]0000  | Certificate not valid anymore. Please update your application      | End-to-end encryption key not valid anymore, retry impossible |
|  J[xx]0000  | Transaction already finished                                       | User did not complete SDK journey within session lifetime     |
|  N[xx]0000  | Scanning not available at this time, please contact the app vendor | Required images are missing to finalize the acquisition       |

:::tip
Please always include error code and message when filing an error related issue to our support team.
:::

### Session Initialization Best Practices

- Generate SDK tokens just-in-time before SDK launch.
- Implement backend-controlled retry logic.
- Use reportingCriteria and Customer Internal Reference for tracking.
- Ensure runtime permissions are granted before launch.

## Default UI

In case you're using Jumio's Default UI module (see [Dependencies](#dependencies)) you may declare the `JumioActivity` in your `AndroidManifest.xml`. With this you can use Jumio's default theme or specify a custom theme (see [Customization](#customization) for details). Also you can set the orientation to be sensor based or locked by using the attribute `android:screenOrientation`. Please note though that some screens in Jumio SDK launch in portrait mode only.

```xml
<activity
  android:theme="@style/Theme.Jumio"
  android:hardwareAccelerated="true"
  android:name="com.jumio.defaultui.JumioActivity"
  android:configChanges="orientation|screenSize|screenLayout|keyboardHidden" />
```

## Custom UI

ID Verification can also be implemented as a **custom scan view.** This means that only the scan view (including the scan overlays) are provided by the SDK.
The handling of the lifecycle, document selection, readability confirmation, intermediate callbacks, and all other steps necessary to complete a scan have to be handled by the client application that implements the SDK.

The following sequence diagram outlines components, callbacks and methods for a basic ID Verification workflow:

![Custom UI Happy Path Diagram](images/happy_paths/custom_ui_happy_path_diagram.png)

:::note
The new 3D face liveness capturing technology is not optimized for tablets. When using Selfie Verification, the face scanner will fallback to a simple face capturing functionality instead. Portrait orientation support is required in your app.
:::

CustomUI enables you to use a custom scan view with a plain scanning user interface. Initialize the Jumio SDK and set [`token`][token] and [`datacenter`][datacenter].

```kotlin
val context: Context = ...
sdk = JumioSDK(context).apply {
	token = "YOUR_SDK_TOKEN"
	datacenter = JumioDataCenter.YOUR_DATACENTER
}
```

- [`JumioDataCenter`][datacenter] values: `US`, `EU`, `SG`

### UI/UX Best Practices

- Launch SDK only after explicit user consent.
- Show pre-permission screens explaining camera use.
- Prompt better lighting for retries.
- Avoid flashlight use by default.
- Use SDK localization.

### Controller Handling

Start the SDK by passing `context` and an instance of your class that implements [`JumioControllerInterface`][jumiocontrollerinterface]. You will receive a [`JumioController`][jumiocontroller] object in return:

```kotlin
val jumioController: JumioController = sdk.start(context, jumioControllerInterface)
```

When the `jumioController` is initialized, the following callback will be triggered:

```kotlin
onInitialized(credentials: List<JumioCredentialInfo>, consentItems: List<JumioConsentItems>?, termsOfUse: JumioTermsOfUse?)
```

#### Consent Handling

To support compliance with various data protection laws, if a user’s consent is required the parameter `consentItems` will provide a list of [`JumioConsentItems`][jumioconsentitem]. Each consent item contains a text, a consent type and an URL that will redirect the user to Jumio’s consent details. Each [`JumioConsentItem`][jumioconsentitem] also provides a method `spannedTextWithLinkColor(color: Int)` that will return a spanned string containing the consent text and the link holder. If no color is specified, the link portion of the spanned string will only be underlined.

If no consent is required, the parameter `consentItems` will be `null`.

Each consent item can be one of two types:

- [`JumioConsentType.ACTIVE`][jumioconsenttype]
- [`JumioConsentType.PASSIVE`][jumioconsenttype]

For `ACTIVE` types, the user needs to accept the consent items explicitly, e.g. by enabling a UI switch or checking a checkbox for each consent item. For `PASSIVE` types, it is enough to present the consent text and URL to the user. The user implicitly accepts the passive consent items by continuing with the journey. For details please check out consent handling [(1)](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/customui/CustomUiActivity.kt#L218-L234) [(2)](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/customui/CustomUiActivity.kt#L252-L260) and [consent adapter](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/customui/adapter/CustomConsentAdapter.kt) in our sample app.

The user can open and continue to the provided consent link if they choose to do so. If the user consents to Jumio's policy, [`jumioController.userConsented(consentItem: JumioConsentItem, userConsent: Boolean)`][userconsented] is required to be called internally before any credential can be initialized and the user journey can continue. If no consent is required, the list of [`JumioConsentItems`][jumioconsentitem] will be `null`. If the user does not consent or if [`jumioController.userConsented(consentItem: JumioConsentItem, userConsent: Boolean)`][userconsented] is not called for all the items inside the `consentItems` list, the user will not be able to continue the user journey.

:::warning
Please be aware that in cases where the list of `consentItems` is not `null`, the user **must consent** to Jumio's processing of personal information, including biometric data, and be provided a link to Jumio's Privacy Notice. Do not accept automatically without showing the user any terms.
:::

#### Terms of Use Handling

The `termsOfUse` parameter provides a [`JumioTermsOfUse`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.termsofuse/-jumio-terms-of-use/index.html) which contains:
- `text`: The localized string containing the terms of use text.
- `url`: The URL to redirect the user to Jumio’s terms of use details.

If the `termsOfUse` parameter is `null`, then it should be ignored.

### Credential Handling

Obtain an instance of [`JumioCredential`][jumiocredential] which will contain all necessary information about the verification process by calling `start` on the `JumioController`.

For ID verification you will receive a [`JumioIDCredential`][jumioidcredential], for Selfie Verification a [`JumioFaceCredential`][jumiofacecredential], and so on. Call [`isConfigured`][isconfigured] to check if the credential is already pre-configured. If so, it can be started right away.

```kotlin
val currentCredentialInfo = ...

val currentCredential = jumioController.start(currentCredentialInfo)
if (currentCredential?.isConfigured == true) {
	// credential can be started
}
```

If the credential is not configured yet, it needs some more configuration before scan parts can be initialized. Details on how to configure each credential and retrieve the first [scan part][jumioscanpart] can be found below.

- [`JumioCredentialCategory`][jumiocredentialcategory] values: `ID`, `FACE`, `DOCUMENT`, `DATA`


Credentials should be processed in ascending order based on the `order` property specified in [`JumioCredentialInfo`][jumiocredentialinfo]. Credentials with the same order value can be processed in any sequence.

⚠️&nbsp;&nbsp;**Note:** Processing credentials according to order is necessary to continue the user journey.

#### Jumio ID Credential

The `lookupResult` property of type [`JumioLookupResult`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-lookup-result/index.html) is returned when a document is found during a Selfie.DONE workflow. If the `lookupResult` contains [`JumioDocumentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-type/index.html) and [`JumioLegalStatement`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-legal-statement/index.html), then you must call [`userConsented(JumioLookupResult.JumioLegalStatement, Boolean)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-id-credential/user-consented.html) using the `legalStatement` from the `lookupResult` to record the user's decision:
- Calling `userConsented(JumioLookupResult.JumioLegalStatement, true)` indicates that consent has been given to use the data from the `lookupResult`. In this scenario, the [`JumioIDCredential`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/index.html) is considered complete, allowing you to immediately call `finish()` on the credential without requiring a new scan.
- Calling `userConsented(JumioLookupResult.JumioLegalStatement, false)` indicates that consent has not been given to use the `lookupResult` data, and the workflow will proceed to scan a new document.

In case of [`JumioIDCredential`][jumioidcredential], you can retrieve all available countries from [`supportedCountries`][supportedcountries]. After selecting a specific country from that list, you can query available documents for that country by either calling [`getPhysicalDocumentsForCountry`][getphysicaldocuments] or [`getDigitalDocumentsForCountry`][getdigitaldocuments]. To configure the [`JumioIDCredential`][jumioidcredential], pass your desired document as well as the country to [`setConfiguration()`][setidconfiguration].

Retrieve the supported countries:

```kotlin
idCredential = ... // Credential received via jumioController.start

val countries: List<String> = idCredential.countries

val country = countries.first { ... } // Select your desired country
```

Query available physical documents (e.g. passports or driving licenses):

```kotlin
val jumioDocuments = idCredential.getPhysicalDocumentsForCountry(country)

val document = jumioDocuments.first { it.type == JumioDocumentType.PASSPORT }
```

Query available digital documents ("Digital Identities"):

```kotlin
val jumioDocuments = idCredential.getDigitalDocumentsForCountry(country)

val document = jumioDocuments.first()
```

Set a valid country / document configuration:

```kotlin
idCredential.setConfiguration(country, document)
```

- [`JumioPhysicalDocument`][jumiophysicaldocument] represents a single `JumioDocumentType` and `JumioDocumentVariant` combination

  - [`JumioDocumentType`][jumiodocumenttype] values: `PASSPORT`, `VISA`, `DRIVING_LICENSE`, `ID_CARD`

  - [`JumioDocumentVariant`][jumiodocumentvariant] values: `PAPER`, `PLASTIC`

- [`JumioDigitalDocument`][jumiodigitaldocument] represents a digital document ("Digital Identity")

  - [`JumioDigitalDocumentType`][jumiodigitaldocumenttype] values: `TRUST_CHECK`, `EIDAS`, `MASTERCARD`, `DIGITAL_DRIVING_LICENSE_PDF`

Once the credential is configured, it is ready to initialize it's first scan part and start the verification process:

```kotlin
val credentialPart = idCredential.credentialParts.first()
idCredential.initScanPart(credentialPart, yourScanPartInterface)
```

#### Jumio Face Credential

In case of [`JumioFaceCredential`][jumiofacecredential], Jumio uses Certified Liveness technology to determine liveness. The mode can be detected by checking the [`JumioScanMode`][jumioscanmode] of the [`JumioScanPart`][jumioscanpart]. Make sure to also implement `FACE_MANUAL` as a fallback, in case `JUMIO_LIVENESS` is not available.

Retrieve the credential part of the credential to start the scanning process by calling:

```kotlin
val credentialPart = currentCredential?.credentialParts?.first()
val scanPart = currentCredential?.initScanPart(credentialPart, yourScanPartInterface)
```

or use the convenience method

```kotlin
val scanPart = currentCredential?.initScanPart(yourScanPartInterface)
```

#### Jumio Document Credential

In case of [`JumioDocumentCredential`][jumiodocumentcredential], there is the option to either acquire the image using the camera or selecting a PDF file from the device. Call `setConfiguration` with a [`JumioAcquireMode`][acquiremode] to select the preferred mode as described in the code documentation.

- [`JumioAcquireMode`][acquiremode] values: `CAMERA`, `FILE`

```kotlin
val acquireModes: List<JumioAcquireMode> = (credential as JumioDocumentCredential).availableAcquireModes

(currentCredential as JumioDocumentCredential).setConfiguration(acquireModes[0])
```

Retrieve the credential part of the credential to start the scanning process by calling:

```kotlin
val credentialPart = currentCredential?.credentialParts?.first()
val scanPart = currentCredential?.initScanPart(credentialPart, yourScanPartInterface)
```

or use the convenience method

```kotlin
val scanPart = currentCredential?.initScanPart(yourScanPartInterface)
```

If [`JumioAcquireMode`][acquiremode] `FILE` is used, the [`JumioFileAttacher`][jumiofileattacher] needs to be utilized
to add a File or FileDescriptor for the selected [`JumioScanPart`][jumioscanpart].

```kotlin
val fileAttacher = JumioFileAttacher()
fileAttacher.attach(scanPart)

val file = File("/path/to/your/file.pdf")
fileAttacher.setFile(file)
```

#### Jumio Data Credential

:::note
`JumioDataCredential` is only available from SDK version `4.2.0` to `4.8.1` (inclusively).
:::

[`JumioDataCredential`][jumiodatacredential] is used for the device fingerprinting. There are some optional configurations you can do to enhance it's behavior.

1. Add the following Android permissions to your `AndroidManifest.xml`, if not already added:

```xml
<manifest>
	<!--Get user's GPS Location.-->
	<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

	<!--Get User's Wifi name and Status.-->
	<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

	<!--Get User's Network information and State.-->
	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

	<!--Get Phone and Network information (MNC, MCC, IMEI, Phone Number, Phone Type (GSM/CDMA), SIM Number, etc).-->
	<uses-permission android:name="android.permission.READ_PHONE_STATE" />

	<!--Get user's Biometric authentication settings (Face or Fingerprint authentication).-->
	<uses-permission android:name="android.permission.USE_BIOMETRIC" />

	<!--Get user's Biometric authentication settings (Face or Fingerprint authentication).-->
	<uses-permission android:name="android.permission.USE_FINGERPRINT" />

	<!--Write data into device to check re-installation behavior.-->
	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

	<!--Get External storage status, total size, free size, etc.-->
	<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

	<!--Get GSFID (Google Services Id) for accurate identification for unique users.-->
	<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
</manifest>
```

:::note

- The reason for the requirement of the given permission is added as inline comment.
- Some of them are `dangerous` permissions, and you have to ask for the permission from the user. More information about permissions can be found in the official [Android documentation](https://developer.android.com/guide/topics/permissions/overview)
- The above permissions imply to add some features to your manifest file:
:::

```xml
  <uses-feature
    android:name="android.hardware.location"
    android:required="false"/>

  <uses-feature
    android:name="android.hardware.telephony"
    android:required="false"/>

  <uses-feature
    android:name="android.hardware.wifi"
    android:required="false"/>
```

2. If you use proguard for obfuscation, you have to add some rules to your [`proguard-rules.pro`][proguardrules]
   configuration file:

```text
   -keep com.google.android.gms.*
   -keep com.google.android.gms.tasks.*
   -keep com.google.android.gms.ads.identifier.AdvertisingIdClient
```

### ScanPart Handling

The following sequence diagram outlines an overview of ScanPart handling details:
![ScanPart Happy Path Diagram](images/happy_paths/scanpart_happy_path_diagram.png)

Start the scanning process by initializing the [`JumioScanPart`][jumioscanpart]. A list of mandatory [`JumioCredentialPart`][jumiocredentialpart]s is retrievable over [`currentCredential?.credentialParts`](credentialPartsList) as soon as the credential is configured. Possible values are:

`currentScanPart = currentCredential?.initScanPart(credentialPart, yourJumioScanPartInterface)`

- [`JumioCredentialPart`][jumiocredentialpart] values: `FRONT`, `BACK`, `MULTIPART`, `FACE`, `DOCUMENT`, `NFC`, `DIGITAL`

Each [`jumioScanPart`][jumioscanpart] has an associated `scanMode`. Depending on the scan mode, you need to provide a different user guidance. The following scan modes are available for the different `JumioCredentialPart`s:

- [`JumioScanMode`][jumioScanMode] values:
  - `FRONT`, `BACK`, `MULTIPART`: `MANUAL`, `BARCODE`, `DOCFINDER`
  - `DIGITAL`: `WEB`, `FILE`
  - `NFC`: `NFC`
  - `FACE`: `FACE_MANUAL`, `JUMIO_LIVENESS`, `JUMIO_PREMIUM`
  - `DOCUMENT`: `MANUAL`, `FILE`

During the scanning process, use the `onUpdate` function of the `JumioScanPartInterface` to check on the scanning progress and update your user guidance accordingly.

`MULTIPART` handles the scanning of multiple sides in one seamless capture experience. When a [`MULTIPART`][jumiomultipart] scan part is started, an additional [`NEXT_PART`][nextpart] step is sent after [`IMAGE_TAKEN`][imagetaken]. This signals that another side of the document should be scanned now. The step returns the [`JumioCredentialPart`][jumiocredentialpart] that should be scanned next. We suggest to actively guide the user to move to the next part, e.g. by showing an animation and by disabling the extraction during the animation. Please also check the new [`NEXT_PART`][nextpart] scan step for this [`JumioCredentialPart`][jumiocredentialpart]

Start the execution of the acquired [`JumioScanPart`][jumioscanpart] by calling [`currentScanPart?.start()`][startscanpart].

When the scanning is done, the parameter [`JumioScanStep.CAN_FINISH`][canfinish] will be received and the scan part can be finished by calling [`currentScanPart?.finish()`][finishscanpart].

Check if the credential is complete by calling [`currentCredential?.isComplete`][iscompletecredential] and finish the current credential by calling [`currentCredential?.finish()`][finishcredential].

Continue that procedure until all needed credentials (e.g. `ID`, `FACE`, `DOCUMENT`) are finished. Check if all credentials are finished with [`jumioController.isComplete`][iscompletecontroller], then call [`jumioController?.finish()`][finishcontroller] to finish the user journey.

The callback [`onFinished()`][onfinished] will be received after the controller has finished:

```kotlin
override fun onFinished(result: JumioResult) {
  log("onFinished")
  sdkResult.value = result
}
```

#### Scan Steps

During the scanning process [`onScanStep()`][onscanstep] will be called as soon as the [`JumioScanPart`][jumioscanpart] needs additional input to continue the scanning journey. The provided [`JumioScanStep`][jumioscanstep] indicates what needs to be done next.

[`JumioScanStep`][jumioscanstep]s cover lifecycle events which require action from the customer to continue the process.

[`JumioScanStep`][jumioscanstep] values: `PREPARE`, `STARTED`, `ATTACH_ACTIVITY`, `ATTACH_FILE`, `SCAN_VIEW`, `NEXT_PART`, `IMAGE_TAKEN`, `PROCESSING`, `CONFIRMATION_VIEW`, `REJECT_VIEW`, `RETRY`, `CAN_FINISH`, `ADDON_SCAN_PART`, `DIGITAL_IDENTITY_VIEW`, `THIRD_PARTY_VERIFICATION`

[`PREPARE`][prepare] is only sent if a scan part requires upfront preparation and the customer should be notified (e.g. by displaying a loading screen):

```kotlin
JumioScanStep.PREPARE -> {
  showLoadingView()
}
```

[`STARTED`][started] is always sent when a scan part is started. If a loading spinner was triggered before, it can now be dismissed:

```kotlin
JumioScanStep.STARTED -> {
  hideLoadingView()
}
```

[`DIGITAL_IDENTITY_VIEW`][digitalidentityview] points out that the current [`JumioScanPart`][jumioscanpart] needs to be attached to a [`JumioDigitalIdentityView`][jumiodiview]. The [`JumioDigitalIdentityView`][jumiodiview] is a custom view that can be placed in your layout.

```kotlin
JumioScanStep.DIGITAL_IDENTITY_VIEW -> {
	currentScanPart?.let {
		jumioDigitalIdentityView.attach(it)
	}
}
```

[`THIRD_PARTY_VERIFICATION`][thirdpartyverification] is triggered in case the current [`JumioScanPart`][jumioscanpart] will switch to a third party's application to continue the verification process (e.g. for Digital Identity verification). As this might take some time, showing a loading indicator is recommended.

```kotlin
JumioScanStep.THIRD_PARTY_VERIFICATION -> {
	showLoadingView()
}
```

[`ATTACH_ACTIVITY`][attachactivity] indicates that an Activity Context is needed. Please see [`JumioActivityAttacher`][jumioactivityattacher] for more information.

```kotlin
JumioScanStep.ATTACH_ACTIVITY -> {
	currentScanPart?.let {
		JumioActivityAttacher(this).attach(it)
	}
}
```

[`ATTACH_FILE`][attachfile] is sent when the user needs to select and upload a file. For this, you should create a [`JumioFileAttacher`][jumiofileattacher], add it to your [`JumioScanPart`][jumioscanpart] and provide the document.
This step is only sent, when the scan method is `FILE`.

```kotlin
JumioScanStep.ATTACH_FILE -> {
	currentScanPart?.let {
		val jumioFileAttacher = JumioFileAttacher()
		jumioFileAttacher.attach(it)
		// Choose how the file should be attached
		// jumioFileAttacher.setFileDescriptor(<your file descriptor>)
		// jumioFileAttacher.setFile(<your file>)
	}
}
```

[`SCAN_VIEW`][scanview] is sent, when the scan view should be displayed. On this view, the user will capture a photo or a sequence of photos of a document or of a face with the camera.
[`JumioScanView`][jumioscanview] needs to be attached to the [`JumioScanPart`][jumioscanpart]. The [`JumioScanView`][jumioscanview] is a custom view that can be placed in your layout.
During runtime it just needs to be attached to the [`JumioScanPart`][jumioscanpart]. Make sure to re-attach the scanview from scan steps [`STARTED`][started] or [`NEXT_PART`][nextpart] in case the activity gets recreated and the scanview was attached before.

```kotlin
JumioScanStep.SCAN_VIEW -> {
	currentScanPart?.let {
		jumioScanView.attach(it)
	}
}
```

[`IMAGE_TAKEN`][imagetaken] is triggered as soon as all required images for the current part are captured and uploaded to the Jumio server. This event might be followed by a [`NEXT_PART`][nextpart] event with additional information on which part has to be scanned next (if any). The data parameter of [`onScanStep()`][onscanstep] contains a `Map` with the `scanPart` (a [`JumioCredentialPart`][jumiocredentialpart] value) and `scanMode` (a [`JumioScanMode`][jumioscanmode] value) of the captured image.

When all parts are done and background processing is executed, [`JumioScanStep.PROCESSING`][processing] is triggered. The camera preview might be stopped during that step.

If images for confirmation or rejection need to be displayed then [`JumioScanStep.CONFIRMATION_VIEW`][confirmationview] or [`JumioScanStep.REJECT_VIEW`][rejectview] is triggered. Attach the [`JumioConfirmationHandler`][jumioconfirmationhandler] or [`JumioRejectHandler`][jumiorejecthandler] once the steps are triggered and render the available [`JumioCredentialParts`][jumiocredentialpart] in [`JumioConfirmationView`][jumioconfirmationview] or [`JumioRejectView`][jumiorejectview] objects:

```kotlin
JumioScanStep.CONFIRMATION_VIEW -> {
	val confirmationHandler = JumioConfirmationHandler()
	confirmationHandler.attach(scanPart)
	confirmationHandler.parts.forEach {
		val confirmationView = JumioConfirmationView(context)
		confirmationHandler.renderPart(it, confirmationView)
		...
	}
}
JumioScanStep.REJECT_VIEW -> {
	val rejectHandler = JumioRejectHandler()
	rejectHandler.attach(scanPart)
	rejectHandler.parts.forEach {
		val rejectView = JumioRejectView(context)
		rejectHandler.renderPart(it, rejectView)
		...
	}
}
```

The scan part can be confirmed by calling [`confirmationView.confirm()`][confirm] or retaken by calling [`confirmationView.retake()`][retakeconfirmation] or [`rejectView.retake()`][retakereject].

The retry scan step returns a data object of type [`JumioRetryReason`][jumioretryreason]. On [`RETRY`][retry], a retry should be triggered on the scan part.

```kotlin
JumioScanStep.RETRY -> {
	val reason = data as? JumioRetryReason ?: return

	val retryCode = reason.code
	val retryMessage = reason.message
	...

	currentScanPart?.retry(reason)
}
```

For possible retry codes please checkout [`JumioRetryReasonGeneric`][jumioretrygeneric], [`JumioRetryReasonDocumentVerification`][jumioretrydv], [`JumioRetryReasonNfc`][jumioretrynfc], and [`JumioRetryReasonDigitalIdentity`][jumioretrydi].

As soon as the scan part has been confirmed and all processing has been completed [`CAN_FINISH`][canfinish] is triggered. [`scanPart.finish()`][finishscanpart] can now be called. During the finish routine the SDK checks if there is an add-on functionality for this part available, e.g. possible NFC scanning after an MRZ scan part. In this case [`ADDON_SCAN_PART`][addonscanpart] will be called.

When an add-on to the current scan part is available, [`JumioScanStep.ADDON_SCAN_PART`][addonscanpart] is sent. The add-on scan part can be retrieved using the method `addonScanPart = currentCredential?.getAddonPart()`.

To see if the finished credential part was the last one of the credential, check `currentCredentialPart == currentCredential?.credentialPart?.last()`. Check if the credential is complete by calling [`currentCredential?.isComplete`][isComplete] and finish the current credential by calling [`currentCredential?.finish()`][credentialFinish].

Continue that procedure until all necessary credentials (e.g. `ID`, `FACE`, `DOCUMENT`, `DATA`) are finished. Check if the last credential is finished, then call [`controller?.finish()`][controllerFinish] to end the user journey.

#### Scan Updates

[`JumioScanUpdates`][jumioscanupdate]s are distributed via the `JumioScanPartInterface` method [`onUpdate()`][onupdate] and cover scan information that is relevant and might need to be displayed during scanning process.
An optional value `data` of type `Any` can contain additional information for each scan update as described.

[`JumioScanUpdate`][jumioscanupdate] values: `CAMERA_AVAILABLE`, `FALLBACK`, `NFC_EXTRACTION_STARTED`, `NFC_EXTRACTION_PROGRESS`, `NFC_EXTRACTION_FINISHED`, `CENTER_ID`, `HOLD_STRAIGHT`, `MOVE_CLOSER`, `TOO_CLOSE`, `HOLD_STILL`, `MOVE_FACE_CLOSER`, `FACE_TOO_CLOSE`, `NEXT_POSITION`, `FLASH`, `TILT`, `IMAGE_ANALYSIS`

In case of `FALLBACK`, the `scanMode` has changed and you should adapt the user interface to reflect the new scan mode. Check the `JumioScanView`[jumioscanview] method `isShutterEnabled`[isshutterenabled] and see if it returns `true`.
If this is the case, a manual shutter button needs to be displayed for the end user to capture an image.

All possible [`JumioFallbackReason`][fallbackreason] values are sent in the optional `data` value to indicate the reason of the fallback.

`NFC_EXTRACTION_STARTED`, `NFC_EXTRACTION_PROGRESS`, and `NFC_EXTRACTION_FINISHED` make it possible to track the progress of an NFC scan. `NFC_EXTRACTION_PROGRESS` additionally delivers an integer in the data parameter in the range of 0-100 to signal the progress in the current data group.

`NEXT_POSITION` signals that the user needs to take a second image, e.g., needs to move the face in a liveness scan.

For the scanMode `DOCFINDER`, the following scan updates are sent: `CENTER_ID`, `TOO_CLOSE`, `MOVE_CLOSER`, `HOLD_STRAIGHT`, `TILT`, `FLASH`

FOR `ID` scans, a Long representing the time for which the user needs to hold still is sent in the data parameter of `JumioScanPartInterface.onUpdate`, when the extraction state `HOLD_STILL` is returned.

`TILT` signals that during an `ID` scan, the document in front of the camera needs to be tilted. The current angle as well as the target angle are transmitted as [`JumioTiltState`][jumiotiltstate] via the `data` parameter.
A negative current angle indicates that the document needs to be tilted in the other direction. When a tilt update is sent, advise the user to tilt the identity document by e.g. showing an animation or an overlay.

`FLASH` signals the enabling or disabling of the camera flash.

`IMAGE_ANALYSIS` signals that the image is being analyzed.

We suggest to disable orientation changes during the states `FLASH` and `IMAGE_ANALYSIS`. Please note - fallback and camera switch will also not be available during these stages.

We send the following extraction states for the scan modes `JUMIO_LIVENESS` and `JUMIO_PREMIUM`: `CENTER_FACE`, `FACE_TOO_CLOSE`, `MOVE_FACE_CLOSER`, `MOVE_FACE_INTO_FRAME`, `LEVEL_EYES_AND_DEVICE`, `HOLD_STILL`, `TILT_FACE_UP`, `TILT_FACE_DOWN`, `TILT_FACE_LEFT`, `TILT_FACE_RIGHT`

```kotlin
override fun onUpdate(jumioScanUpdate: JumioScanUpdate, data: Any?) {
	when(jumioScanUpdate) {
		JumioScanUpdate.FALLBACK -> handleFallback(data as JumioFallbackReason)
		JumioScanUpdate.FLASH -> handleFlash(data as JumioFlashState)
		JumioScanUpdate.TILT -> handleTilt(data as JumioTiltState)
			... // handle other scan updates
	}
}
```

### Result and Error Handling

Instead of using the standard method `onActivityResult()`, implement the following methods within your [`jumioControllerInterface`][jumiocontrollerinterface] for successful scans and error notifications:

The method `onFinished(result: JumioResult)` has to be implemented to handle data after a successful scan, which will return [`JumioResult`][jumioresult].

```kotlin
override fun onFinished(result: JumioResult) {
	val data = result
	// handle success case
	finish()
}
```

The method `onError(error: JumioError)` has to be implemented to handle data after an unsuccessful scan, which will return [`JumioError`][jumioerror]. Check the parameter [`error.isRetryable`][isretryable] to see if the failed scan attempt can be retried.

```kotlin
override fun onError(error: JumioError) {
	if (error.isRetryable) {
		// retry scan attempt
	} else {
		// handle error case
	}
	log(String.format("onError: %s, %s, %s", error.code, error.message, if (error.isRetryable) "true" else "false"))
}
```

If an error is retryable, [`jumioController.retry()`][retrycontroller] should be called to execute a retry.

## Error Handling & Retry Strategy

- Categorize errors: soft (retry allowed) vs hard (exit flow).
- On failure: create new account ID or reuse existing account ID with new session.
- Redirect to retry/support screen instead of immediate SDK relaunch.
- Log errors without storing PII.

### Instant Feedback

The use of Instant Feedback provides immediate end user feedback by performing a usability check on any image the user took and prompting them to provide a new image immediately if this image is not usable, for example because it is too blurry. Please refer to the [JumioRejectReason table](#retrieving-information) for a list of all reject possibilities.

## Customization

The Jumio SDK provides various options to customize its UI. If you are using [Default UI](#default-ui) you can change each screen to fulfil your needs. In case you decide to implement the verification workflow on your own (see [Custom UI](#custom-ui)) you also have the possibility to influence the look and feel of some views provided by the SDK, e.g. [`JumioScanView`][jumioscanview].

### Customization Tool

[Jumio Surface](https://jumio.github.io/surface-tool/) is a web tool that offers the possibility to apply and visualize all available customization options for the Jumio SDK, as well as an export feature that generates all data needed to import the desired changes straight into your codebase.

[![Jumio Surface](images/surface_tool.png)](https://jumio.github.io/surface-tool/)

### Default UI customization

The surface tool utilizes each screen of Jumio's [Default UI](#default-ui) to visualize all items and colors that can be customized. If you are planning to use the [Default UI](#default-ui) implementation, you can specify the `Theme.Jumio` as a parent style in your application and override according attributes within this theme to match your application's look and feel.

After customizing the SDK via the surface tool, you can click the **Android-Xml** button in the **Output** menu on the bottom right to copy the code from the theme `AppThemeCustomJumio` to your Android app's `styles.xml` file.

Apply your custom theme that you defined before by replacing `Theme.Jumio` in the `AndroidManifest.xml:`

```xml
<activity
	android:name="com.jumio.defaultui.JumioActivity"
	android:theme="@style/AppThemeCustomJumio">
	...
</activity>
```

#### Dark Mode

`Theme.Jumio` attributes can also be customized for dark mode. If you haven't done so already, create a `values-night` folder in your resources directory and add a new `styles.xml` file. Adapt your custom Jumio theme for dark mode. The SDK will switch automatically to match the system settings of the user device.

### Custom UI customization

If you implement your own UI, you can still customize how some views provided by the SDK look. In particular this means you can customize Jumio's **scan overlay** and **NFC scanning** views at the moment.

By following the steps explained in [Default UI customization](#default-ui-customization) you can see potential attributes to override in the generated XML file.

## Testing & Validation

- Use Jumio official sample apps to validate flows.
- Test on varied device tiers and OS versions.
- Test multiple ID types and lighting conditions.

# Security

All SDK related traffic is sent over HTTPS using TLS and public key pinning. Additionally, the information itself within the transmission is also encrypted utilizing **Application Layer Encryption** (ALE). ALE is a Jumio custom-designed security protocol that utilizes RSA-OAEP and AES-256 to ensure that the data cannot be read or manipulated even if the traffic was captured.

## Token Management & Session Security

- Always create SDK tokens server-side.
- Auth Tokens are valid for 60 minutes. Reuse the same token within that window rather than generating a new one per launch.
- Pass Auth tokens securely using HTTPS only and store in-memory only.
- Never hard-code or store tokens creation mechanism on devices.
- Always log Account ID and workflowExecutionId.

# Support

## Licenses

The software contains third-party open source software. For more information, see [licenses](../licenses).

This software is based in part on the work of the Independent JPEG Group.

## Contact

If you have any questions regarding our implementation guide please contact **Jumio Customer Service** at [support@jumio.com](mailto:support@jumio.com). The [Jumio online helpdesk](https://support.jumio.com) contains a wealth of information regarding our services including demo videos, product descriptions, FAQs, and other resources that can help to get you started with Jumio.

## Copyright

&copy; Jumio Corporation, 100 Mathilda Place Suite 100 Sunnyvale, CA 94086

The source code and software available on this website (“Software”) is provided by Jumio Corp. or its affiliated group companies (“Jumio”) "as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Jumio be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services, loss of use, data, profits, or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this Software, even if advised of the possibility of such damage.
In any case, your use of this Software is subject to the terms and conditions that apply to your contractual relationship with Jumio. As regards Jumio’s privacy practices, please see our privacy notice available here: [Privacy Policy](https://www.jumio.com/privacy-center/privacy-notices/online-services-notice/).

[token]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/token.html
[datacenter]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/data-center.html
[sdkversion]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/version.html
[isrooted]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/is-rooted.html
[camerafacing]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-camera-facing/index.html
[acquiremode]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-acquire-mode/index.html
[fallbackreason]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-fallback-reason/index.html
[userconsented]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/user-consented.html
[isconfigured]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/is-configured.html
[setidconfiguration]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/set-configuration.html
[supportedcountries]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/supported-countries.html
[getphysicaldocuments]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/get-physical-documents-for-country.html
[getdigitaldocuments]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/get-digital-documents-for-country.html
[iscompletecredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/is-complete.html
[iscompletecontroller]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/is-complete.html
[startscanpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/start.html
[finishscanpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/finish.html
[finishcredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/finish.html
[finishcontroller]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/finish.html
[isshutterenabled]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-scan-view/is-shutter-enabled.html
[isretryable]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.error/-jumio-error/is-retryable.html
[confirm]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-confirmation-view/confirm.html
[retakeconfirmation]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-confirmation-view/retake.html
[retakereject]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-reject-view/retake.html
[retrycontroller]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/retry.html
[onfinished]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-finished.html
[onscanstep]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-scan-part-interface/on-scan-step.html
[onupdate]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-scan-part-interface/on-update.html
[canfinish]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-c-a-n_-f-i-n-i-s-h/index.html
[prepare]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-p-r-e-p-a-r-e/index.html
[started]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-s-t-a-r-t-e-d/index.html
[attachactivity]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-a-t-t-a-c-h_-a-c-t-i-v-i-t-y/index.html
[attachfile]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-a-t-t-a-c-h_-f-i-l-e/index.html
[scanview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-s-c-a-n_-v-i-e-w/index.html
[digitalidentityview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-d-i-g-i-t-a-l_-i-d-e-n-t-i-t-y_-v-i-e-w/index.html
[imagetaken]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-i-m-a-g-e_-t-a-k-e-n/index.html
[nextpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-n-e-x-t_-p-a-r-t/index.html
[processing]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-p-r-o-c-e-s-s-i-n-g/index.html
[confirmationview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-c-o-n-f-i-r-m-a-t-i-o-n_-v-i-e-w/index.html
[rejectview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-r-e-j-e-c-t_-v-i-e-w/index.html
[retry]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-r-e-t-r-y/index.html
[addonscanpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-a-d-d-o-n_-s-c-a-n_-p-a-r-t/index.html
[thirdpartyverification]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-t-h-i-r-d_-p-a-r-t-y_-v-e-r-i-f-i-c-a-t-i-o-n/index.html
[jumioactivityattacher]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-activity-attacher/index.html
[jumiofileattacher]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-file-attacher/index.html
[jumioscanview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-scan-view/index.html
[jumiocontroller]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/index.html
[jumiocontrollerinterface]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/index.html
[jumioresult]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-result/index.html
[jumioidresult]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-i-d-result/index.html
[jumiofaceresult]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-face-result/index.html
[jumiorejectreason]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.reject/-jumio-reject-reason/index.html
[jumioerror]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.error/-jumio-error/index.html
[jumiocredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/index.html
[jumiocredentialinfo]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential-info/index.html
[jumioidcredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/index.html
[jumiodocumentcredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-document-credential/index.html
[jumiofacecredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-face-credential/index.html
[jumiodatacredential]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-data-credential/index.html
[jumiocredentialcategory]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential-category/index.html
[jumiophysicaldocument]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-physical-document/index.html
[jumiodigitaldocument]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document/index.html
[jumiodocumenttype]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-type/index.html
[jumiodocumentvariant]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-variant/index.html
[jumiocredentialpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html
[jumioscanstep]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/index.html
[jumioretryreason]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.retry/-jumio-retry-reason/index.html
[jumioretrygeneric]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.retry/-jumio-retry-reason-generic/index.html
[jumioretrydv]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.retry/-jumio-retry-reason-document-verification/index.html
[jumioretrynfc]: https://jumio.github.io/mobile-sdk-android/jumio-nfc/com.jumio.sdk.retry/-jumio-retry-reason-nfc/index.html
[jumioretrydi]: https://jumio.github.io/mobile-sdk-android/jumio-digital-identity/com.jumio.sdk.retry/-jumio-retry-reason-digital-identity/index.html
[jumioconfirmationview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-confirmation-view/index.html
[jumiorejectview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-reject-view/index.html
[jumioconfirmationhandler]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-confirmation-handler/index.html
[jumiorejecthandler]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-reject-handler/index.html
[jumioscanupdate]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html
[jumiofileattacher]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-file-attacher/index.html
[jumioscanpart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html
[jumiomultipart]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/-m-u-l-t-i-p-a-r-t/index.html
[jumioscanmode]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html
[jumioconsenttype]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-consent-type/index.html
[jumioconsentitem]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.consent/-jumio-consent-item/index.html
[credentialpartslist]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/credential-parts.html
[proguardrules]: https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/proguard-rules.pro
[jumiodiview]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-digital-identity-view/index.html
[jumiopreloader]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.preload/-jumio-preloader/index.html
[jumiopreloadcallback]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.preload/-jumio-preload-callback/index.html
[jumioflashstate]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-flash-state/index.html
[jumiotiltstate]: https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.data/-jumio-tilt-state/index.html

---

# Transition Guide

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/transition_guide

![Header Graphic](images/jumio_feature_graphic.jpg)

# Transition Guide for Android SDK

This section covers all technical changes that should be considered when updating from previous versions, including, but not exclusively: API breaking changes or new functionality in the public API, major dependency changes, attribute changes, deprecation notices.

:::important

- When updating your SDK version, **all** changes/updates made in in the meantime have to be taken into account and applied if necessary.
- **Example:** If you're updating from SDK version **3.7.2** to **3.9.2**, the changes outlined in **3.8.0, 3.9.0** and **3.9.1** are **still relevant**.
:::

## 4.18.0

#### Minimum Android SDK Version increase

⚠️&nbsp;&nbsp;SDK 4.17.0 was the last SDK version supporting Android 6 (API level 23). Starting with this release the minimum Android SDK version is raised to Android 7.0 "Nougat" (API level 24).

#### Public API Changes

- [`JumioDigitalDocumentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document-type/index.html) enum has been added with the following supported values: `TRUST_CHECK`, `EIDAS`, `MASTERCARD`, `DIGITAL_DRIVING_LICENSE_PDF`
- [`JumioDigitalDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document/index.html) property `type` has changed from `String` to [`JumioDigitalDocumentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document-type/index.html).
- Digital Identity documents can now be preselected via the account request. See the [Preselection](integration_guide.md#preselection) section in the integration guide for details.
- The data parameter of [`JumioScanStep.IMAGE_TAKEN`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-i-m-a-g-e_-t-a-k-e-n/index.html) now contains a `Map` with the `scanPart` (a [`JumioCredentialPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html) value) and `scanMode` (a [`JumioScanMode`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html) value) of the captured image.

#### Model updates

If you are using the `com.jumio.android:docfinder` module and you bundle the required models in your app then please note that the classifierOnDeviceV2.enc model has been replaced by [mobile-classifier-model-1.0.0.enc](https://cdn.mobile.jumio.ai/android/model/mobile-classifier-model-1.0.0.enc).

#### Localization Keys

The following keys have been added
- `jumio_di_continue_with_provider`
- `jumio_di_doctype_digital_id_subheader`
- `jumio_di_external_instructions_one`
- `jumio_di_external_instructions_two`
- `jumio_di_external_instructions_three`
- `jumio_di_external_sub_header`
- `jumio_physical_id`
- `jumio_di_select_from_list_below`
- `jumio_di_unexpected_error_description`
- `jumio_di_unexpected_error_title`
- `jumio_di_use_another_id`
- `jumio_di_what_happens_next`
- `jumio_accessibility_button_close`

The following keys have been renamed:
- `jumio_idtype_subtitle_id` to `jumio_select_id_type`
- `jumio_di_vendor_selection_title` to `jumio_di_choose_digital_id`
- `jumio_di_back_to_document_selection` to `jumio_di_back_to_previous_step`

The following keys have been removed:
- `jumio_uploading_title`

#### Dependency Updates

| Name                      | Jumio Module        | Dependency                                            | old version | new version |
|---------------------------|---------------------|-------------------------------------------------------|-------------|-------------|
| Android Gradle Plugin     | all                 | `"com.android.library"`                               | 8.9.3       | 8.10.1      |
| CameraX Core              | camerax             | `"androidx.camera:camera-core"`                       | 1.4.2       | 1.5.3       |
| CameraX Lifecycle         | camerax             | `"androidx.camera:camera-lifecycle"`                  | 1.4.2       | 1.5.3       |
| CameraX View              | camerax             | `"androidx.camera:camera-view"`                       | 1.4.2       | 1.5.3       |
| Lifecycle Viewmodel       | defaultui           | `"androidx.lifecycle:lifecycle-viewmodel-ktx"`        | 2.9.3       | 2.10.0      |
| Lifecycle Savedstate      | defaultui           | `"androidx.lifecycle:lifecycle-viewmodel-savedstate"` | 2.9.3       | 2.10.0      |
| Lifecycle Livedata        | defaultui           | `"androidx.lifecycle:lifecycle-livedata-ktx"`         | 2.9.3       | 2.10.0      |
| Lifecycle Runtime Android | defaultui           | `"androidx.lifecycle:lifecycle-runtime-android"`      | 2.9.3       | 2.10.0      |
| Lifecycle Runtime Ktx     | defaultui           | `"androidx.lifecycle:lifecycle-runtime-Ktx"`          | 2.9.3       | 2.10.0      |
| Navigation UI             | defaultui           | `"androidx.navigation:navigation-ui-ktx"`             | 2.9.3       | 2.9.7       |
| Navigation Fragment       | defaultui           | `"androidx.navigation:navigation-fragment-ktx"`       | 2.9.3       | 2.9.7       |
| LiteRT                    | docfinder, liveness | `"com.google.ai.edge.litert:litert"`                  | 1.0.1       | 1.4.2       |
| LiteRT Metadata           | docfinder           | `"com.google.ai.edge.litert:litert-metadata"`         | 1.0.1       | 1.4.2       |
| JMRTD                     | nfc                 | `"org.jmrtd:jmrtd"`                                   | 0.8.2       | 0.8.5       |
| BouncyCastle              | nfc                 | `"org.bouncycastle:bcprov-jdk18on"`                   | 1.81        | 1.83        |

#### Jetifier and BouncyCastle 1.83 (NFC module)

⚠️&nbsp;&nbsp;If you still have Jetifier enabled (`android.enableJetifier=true` in your `gradle.properties`) and use the `com.jumio.android:nfc` module, your build will fail. BouncyCastle `bcprov-jdk18on:1.83` is a multi-release jar containing Java 25 (class major version 69) bytecode, which Jetifier cannot scan:

```
Jetifier failed to transform … bcprov-jdk18on-1.83.jar
java.lang.IllegalArgumentException - Unsupported class file major version 69
```

Add BouncyCastle to the Jetifier ignorelist in your `gradle.properties`:

```
android.jetifier.ignorelist=bcprov-jdk18on
```

This excludes the jar from Jetifier's transform step only - it stays on the classpath and ships in the APK unchanged, so NFC keeps working. The transform is a no-op anyway, since BouncyCastle does not reference any `android.support.*` APIs. See the [Jetifier Fails on BouncyCastle 1.83 (NFC module)](known_issues.md#jetifier-fails-on-bouncycastle-183-nfc-module) section in the known issues for details.

## 4.17.0

#### Public API Changes

- [`JumioTermsOfUse`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.termsofuse/-jumio-terms-of-use/index.html), [`JumioLookupResult`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-lookup-result/index.html), [`JumioLegalStatement`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-legal-statement/index.html) classes have been added
- Optional property `order` has been added to [`JumioCredentialInfo`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential-info/index.html)
- Property `lookupResult` of type [`JumioLookupResult`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-lookup-result/index.html) has been added to [`JumioIDCredential`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/index.html)
- Method [`userConsented(JumioLookupResult.JumioLegalStatement, Boolean)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-id-credential/user-consented.html) has been added to [`JumioIDCredential`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/index.html)
- [`onInitialized()`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-initialized.html) callback has been changed from ~~`onInitialized(credentials: List<JumioCredentialInfo>, consentItems: List<JumioConsentItem>?)`~~ to [`onInitialized(credentials: List<JumioCredentialInfo>, consentItems: List<JumioConsentItems>?, termsOfUse: JumioTermsOfUse?)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-initialized.html)

#### Instant Feedback Reject Reasons

The following reject reasons have been removed:

- BLACK_WHITE_COPY
- COLOR_PHOTOCOPY

#### Localizations Changes

The following keys have been added:
- `jumio_selfiedone_ID_Found`
- `jumio_loaders_almost_there`
- `jumio_selfiedone_continue`
- `jumio_loaders_finishing_up`
- `jumio_selfiedone_scan_ID_manually`
- `jumio_loaders_success`
- `jumio_loaders_this_will_take_a_moment`
- `jumio_selfiedone_we_found_your_ID`
- `jumio_loaders_working_on_it`

The following keys have been removed:
- `jumio_liveness_scanning_completed`
- `jumio_uploading_success`

## 4.16.0

#### Localizations Changes

The following keys have been removed:
- `iproov__accessibility_prompt_align_face`
- `iproov__accessibility_prompt_scanning`
- `iproov__error_camera`
- `iproov__error_camera_permission_denied`
- `iproov__error_capture_already_active`
- `iproov__error_device_not_supported`
- `iproov__error_face_detector`
- `iproov__error_multi_window_mode_unsupported`
- `iproov__error_network`
- `iproov__error_server`
- `iproov__error_unexpected_error`
- `iproov__failure_eyes_closed`
- `iproov__failure_face_too_close`
- `iproov__failure_face_too_far`
- `iproov__failure_misaligned_face`
- `iproov__failure_not_supported`
- `iproov__failure_obscured_face`
- `iproov__failure_sunglasses`
- `iproov__failure_too_bright`
- `iproov__failure_too_dark`
- `iproov__failure_too_much_movement`
- `iproov__failure_unknown`
- `iproov__failure_user_timeout`
- `iproov__progress_assessing_genuine_presence`
- `iproov__progress_assessing_liveness`
- `iproov__progress_confirming_identity`
- `iproov__progress_creating_identity`
- `iproov__progress_finding_face`
- `iproov__progress_identifying_face`
- `iproov__progress_loading`
- `iproov__progress_streaming`
- `iproov__prompt_align_face`
- `iproov__prompt_get_ready`
- `iproov__prompt_liveness_scan_completed`
- `iproov__prompt_too_bright`
- `iproov__prompt_too_close`
- `iproov__prompt_too_far`
  
The following keys have been added:
- `jumio_dv_clear_or_unedited`
- `jumio_dv_jpg_png_or_webp_format`
- `jumio_dv_no_transparency_or_watermarks`
- `jumio_dv_selected_the_right_file`
- `jumio_dv_take_a_photo_or_upload_a_file`
- `jumio_dv_upload_an_image`
- `jumio_dv_upload_from_photo_library`
- `jumio_choose_file_location`
- `jumio_dv_retry_selected_file_cannot_be_processed`
- `jumio_id_scan_guide_initial`

The following keys have been renamed
- `jumio_dv_retry_size_limit` to `jumio_dv_retry_maximum_size_limit_exceeded`
- `jumio_dv_confirm_file_info` to `jumio_dv_selected_the_right_file`

#### Customization Changes

The following customization color attributes have been removed:
- `<item name="iproov_filterForegroundColor">`
- `<item name="iproov_filterBackgroundColor">`
- `<item name="iproov_titleTextColor">`
- `<item name="iproov_promptTextColor">`
- `<item name="iproov_promptBackgroundColor">`
- `<item name="iproov_promptRoundedCorners">`
- `<item name="iproov_surroundColor">`
- `<item name="iproov_closeButton_colorTint">`
- `<item name="iproov_livenessAssurance_ovalStrokeColor">`
- `<item name="iproov_livenessAssurance_completedOvalStrokeColor">`
- `<item name="iproov_genuinePresenceAssurance_notReadyOvalStrokeColor">`
- `<item name="iproov_genuinePresenceAssurance_readyOvalStrokeColor">`

The following customization color attributes have been added:
  - `<item name="jumio_id_aligned_stroke">`
  - `<item name="jumio_id_unaligned_stroke">`

The following customization color attributes have been renamed:
  - `<item name="jumio_scanview_bubble_background">` to `<item name="jumio_scanview_background">`

#### Dependency Updates

| Name                    | Jumio Module    | Dependency                   | old version | new version |
| ----------------------- | --------------- | ---------------------------- | ----------- | ----------- |
| IProov                  | iproov          | `"com.iproov.sdk:iproov"`    | 9.1.2       | REMOVED     |
| IProov                  | iproov          | `"com.jumio.android:iproov"` | 4.15.0      | REMOVED     |

## 4.15.0

#### Deprecation Notice

⚠️&nbsp;&nbsp;The iProov dependency `com.jumio.android:iproov` is deprecated and will be removed in SDK v4.16.0.

#### Minimum SDK Version Changes

- minSdkVersion has been increased to 23. The SDK can still be integrated in Apps that support lower minSdkVersions - check if the [platform is supported](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/is-supported-platform.html) before initializing the JumioSDK, otherwise it will throw a [PlatformNotSupportedException](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.exceptions/-platform-not-supported-exception/index.html). The minSdkVersion change also internally changes how the apk is compressed which results in bigger apk files. Please see the [FAQ](integration_faq.md#minsdkversion-23-increases-apk-size) for that.

#### New SDK Localizations Added

The following keys have been added:

- `jumio_nfc_error_description_id`
- `jumio_nfc_error_description_other`
- `jumio_nfc_error_description_us`

#### Customization Changes

- The following customization color attributes have been added:
  - `<item name="jumio_nfc_phone_screen">`
  - `<item name="jumio_nfc_phone_notch">`
  - `<item name="jumio_nfc_chip_primary">`
  - `<item name="jumio_nfc_chip_secondary">`
  - `<item name="jumio_nfc_chip_glow">`
  - `<item name="jumio_nfc_pulse">`
- `jumio_nfc_id_foreground` customization color attribute has been removed.

#### Dependency Updates

⚠️&nbsp;&nbsp; Please note that the Android Gradle Plugin update is [officially recommended to fully support Android 16](https://developer.android.com/build/releases/gradle-plugin#api-level-support).

| Name                      | Jumio Module     | Dependency                                            | old version | new version |
| ------------------------- | ---------------- | ----------------------------------------------------- | ----------- | ----------- |
| Gradle Wrapper            | all              |                                                       | 8.9         | 8.11.1      |
| Android Gradle Plugin     | all              | `"com.android.library"`                               | 8.7.3       | 8.9.3       |
| Appcompat                 | all              | `"androidx.appcompat:appcompat"`                      | 1.7.0       | 1.7.1       |
| Coroutines                | core             | `"org.jetbrains.kotlinx:kotlinx-coroutines-android"`  | 1.8.1       | 1.10.2      |
| Concurrent                | core             | `"androidx.concurrent:concurrent-futures"`            | 1.2.0       | 1.3.0       |
| Material                  | core             | `"com.google.android.material:material"`              | 1.12.0      | 1.13.0      |
| LibYUV                    | core             | `"io.github.crow-misia.libyuv:libyuv-android"`        | 0.36.0      | 0.43.2      |
| Constraint Layout         | core, defaultui  | `"androidx.constraintlayout:constraintlayout"`        | 2.2.0       | 2.2.1       |
| Lifecycle Viewmodel       | defaultui        | `"androidx.lifecycle:lifecycle-viewmodel-ktx"`        | 2.8.7       | 2.9.3       |
| Lifecycle Savedstate      | defaultui        | `"androidx.lifecycle:lifecycle-viewmodel-savedstate"` | 2.8.7       | 2.9.3       |
| Lifecycle Livedata        | defaultui        | `"androidx.lifecycle:lifecycle-livedata-ktx"`         | 2.8.7       | 2.9.3       |
| Lifecycle Runtime Android | defaultui        | `"androidx.lifecycle:lifecycle-runtime-android"`      | ADDED       | 2.9.3       |
| Lifecycle Runtime Ktx     | defaultui        | `"androidx.lifecycle:lifecycle-runtime-Ktx"`          | ADDED       | 2.9.3       |
| Navigation UI             | defaultui        | `"androidx.navigation:navigation-ui-ktx"`             | 2.8.5       | 2.9.3       |
| Navigation Fragment       | defaultui        | `"androidx.navigation:navigation-fragment-ktx"`       | 2.8.5       | 2.9.3       |
| Browser                   | digital-identity | `"androidx.browser:browser"`                          | 1.8.0       | 1.9.0       |
| AndroidX Core KTX         | docfinder        | `"androidx.core:core-ktx"`                            | 1.15.0      | 1.17.0      |
| JMRTD                     | nfc              | `"org.jmrtd:jmrtd"`                                   | 0.7.42      | 0.8.2       |
| BouncyCastle              | nfc              | `"org.bouncycastle:bcprov-jdk18on"`                   | 1.78.1      | 1.81        |

## 4.14.0

#### Deprecation Notice

⚠️&nbsp;&nbsp;SDK 4.14.0 will be the last SDK version supporting Android 5 (API level 21). All subsequent SDK versions will require at least Android 6.0 "Marshmallow" (API level 23).

#### General

- Added support for Android 16.

#### LiteRT Notice

JumioSDK bundles LiteRT Version 1.0.1 which supports 16kb page size for ARM64-v8 but not x86_64. This is fine for the JumioSDK as only ARM cpus are supported. An update to 1.4.0 is currently not possible because the min API level of LiteRT 1.4.0 (25) exceeds the min API level of the Jumio SDK (21).
If you don't use LiteRT elsewhere in the code you can remove the x86 and x86_64 libraries by excluding them in the packagingOptions:

```gradle
android {
	...
	packagingOptions {
		...
		it.excludes.add("lib/x86_64/libtensorflowlite_jni.so")
		it.excludes.add("lib/x86/libtensorflowlite_jni.so")
	}
}
```

If your apps min API level is at least 25 then the LiteRT dependency can be overridden:

```gradle
implementation ("com.jumio.android:docfinder:4.14.0") {
	exclude group: 'com.google.ai.edge.litert', module: 'litert'
	exclude group: 'com.google.ai.edge.litert', module: 'litert-metadata'
}
implementation ("com.jumio.android:liveness:4.14.0") {
	exclude group: 'com.google.ai.edge.litert', module: 'litert'
}
implementation 'com.google.ai.edge.litert:litert:1.4.0'
implementation 'com.google.ai.edge.litert:litert-support:1.4.0'
```

#### Public API Changes

- Unused [`JumioFallbackReason.NO_DETECTION`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-fallback-reason/index.html) has been removed.
- `IMAGE_ANALYSIS` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)
- Property `SCANNING_ERROR` has been added to [`JumioFallbackReason`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-fallback-reason/index.html).
- The data parameter of [`JumioScanStep.ADDON_SCAN_PART`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-a-d-d-o-n_-s-c-a-n_-p-a-r-t/index.html) now contains [`JumioDocumentInfo`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-info/index.html).
- [`JumioDocumentInfo`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-info/index.html) contains the issuing country and the [`JumioDocumentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-type/index.html) of the initially scanned document .
- Function `getHelpAnimation()` has been deprecated in [`JumioScanPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html).

#### Android Manifest Changes

The following optional permission can be declared in the `AndroidManifest.xml` file, in order to improve fraud prevention:
`<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />`

#### New SDK Localizations Added

The following keys have been added:

- `jumio_id_scan_hint_error_fallback`
- `jumio_eidas_description`
- `jumio_eidas_login_header`
- `jumio_button_continue`
- `jumio_switched_to_back_camera`
- `jumio_switched_to_front_camera`
- `jumio_search_completed_for_country`
- `jumio_search_bar`
- `jumio_no_results_found`
- `jumio_clear_search`
- `jumio_current_issuing_country`
- `jumio_button`
- `jumio_accessibility_camera_switch_to_back`
- `jumio_accessibility_camera_switch_to_front`
- `jumio_select`
- `jumio_change_issuing_country`
- `jumio_current_issuing_country`
- `jumio_accessibility_scan_back`

The following keys have been removed:

- `jumio_nfc_retry_error_general`
- `iproov__prompt_pitch_too_high`
- `iproov__prompt_pitch_too_low`
- `iproov__prompt_roll_too_high`
- `iproov__prompt_roll_too_low`
- `iproov__prompt_yaw_too_high`
- `iproov__prompt_yaw_too_low`

#### Dependency Updates

| Name              | Jumio Module | Dependency                                 | old version | new version |
| ----------------- | ------------ | ------------------------------------------ | ----------- | ----------- |
| Concurrent        | core         | `"androidx.concurrent:concurrent-futures"` | ADDED       | 1.2.0       |
| CameraX Core      | camerax      | `"androidx.camera:camera-core"`            | 1.4.1       | 1.4.2       |
| CameraX Lifecycle | camerax      | `"androidx.camera:camera-lifecycle"`       | 1.4.1       | 1.4.2       |
| CameraX View      | camerax      | `"androidx.camera:camera-view"`            | 1.4.1       | 1.4.2       |

## 4.13.0

#### Public API Changes

- The data parameter of [`JumioScanStep.ADDON_SCAN_PART`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/-a-d-d-o-n_-s-c-a-n_-p-a-r-t/index.html) now contains [`JumioDocumentInfo`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-info/index.html)
- [`JumioDocumentInfo`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-info/index.html) contains the issuing country and the [`JumioDocumentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document-type/index.html) of the initially scanned document
- Function `getHelpAnimation()` has been deprecated in [`JumioScanPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html)

#### New SDK Localizations Added

The following keys have been added:

- `jumio_nfc_id_retry_tag_lost`
- `jumio_nfc_id_description`
- `jumio_nfc_id_header_start`

#### Dependency Updates

| Name                  | Jumio Module    | Dependency                                            | old version | new version |
| --------------------- | --------------- | ----------------------------------------------------- | ----------- | ----------- |
| Gradle Wrapper        | all             |                                                       | 8.7         | 8.9         |
| Android Gradle Plugin | all             | `"com.android.library"`                               | 8.6.1       | 8.7.3       |
| Kotlin Plugin         | all             | `"org.jetbrains.kotlin.android"`                      | 2.0.0       | 2.1.0       |
| Kotlin Stdlib         | all             | `"org.jetbrains.kotlin:kotlin-stdlib-jdk8"`           | 2.0.0       | 2.1.0       |
| Annotation            | core            | `"androidx.annotation:annotation-jvm"`                | 1.8.2       | 1.9.1       |
| Navigation UI         | core            | `"androidx.navigation:navigation-ui-ktx"`             | 2.8.1       | 2.8.5       |
| Navigation Fragment   | core            | `"androidx.navigation:navigation-fragment-ktx"`       | 2.8.1       | 2.8.5       |
| Constraint Layout     | core, defaultui | `"androidx.constraintlayout:constraintlayout"`        | 2.1.4       | 2.2.0       |
| CameraX Core          | camerax         | `"androidx.camera:camera-core"`                       | 1.3.4       | 1.4.1       |
| CameraX Lifecycle     | camerax         | `"androidx.camera:camera-lifecycle"`                  | 1.3.4       | 1.4.1       |
| CameraX View          | camerax         | `"androidx.camera:camera-view"`                       | 1.3.4       | 1.4.1       |
| AndroidX Core KTX     | docfinder       | `"androidx.core:core-ktx"`                            | 1.13.1      | 1.15.0      |
| CameraX Camera2       | camerax         | `"androidx.camera:camera-camera2"`                    | 1.3.4       | 1.4.1       |
| Lifecycle Viewmodel   | defaultui       | `"androidx.lifecycle:lifecycle-viewmodel-ktx"`        | 2.8.6       | 2.8.7       |
| Lifecycle Savedstate  | defaultui       | `"androidx.lifecycle:lifecycle-viewmodel-savedstate"` | 2.8.6       | 2.8.7       |
| Lifecycle Livedata    | defaultui       | `"androidx.lifecycle:lifecycle-livedata-ktx"`         | 2.8.6       | 2.8.7       |
| Datadog               | datadog         | `"com.jumio.android:datadog"`                         | 4.12.1      | REMOVED     |

#### Dependency Management

- Bill of Material (BOM) support for simplified dependency management and versioning has been added.

```groovy
dependencies {
		implementation platform("com.jumio.android:bom:4.13.0")
		implementation "com.jumio.android:core"
		implementation "com.jumio.android:barcode-mlkit"
		implementation "com.jumio.android:camerax"
		implementation "com.jumio.android:defaultui"
		implementation "com.jumio.android:digital-identity"
		implementation "com.jumio.android:docfinder"
		implementation "com.jumio.android:iproov"
		implementation "com.jumio.android:liveness"
		implementation "com.jumio.android:nfc"
}
```

#### Customization Changes

- Custom NFC parent theme has been renamed from ~~`Nfc.Customization`~~ to `Jumio.Nfc.Customization`
- The following customization color attributes have been renamed:
  - ~~`<item name="nfc_passport_cover">`~~ to `<item name="jumio_nfc_passport_cover">`
  - ~~`<item name="nfc_passport_page_dark">`~~ to `<item name="jumio_nfc_passport_page_dark">`
  - ~~`<item name="nfc_passport_page_light">`~~ to `<item name="jumio_nfc_passport_page_light">`
  - ~~`<item name="nfc_passport_foreground">`~~ to `<item name="jumio_nfc_passport_foreground">`
  - ~~`<item name="nfc_phone_background">`~~ to `<item name="jumio_nfc_phone_background">`

## 4.12.1

No backward incompatible changes

## 4.12.0

This version adds support for Android 15 and 16KB page size for native libraries.

#### Public API Changes

- Property `LINEFINDER` was unused and has been removed from [`JumioScanMode`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html)
- Property `JUMIO_PREMIUM` has been added to [`JumioScanMode`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html)
- Optional parameter `url` has been added to [`JumioDigitalDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document/index.html)
- `INVALID_CERTIFICATE` has been added to [`JumioRejectReason`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.reject/-jumio-reject-reason/index.html)
- Function `detach()` has been added to [`JumioScanView`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-scan-view/index.html)

#### Dependency Updates

- Tensorflow Lite dependencies have been updated to LiteRT - see https://developers.googleblog.com/en/tensorflow-lite-is-now-litert/ for more infos.

| Name                     | Jumio Module        | Dependency                                                      | old version | new version |
| ------------------------ | ------------------- | --------------------------------------------------------------- | ----------- | ----------- |
| Android Gradle Plugin    | all                 | `"com.android.library"`                                         | 8.2.2       | 8.6.1       |
| Kotlin Plugin            | all                 | `"org.jetbrains.kotlin.android"`                                | 1.9.24      | 2.0.0       |
| Kotlin Stdlib            | all                 | `"org.jetbrains.kotlin:kotlin-stdlib-jdk8"`                     | 1.9.24      | 2.0.0       |
| Annotation               | core                | `"androidx.annotation:annotation-jvm"`                          | 1.8.0       | 1.8.2       |
| Navigation UI            | core                | `"androidx.navigation:navigation-ui-ktx"`                       | 2.7.7       | 2.8.1       |
| Navigation Fragment      | core                | `"androidx.navigation:navigation-fragment-ktx"`                 | 2.7.7       | 2.8.1       |
| LibYUV                   | core                | `"io.github.crow-misia.libyuv:libyuv-android"`                  | 0.34.0      | 0.36.0      |
| CameraX Core             | camerax             | `"androidx.camera:camera-core"`                                 | 1.3.3       | 1.3.4       |
| CameraX Lifecycle        | camerax             | `"androidx.camera:camera-lifecycle"`                            | 1.3.3       | 1.3.4       |
| CameraX View             | camerax             | `"androidx.camera:camera-view"`                                 | 1.3.3       | 1.3.4       |
| CameraX Camera2          | camerax             | `"androidx.camera:camera-camera2"`                              | 1.3.3       | 1.3.4       |
| Lifecycle Viewmodel      | defaultui           | `"androidx.lifecycle:lifecycle-viewmodel-ktx"`                  | 2.8.1       | 2.8.6       |
| Lifecycle Savedstate     | defaultui           | `"androidx.lifecycle:lifecycle-viewmodel-savedstate"`           | 2.8.1       | 2.8.6       |
| Lifecycle Livedata       | defaultui           | `"androidx.lifecycle:lifecycle-livedata-ktx"`                   | 2.8.1       | 2.8.6       |
| Tensorflow Lite          | docfinder, liveness | `"org.tensorflow:tensorflow-lite"`                              | 2.16.1      | REMOVED     |
| LiteRT                   | docfinder, liveness | `"com.google.ai.edge.litert:litert"`                            | ADDED       | 1.0.1       |
| Tensorflow Lite Metadata | docfinder           | `"org.tensorflow:tensorflow-lite-metadata"`                     | 0.4.4       | REMOVED     |
| LiteRT Metadata          | docfinder           | `"com.google.ai.edge.litert:litert-metadata"`                   | ADDED       | 1.0.1       |
| IProov                   | iproov              | `"com.iproov.sdk:iproov"`                                       | 9.1.1       | 9.1.2       |
| JMRTD                    | nfc                 | `"org.jmrtd:jmrtd"`                                             | 0.7.41      | 0.7.42      |
| Scube                    | nfc                 | `"net.sf.scuba:scuba-sc-android"`                               | 0.0.25      | 0.0.26      |
| BouncyCastle             | nfc                 | `"org.bouncycastle:bcprov-jdk18on"`                             | 1.77        | 1.78.1      |
| MLKit Barcode            | barcode-mlkit       | `"com.google.android.gms:play-services-mlkit-barcode-scanning"` | 18.3.0      | 18.3.1      |

#### Packaging Options

Multiple third party android libraries include the same meta files which will result in duplicates files during the build.
Please see the [FAQ](integration_faq.md#packaging-options) section for that.

#### SDK Localizations Changes

##### New strings

| new                                   |
| ------------------------------------- |
| `jumio_liveness_prompt_keep_centered` |
| `jumio_liveness_prompt_keep_still`    |
| `jumio_liveness_prompt_keep_upright`  |
| `jumio_liveness_prompt_tilt_down`     |
| `jumio_liveness_prompt_tilt_left`     |
| `jumio_liveness_prompt_tilt_right`    |
| `jumio_liveness_prompt_tilt_up`       |
| `jumio_liveness_scanning_completed`   |

##### Renamed strings

| old                                          | new                                          |
| -------------------------------------------- | -------------------------------------------- |
| `jumio_liveness_prompt_success_another_shot` | `jumio_liveness_prompt_success_another_scan` |
| `jumio_liveness_prompt_too_close`            | `jumio_liveness_prompt_move_away`            |
| `jumio_error_case_ocr_failed`                | `jumio_error_case_scanning_not_possible`     |

## 4.11.0

#### Public API Changes

- `TILT` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html) alongside with [`JumioTiltState`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.core/-jumio-tilt-state/index.html)
- `NEXT_POSITION` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)
- `IMAGE_TAKEN` [`JumioScanStep`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/index.html) is again sent only when the side/part is completed. If you have logic based on `NEXT_PART` or `PROCESSING`, it is not affected by this change.
- 'UNSUPPORTED_DOCUMENT' has been added to [`JumioRejectReason`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.reject/-jumio-reject-reason/index.html)

#### Dependency Updates

| Name                 | Jumio Module | Dependency                                            | old version | new version |
| -------------------- | ------------ | ----------------------------------------------------- | ----------- | ----------- |
| Annotation           | core         | `"androidx.annotation:annotation-jvm"`                | 1.7.1       | 1.8.0       |
| Appcompat            | core         | `"androidx.appcompat:appcompat"`                      | 1.6.1       | 1.7.0       |
| Material             | core         | `"com.google.android.material:material"`              | 1.11.0      | 1.12.0      |
| Coroutines           | core         | `"org.jetbrains.kotlinx:kotlinx-coroutines-android"`  | 1.8.0       | 1.8.1       |
| LibYUV               | core         | `"io.github.crow-misia.libyuv:libyuv-android"`        | 0.33.0      | 0.34.0      |
| CameraX Core         | camerax      | `"androidx.camera:camera-core"`                       | 1.3.1       | 1.3.3       |
| CameraX Lifecycle    | camerax      | `"androidx.camera:camera-lifecycle"`                  | 1.3.1       | 1.3.3       |
| CameraX View         | camerax      | `"androidx.camera:camera-view"`                       | 1.3.1       | 1.3.3       |
| CameraX Camera2      | camerax      | `"androidx.camera:camera-camera2"`                    | 1.3.1       | 1.3.3       |
| Lifecycle Viewmodel  | defaultui    | `"androidx.lifecycle:lifecycle-viewmodel-ktx"`        | 2.7.0       | 2.8.1       |
| Lifecycle Savedstate | defaultui    | `"androidx.lifecycle:lifecycle-viewmodel-savedstate"` | 2.7.0       | 2.8.1       |
| Lifecycle Livedata   | defaultui    | `"androidx.lifecycle:lifecycle-livedata-ktx"`         | 2.7.0       | 2.8.1       |
| IProov               | iproov       | `"com.iproov.sdk:iproov"`                             | 9.0.4       | 9.1.1       |

#### Customization Changes

- `jumio_divider_color` has been added to customize the color of list dividers
- See also: [Jumio sample `styles.xml`](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/src/main/res/values/styles.xml)

#### New SDK Localizations Added

The following keys have been added:

- `jumio_id_scan_guide_photo_side_tilt`
- `jumio_id_scan_prompt_tilt_less`
- `jumio_id_scan_prompt_tilt_more`

## 4.10.0

#### Public API Changes

- `IMAGE_TAKEN` [`JumioScanStep`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/index.html) is now sent for each image required for a specified side. This is different to previous behavior where `IMAGE_TAKEN` was sent only when the side/part was completed. Please make sure to align any logic based on `IMAGE_TAKEN` to the new behavior. `NEXT_PART` or `PROCESSING` might be used to identify when a side/part has been finished.
- `FLASH` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)

#### New SDK Localizations Added

SDK Translations for the languages Serbian (Cyrillic) and Serbian (Latin) have been added.

#### Dependency Updates

- Tensorflow lite update: ~~`"org.tensorflow:tensorflow-lite:2.10.0"`~~ is replaced by `"org.tensorflow:tensorflow-lite:2.16.1"`.
- `"com.jumio.android:camerax"` is added as a transitive dependency to `"com.jumio.android:liveness"`

## 4.9.1

No backward incompatible changes

## 4.9.0

#### Compile SDK Version Changes

- **⚠️&nbsp;&nbsp;The minimum required compile SDK version for SDK `4.9.0` is `34`.**
- With these changes also Gradle 8 is **required** to build your application successfully. The [Android Gradle plugin Upgrade Assistant](https://developer.android.com/build/agp-upgrade-assistant) can be helpful conducting the upgrade.
- Troubleshooting:
  - In case you are experiencing some errors when trying to build your release application, make sure to replace all occurrences of `tasks.whenTaskAdded` with `tasks.configureEach`

#### Public API Changes

- Function `getHelpAnimation()` has been deprecated for all face help animation instances in [`JumioScanPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html)
- Property `parts` has been added to [`JumioPhysicalDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-physical-document/index.html)
- Property `idSubType` has been added to [`JumioIDResult`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-i-d-result/index.html)
- Removed retry code `USER_BACK` from `JumioRetryReasonGeneric`.
- Added `JumioRetryReasonFace` to represent new retry codes for face scanning:
  - GENERIC = 3001
  - TOO_MUCH_MOVEMENT = 3002
  - LIGHTING_TOO_BRIGHT = 3003
  - LIGHTING_TOO_DARK = 3004
  - EYES_CLOSED = 3005
  - OBSCURED_FACE = 3006
  - MULTIPLE_FACES = 3007
  - SUNGLASSES = 3008
- Class `JumioDataCredential` has been removed
- Property `DEVICE_RISK` has been removed from [`JumioScanMode`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html)
- Property `DEVICE_RISK` has been removed from [`JumioCredentialPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html)

#### Dependency Updates

- Removed Devicerisk dependency: ~~`implementation "com.jumio.android:devicerisk:4.8.1"`~~
- IProov update: ~~`"com.iproov.sdk:iproov:8.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:9.0.3"`. Please note that this update also includes a major UI/UX upgrade.

#### Customization Changes

- The following customization color attributes have been added:

  - `<item name="jumio_face_primary">`
  - `<item name="jumio_face_secondary">`
  - `<item name="jumio_face_outline">`
  - `<item name="jumio_face_success">`
  - `<item name="jumio_image_border">`
  - `<item name="jumio_bubble_outline_selected">`

- Customization attribute ~~`<item name="jumio_face_animation_customization">`~~ has been removed

## 4.8.2

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:8.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:8.5.2"`

## 4.8.1

No backward incompatible changes

## 4.8.0

No backward incompatible changes

## 4.7.2

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:8.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:8.5.2"`

## 4.7.1

No backward incompatible changes

## 4.7.0

#### Public API Changes

- `rawBarcodeData` has been removed from [`JumioIDResult`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-i-d-result/index.html)
- `LEGAL_HINT` has been removed from [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)
- `giveDataDogConsent` has been removed from [`JumioSDK`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/index.html)

#### Dependency Updates

- Removed MRZ dependency: ~~`implementation "com.jumio.android:mrz:4.6.0"`~~
- Removed Linefinder dependency: ~~`implementation "com.jumio.android:linefinder:4.6.0"`~~
- Removed Barcode dependency: ~~`implementation "com.jumio.android:barcode:4.6.0"`~~
- Datadog update: ~~`"com.datadoghq:dd-sdk-android:1.19.3"`~~ is replaced by `"com.datadoghq:dd-sdk-android-rum:2.0.0"` - If Datadog is used in a dynamic feature module please have a look at [this known issue](known_issues.md#datadog-in-dynamic-feature-modules).

#### Custom UI Changes

- The platform check has been moved from the [`JumioSDK`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/index.html) constructor to the [`JumioController`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/index.html) constructor. In case the platform is not supported there will be a non-retryable F000001 [`JumioError`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.error/-jumio-error/index.html) delivered in [`JumioControllerInterface$onError`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-error.html) instead of a [`PlatformNotSupportedException`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.exceptions/-platform-not-supported-exception/index.html) being thrown. Please also make sure to check [`isSupportedPlatform`](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#device-supported-check) before using the SDK.

#### Localization Changes

- SDK string translations for Brazilian Portuguese (pt-rBR) have been added

#### Customization Changes

- Customization attribute ~~`<item name="jumio_face_animation_background">`~~ has been removed

#### Documentation Changes

- Functions `persist` and `stop` in [`JumioController`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.controller/-jumio-controller/index.html) need to be called independently from `isComplete` as long as the workflow is not yet finished or canceled.

## 4.6.2

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:8.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:8.5.2"`

## 4.6.1

No backward incompatible changes

## 4.6.0

#### Public API Changes

- `JUMIO_LIVENESS` has been added to [`JumioScanMode`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-mode/index.html)
- `MOVE_FACE_CLOSER` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)
- `FACE_TOO_CLOSE` has been added to [`JumioScanUpdate`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-update/index.html)

#### Customization Changes

- A new customization theme `<item name="jumio_face_animation_customization">@style/CustomFaceHelp</item>` has been added to help customize the newly added Jumio Liveness solution. This style includes the following attributes:

  - `<item name="jumio_face_animation_foreground">`
  - `<item name="jumio_face_animation_background">`

- The following customization attributes have been added to `@style/CustomOverlay` theme:

  - `<item name="jumio_scanOverlay">`
  - `<item name="jumio_scanOverlay_livenessStrokeAnimation">`
  - `<item name="jumio_scanOverlay_livenessStrokeAnimationCompleted>`

- The following customization attributes have been removed from `@style/CustomIproov` theme:

  - ~~`<item name="iproov_animation_foreground">`~~
  - ~~`<item name="iproov_animation_background">`~~

- See also: [Jumio sample `styles.xml`](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/src/main/res/values/styles.xml)

#### Dependency Updates

- NEW Liveness dependency: `implementation "com.jumio.android:liveness:4.6.0"`

## 4.5.2

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:8.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:8.5.2"`

## 4.5.1

No backward incompatible changes

## 4.5.0

#### Public API Changes

- ~~`onPause`~~ has been removed from [JumioScanPart](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html)

- [`JumioError.code`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.error/-jumio-error/index.html) format updated from `[A][x][yyyy]` to `[A][xx][yyyy]`

- Property [`countries`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/countries.html) of `JumioIDCredential` has been deprecated. Instead the following new property and functions have been added:

  - [`JumioIDCredential.supportedCountries`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/supported-countries.html)
  - [`JumioIDCredential.getPhysicalDocumentsForCountry(countryCode:)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/get-physical-documents-for-country.html)
  - [`JumioIDCredential.getDigitalDocumentsForCountry(countryCode:)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-i-d-credential/get-digital-documents-for-country.html)

- [`JumioDeepLinkHandler`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.util/-jumio-deep-link-handler/index.html) has been added

- [`JumioPhysicalDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-physical-document/index.html) and [`JumioDigitalDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-digital-document/index.html) have been added

- [`JumioDocument`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.document/-jumio-document/index.html) type has changed to interface. (Original `JumioDocument` class has been replaced by `JumioPhysicalDocument`)

- `DIGITAL` has been added in [`JumioCredentialPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html)

- `DIGITAL_IDENTITY_VIEW` and `THIRD_PARTY_VERIFICATION` have been added in [`JumioScanStep`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/index.html)

- [`JumioRetryReasonDigitalIdentity`](https://jumio.github.io/mobile-sdk-android/jumio-digital-identity/com.jumio.sdk.retry/-jumio-retry-reason-digital-identity/index.html) has been added

- [`JumioConsentItem`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.consent/-jumio-consent-item/index.html) class and [`JumioConsentType`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-consent-type/index.html) enum have been added

- [`onInitialized()`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-initialized.html) callback has been changed from ~~`onInitialized(credentials: List<JumioCredentialInfo>, policyUrl: String?)`~~ to [`onInitialized(credentials: List<JumioCredentialInfo>, consentItems: List<JumioConsentItems>?)`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/on-initialized.html)
  - Please refer to the [Consent Handling section](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#consent-handling) in our integration guide for more details.

#### Localization Keys

The following keys have been added to `strings.xml`:

- jumio_idtype_di
- jumio_di_vendor_selection_title
- jumio_di_retry_unknown
- jumio_di_retry_third_party_verification_error
- jumio_di_retry_service_error
- jumio_di_retry_expired
- jumio_di_back_to_document_selection

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:8.0.3"`~~ is replaced by `"com.iproov.sdk:iproov:8.3.1"`

## 4.4.2

No backward incompatible changes

## 4.4.1

No backward incompatible changes

## 4.4.0

#### Public API Changes

- `credentialParts` property of [`JumioCredential` class](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.credentials/-jumio-credential/credential-parts.html) has been changed from `ArrayList<JumioCredentialPart>` to `List<JumioCredentialPart>`
- [`JumioConfirmationHandler`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-confirmation-handler/index.html) has been added. Attach a [JumioScanPart](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html) to this class to retrieve all accepted images and render them to [`JumioConfirmationView`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-confirmation-view/index.html) objects for confirmation.
- [`JumioRejectHandler`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-reject-handler/index.html) has been added. Attach a [JumioScanPart](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/index.html) to this class to retrieve all rejected images and render them to [`JumioRejectView`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-reject-view/index.html) objects for retaking.
- Functions in [`JumioConfirmationView`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-confirmation-view/index.html) have been moved to [`JumioConfirmationHandler`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-confirmation-handler/index.html).
- Functions in [`JumioRejectView`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-reject-view/index.html) have been moved to [`JumioRejectHandler`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.handler/-jumio-reject-handler/index.html)
- `MULTIPART` has been added in [`JumioCredentialPart`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html) as a new Autocapture scan part: Instead of having a single scan part for all parts of a document (front, back), there is now a single `MULTIPART` scan part that combines the two. Within this scan part all needed parts of a document are captured at once.
- `NEXT_PART` has been added in [`JumioScanStep`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-scan-step/index.html): This scan step shows that the previous part has been captured and the next one can be started (e.g. frontside has been captured, now switch to the backside of the document)

#### Customization Updates

- Attributes changed and added to [`Iproov.Customization` theme](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/styles.xml#L95)

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:7.5.0"`~~ is replaced by `"com.iproov.sdk:iproov:8.0.3"`

## 4.3.1

No backward incompatible changes

## 4.3.0

#### Minimum SDK Version Changes

- minSdkVersion has been increased to 21. The SDK can still be integrated in Apps that support lower minSdkVersions - check if the [platform is supported](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk/-jumio-s-d-k/-companion/is-supported-platform.html) before initializing the JumioSDK, otherwise it will throw a [PlatformNotSupportedException](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.exceptions/-platform-not-supported-exception/index.html).

#### Dependency Updates

- IProov update: ~~`"com.iproov.sdk:iproov:7.2.0"`~~ is replaced by `"com.iproov.sdk:iproov:7.5.0"`

#### Public API Changes

- Document Verification is now supported. Please check the [Integration Guide](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#jumio-document-credential) for more information.
- ~~`JumioCameraPosition`~~ from package `com.jumio.sdk.enums` in `com.jumio.sdk:core` is replaced by `JumioCameraFacing`
- `JumioAcquireMode` has been added to package `com.jumio.sdk.enums` in `com.jumio.sdk:core`, containing fields `FILE` and `CAMERA`
- [`JumioDataCredential` class](integration_guide.md/#jumio-data-credential) has been added for handling of Device Fingerprinting
- [`JumioDocumentCredential` class](integration_guide.md/#jumio-document-credential) has been added for Document Verification handling

## 4.2.1

No backward incompatible changes

## 4.2.0

#### Public API Changes

- In [JumioControllerInterface](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.interfaces/-jumio-controller-interface/index.html) the signature of function `onInitialized` has been changed. Parameter `credentials` has been changed from `ArrayList<JumioCredentialInfo>` to `List<JumioCredentialInfo>`
- In [JumioResult](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.result/-jumio-result/index.html) field `credentialInfos` has been changed from `ArrayList<JumioCredentialInfo>?` to `List<JumioCredentialInfo>?`
- `JumioScanSide` from package `com.jumio.sdk.enums` in `com.jumio.sdk:core` has been renamed to [JumioCredentialPart](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.enums/-jumio-credential-part/index.html)

#### Dependency Updates

- NEW Autocapture dependency (Beta): `implementation "com.jumio.android:docfinder:4.2.0"`

#### Customization Updates

- Boolean `iproov_floating_prompt_enabled` has been added to [`Iproov.Customization` theme](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/styles.xml#L84)
- Color attribute ~`iproov_footerTextColor` has been replaced with `iproov_promptTextColor` in [`Iproov.Customization` theme](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/styles.xml#L84)

#### Deprecation Notice

⚠️&nbsp;&nbsp;SDK 4.2.0 will be the last SDK version supporting Android 4.4 (API level 19). All subsequent SDK versions will require at least Android 5.0 "Lollipop" (API level 21).

## 4.1.1

No backward incompatible changes

## 4.1.0

#### Dependency Updates

- NEW Datadog dependency (optional): `implementation "com.jumio.android:datadog:4.1.0"`

- IProov update: ~~`"com.iproov.sdk:iproov:7.0.3"`~~ is replace by `"com.iproov.sdk:iproov:7.2.0"`

#### Customization Updates

- Dark mode is now available. DefaultUI will switch automatically if system settings of the user device change.
- Dark mode can also be customized by creating a custom theme, utilizing `values-night` in the resources directory.

#### Instant Feedback Reject Reasons

Added Instant Feedback functionality to give more granular user feedback with new reject reasons:

- BLACK_WHITE_COPY
- COLOR_PHOTOCOPY
- DIGITAL_COPY
- NOT_READABLE
- NO_DOC
- MISSING_BACK
- MISSING_FRONT
- BLURRY
- MISSING_PART_DOC
- DAMAGED_DOCUMENT
- HIDDEN_PART_DOC
- GLARE

## 4.0.0

#### Authentication

ℹ️&nbsp;&nbsp;**As of version 4.0.0 and onward, the SDK can only be used in combination with Jumio KYX or Jumio API v3. API v2 as well as using API token and secret to authenticate against the SDK will no longer be compatible.**

#### Dependency Updates

- The repository declaration for ~~`jcenter()`~~ is replaced with `mavenCentral()` as [JFrog will be shutting down JCenter](https://blog.gradle.org/jcenter-shutdown)

- Additionally to that, the repository declaration `gradlePluginPortal()` was added to mitigate the gradle build plugin dependency not being migrated to `mavenCentral()` yet.

- All AndroidX dependencies are now declared in the `.pom` files and resolved transitively by Gradle. The following AndroidX dependencies are used in the SDK, but **do not** have to be declared manually in the `build.gradle` anymore:

  - `"androidx.appcompat:appcompat:1.3.0"`
  - `"com.google.android.material:material:1.4.0"`
  - `"androidx.constraintlayout:constraintlayout:2.1.1"`
  - `"androidx.lifecycle:lifecycle-livedata-ktx:2.3.1"`
  - `"androidx.lifecycle:lifecycle-viewmodel-ktx:2.3.1"`
  - `"androidx.lifecycle:lifecycle-viewmodel-savedstate:2.3.1"`
  - `"androidx.lifecycle:lifecycle-extensions:2.2.0"`
  - `"androidx.recyclerview:recyclerview:1.2.1"`
  - `"androidx.fragment:fragment-ktx:1.3.6"`
  - `"androidx.navigation:navigation-ui-ktx:2.3.5"`

- The Jumio liveness dependency `"com.iproov.sdk:iproov:7.0.3"` is referenced as a transitive dependency within the iProov module and does not have to be added manually to the `build.gradle` anymore.

- `kotlin-parcelize` and `kotlinx-serialization` plugins, as well as the following dependencies have been removed:
  - `org.jetbrains.kotlinx:kotlinx-serialization-core:1.0.0`
  - `org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0`

#### Initialization Updates

- ~~`apiToken`~~ and ~~`apiSecret`~~ are replaced by one-time `sdk.token`

#### Default UI Updates

As of SDK version 4.0.0, a lot of SDK parameters that previously could be set in the actual code are now contained within and provided by the `sdk.token`. These parameters have to be configured beforehand, during the API call that requests the token.

Please refer to the [Configuration section](integration_guide.md#configuration) of our integration guides for a detailed description of all Default UI changes and updates.

Information about which user journey (ID Verification, Selfie Verification, Authentication, ...) the SDK is going to provide now also has to be specified during the API call that request the `sdk.token`.

For more details on individual Jumio workflows, please refer to [Workflow Descriptions](https://github.com/Jumio/implementation-guides/blob/master/api-guide/workflow_descriptions.md) in our guides.

#### Custom UI Updates

As of SDK version 4.0.0, Custom UI workflow has been completely restructured.

Please refer to the [Custom UI section](integration_guide.md#custom-ui) of our integration guides for a detailed description of all Custom UI changes and updates.

## 3.9.5

No backward incompatible changes

## 3.9.4

- IProov update: ~~`"com.iproov.sdk:iproov:6.4.1"`~~ is replaced by `"com.iproov.sdk:iproov:6.4.3"`.

## 3.9.3

No backward incompatible changes

## 3.9.2

#### Dependency Changes

- IProov update: ~~`"com.iproov.sdk:iproov:6.3.1"`~~ is replaced by `"com.iproov.sdk:iproov:6.4.1"`. This version improves conversion and offers additional customization options.

#### Customization Updates

- Added additional customization attributes to the IProov theme `Iproov.Customization`:
  - `iproov_headerTextColor`
  - `iproov_headerBackgroundColor`
  - `iproov_footerTextColor`
  - `iproov_footerBackgroundColor`
  - `iproov_livenessScanningTintColor`
  - `iproov_progressBarColor`

## 3.9.1

#### Dependency Changes

- IProov update: ~~`"com.iproov.sdk:iproov:6.3.0"`~~ is replaced by `"com.iproov.sdk:iproov:6.3.1"`. This version fixes cross-dependency problems with okhttp 4.x

#### Customization Updates

- Added attribute `iproov_backgroundColor` to the IProov theme `Iproov.Customization` to allow customization of the IProov background color during scanning.

## 3.9.0

#### Dependency Changes

- IProov update: ~~`"com.iproov.sdk:iproov:6.1.0"`~~ is replaced by "com.iproov.sdk:iproov:6.3.0"

- Room update: ~~`"androidx.room:room-runtime:2.2.5"`~~ is replaced by "androidx.room:room-runtime:2.2.6"

- AndroidX Kotlin Extension update: ~~`"androidx.core:core-ktx:1.3.1"`~~ is replaced by `"androidx.core:core-ktx:1.3.2"`

- JMRTD update: ~~`"org.jmrtd:jmrtd:0.7.19"`~~ is replaced by `"org.jmrtd:jmrtd:0.7.24"`

- Bouncycastle update: ~~`"org.bouncycastle:bcprov-jdk15on:1.65"`~~ is replaced by `"org.bouncycastle:bcprov-jdk15on:1.67"`

- REMOVE LocalBroadcastManager ~~`"androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"`~~

- REPLACE ~~`apply plugin: 'kotlin-android-extensions`~~ with `apply plugin: kotlin-parcelize`. The extensions plugin has been [deprecated by Google](https://goo.gle/kotlin-android-extensions-deprecation). The parcelize functionality has been extracted to a separate plugin.

#### Public API Changes

- `setEnableEMRTD(boolean enable)` has been removed from [NetverifySDK](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html)

- `recreate(Activity rootActivity)` has been added to [NetverifySDK](https://jumio.github.io/mobile-sdk-android/com/jumio/MobileSDK.html#recreate-android.app.Activity-) - this needs to be called in case the hosting activity that was passed in [`create`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#create-android.app.Activity-java.lang.String-java.lang.String-com.jumio.core.enums.JumioDataCenter-) is recreated.

#### Custom UI Changes

- [`NetverifyCustomSDKInterface$onNetverifyFinished`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKInterface.html#onNetverifyFinished-android.os.Bundle-) all parameters were replaced with a Bundle. The keys are defined as constants in the [`NetverifySDK.EXTRA_SCAN_REFERENCE`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html):
- [`EXTRA_SCAN_REFERENCE`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#EXTRA_SCAN_REFERENCE)
- [`EXTRA_ACCOUNT_ID`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#EXTRA_ACCOUNT_ID)
- [`EXTRA_SCAN_DATA`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#EXTRA_SCAN_DATA)

- [`NetverifyCustomSDKInterface$onNetverifyError`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKInterface.html#onNetverifyError-java.lang.String-java.lang.String-boolean-java.lang.String-java.lang.String-) added an optional parameter `accountId`

- New methods for handling host activity lifecycle changes have been added:

  - `recreate(Activity activity, NetverifyCustomSDKInterface netverifyCustomSDKInterface)` has been added to [NetverifyCustomSDKController](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKController.html#recreate-android.app.Activity-com.jumio.nv.custom.NetverifyCustomSDKInterface-) - this needs to be called in case the hosting activity is recreated.

  - `recreate(NetverifyCustomScanView scanView, NetverifyCustomConfirmationView confirmationView, NetverifyCustomScanInterface netverifyCustomScanInterface)` has been added to [NetverifyCustomScanPresenter](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanPresenter.html#recreate-com.jumio.nv.custom.NetverifyCustomScanView-com.jumio.nv.custom.NetverifyCustomConfirmationView-com.jumio.nv.custom.NetverifyCustomScanInterface-) - this needs to be called in case the hosting activity is recreated.

- The initialization and start of scan presenters has been split. This allows displaying a help view with the help animation prior to starting the scan presenter:

  - `startScanForPart(ScanSide scanSide, NetverifyCustomScanView scanView, NetverifyCustomConfirmationView confirmationView, NetverifyCustomScanInterface scanViewInterface` has been replaced with `initScanForPart(ScanSide scanSide, NetverifyCustomScanView scanView, NetverifyCustomConfirmationView confirmationView, NetverifyCustomScanInterface scanViewInterface)`

  - The following method was added to `NetverifyCustomScanPresenter` to trigger scanning start after the initialization. This method needs to be called on the `NetverifyCustomScanPresenter` after it was initialized with `initScanForPart(..)`.

```
/**
	 * Starts a scan after a scan presenter has been initialized
	 */
	void startScan();
```

- Make sure to display the `NetverifyCustomScanView` only AFTER calling `startScan()` as done in our [Sample](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/kotlin/netverify/customui/NetverifyCustomScanFragment.kt), to ensure that the scan presenter is fully initialized and the camera callback `onNetverifyCameraAvailable()` will be fired.

- ~~[`NetverifyScanMode.FACE`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyScanMode.html#FACE)~~ is replaced with

  - [`NetverifyScanMode.FACE_MANUAL`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyScanMode.html#FACE_MANUAL) for manual face scanning

  - [`NetverifyScanMode.FACE_IPROOV`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyScanMode.html#FACE_IPROOV) for face scanning with IProov

  - [`NetverifyScanMode.FACE_ZOOM`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyScanMode.html#FACE_ZOOM) for face scanning with Facetec ZoOm

#### Jetifier adaptions

Due to a bug in the Jetifier, the Bouncycastle library needs to be added to the Jetifiers ignorelist in the [`gradle.properties`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/gradle.properties)

```
android.jetifier.blacklist=bcprov-jdk15on
```

Please note that the naming of this will change with the Android Gradle Plugin 4 release and will become `android.jetifier.ignorelist`

## 3.8.0

#### Dependency Changes

- NEW AndroidX Kotlin Extension: `"androidx.core:core-ktx:1.3.1"`

- NEW Kotlin dependency: `"org.jetbrains.kotlinx:kotlinx-serialization-core:1.0.0"`

- NEW Kotlin dependency: `"org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0"`

- NEW Kotlin plugin: `"apply plugin: 'kotlinx-serialization"`

- NEW classpath definition: `"classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"`

- REPLACE Jumio Face: ~~`"com.jumio.android:face"`~~ with either:

  - `"com.jumio.android:iproov:3.8.0@aar"` and `implementation ("com.iproov.sdk:iproov:6.1.0"){ exclude group: 'org.json', module:'json' }`
    **or**
  - `"com.jumio.android:zoom:3.8.0@aar"` and `"com.facetec:zoom-authentication:8.12.1@aar"`

- AndroidX ConstraintLayout update: ~~`"androidx.constraintlayout:constraintlayout:2.0.1"`~~ is replaced by `"androidx.constraintlayout:constraintlayout:2.0.4"`

- AndroidX Appcompat update: ~~`"androidx.appcompat:appcompat:1.1.0"`~~ is replaced by `"androidx.appcompat:appcompat:1.2.0"`

- Google Play Services update: ~~`"com.google.android.gms:play-services-vision:19.0.0"`~~ is replaced by `"com.google.android.gms:play-services-vision:20.1.2"`

- Google Material Library update: ~~`"com.google.android.material:material:1.1.0"`~~ is replaced by `"com.google.android.material:material:1.2.1"`

#### Custom UI Changes

- [`NetverifyCustomSDKController$setDocumentConfiguration`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKController.html#setDocumentConfiguration-com.jumio.nv.custom.NetverifyCountry-com.jumio.nv.data.document.NVDocumentType-com.jumio.nv.data.document.NVDocumentVariant-) does not return a List with all required ScanSides anymore - they are now available as a parameter of [`NetverifyCustomSDKInterface$onNetverifyResourcesLoaded`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKInterface.html#onNetverifyResourcesLoaded-java.util.List-)

- Method `onNetverifyPrepareScanning()` added to `NetverifyCustomScanInterface` - indicates that the SDK is now loading information

#### Proguard Changes

Added the line ` -keep public class com.iproov.sdk.IProov {public *; }` to consumer Proguard rules.

#### Strings and Style Changes

Several additions and changes, mostly in regards to the new liveness flow.

- Button style: ~~`<item name="netverify_confirmationPositiveStyle"> @style/Custom.Netverify.Confirmation.MaterialButton </item>`~~ is replaced by `<item name="materialButtonStyle">@style/Custom.Netverify.Confirmation.MaterialButton</item>`

- Button style: ~~`<item name="netverify_confirmationNegativeStyle"> @style/Custom.Netverify.Confirmation.MaterialButton.Outlined</item>`~~ is replaced by `<item name="materialButtonOutlinedStyle">@style/Custom.Netverify.Confirmation.MaterialButton.Outlined</item>`

- NEW IProov attribute: `<item name="iproov_customization">@style/CustomIproov</item>`

- NEW IProov theme: `<style name="CustomIproov" parent="Iproov.Customization">`

- For changes in `String.xml` file changes please refer to the sample project.

## 3.7.3

#### Custom UI changes

- The countryList parameter in [NetverifyCustomSDKInterface$onNetverifyCountriesReceived](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKInterface.html#onNetverifyCountriesReceived-java.util.Map-java.lang.String-) has been changed from `HashMap` to `Map`

#### ZoOm Customization Changes

- All the attributes starting with `face_` have been removed
- For a full guide please head over to the [FAQ](integration_faq.md#zoom-customization)

#### Error Code Change

Error code N (Access token for different product / Parts of access token are missing) has been added.
Read more detailed information on this in chapter [Error codes](/docs/integration_guide.md#error-codes)

## 3.7.2

No backward incompatible changes

## 3.7.1

No backward incompatible changes

## 3.7.0

#### Dependency Changes

- Zoom update: ~~"com.facetec:zoom-authentication:8.0.11@aar"~~ is replaced by "com.facetec:zoom-authentication:8.12.1@aar"
- Room updated: ~~"androidx.room:room-runtime:2.2.3"~~ is replaced by "androidx.room:room-runtime:2.2.5"
- JMRTD updated: ~~"org.jmrtd:jmrtd:0.7.18"~~ is replaced by "org.jmrtd:jmrtd:0.7.19"
- Bouncycastle updated: ~~"org.bouncycastle:bcprov-jdk15on:1.64"~~ is replaced by "org.bouncycastle:bcprov-jdk15on:1.65"

#### API Changes

- `getEMRTDStatus()` has been removed from [NetverifyDocumentData](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifyDocumentData.html)
- New attributes for customization of the NFC help animation have been added to our `styles.xml`:

  - `netverify_nfc_passport_cover` - Outside passport cover color
  - `netverify_nfc_passport_page_dark` - Color of the last page inside the passport after opening
  - `netverify_nfc_passport_page_light` - Color of the flipped pages during opening
  - `netverify_nfc_passport_foreground` - Foreground color for the passport text and the phone screen
  - `netverify_nfc_phone_background` - Frame color for the phone that is positioned on the passport

- Attribute `netverify_nfc_dialog_theme` has been removed and is not required any more
- The position of the Jumio branding logo and privacy link changed to from bottom-right to center-top for all portrait scan views. In Custom UI, the top margin for this element can be adjusted using the following method [`setBrandingLogoTopMargin(int topMargin)`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanView.html#setBrandingLogoTopMargin-int-)

#### Customization Updates

- Android Zoom screens update.

#### Localizable Strings

Several additions and changes in regards to the Android Zoom screens update.

**Added strings:**

- [`netverify_nfc_description_xxx`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml#L58-L65) strings
- [`zoom_action_xxx`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml#L107-L108) strings
- [`zoom_instructions_xxx`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml#L127-L128) strings
- [`zoom_result_xxx`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml#L129-L130) strings
- [`zoom_retry_xxx`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml#L131-L136) strings

**Removed strings:**

- `netverify_nfc_bac_dialog_xxx` strings
- `netverify_nfc_description_xxx` strings

## 3.6.2

The Proguard keep rule `-keep class com.jumio.** { *; }` has to be added to your Proguard rules, if it wasn't added yet.
Details can be found in chapter [Proguard](../README_Android.md#proguard)

## 3.6.1

No backward incompatible changes

## 3.6.0

#### Dependency Changes

AndroidX Material design library has been _updated to version 1.1.0_

- ~~"com.google.android.material:material:1.0.0"~~ is replaced by "com.google.android.material:material:1.1.0"

Local broadcast manager dependency has been added mandatory due to the design library update where it was separated by Google

- implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.0.0"

JMRTD is now added as a gradle dependency - if you use NFC scanning please make sure to add the new dependencies:

- implementation "org.jmrtd:jmrtd:0.7.18"
- implementation "org.ejbca.cvc:cert-cvc:1.4.6"

## 3.5.0

#### Error Code Change

- Error code D (Wrong API credentials used, retry impossible) has been removed.

#### Proguard Change

- Consumer proguard rules have been added. All Jumio SDK proguard rules will now be applied automatically to the application when the Jumio Core library is included.

## 3.4.1

#### API Changes in NetverifyCustomScanInterface

- A new callback [onNetverifyUserConsentRequired](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKInterface.html#onNetverifyUserConsentRequired-java.lang.String-) was added to [NetverifyCustomScanInterface](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanInterface.html)

#### API Changes in NetverifyCustomSDKController

- A new method [onUserConsented](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKController.html#onUserConsented--) was added to [NetverifyCustomSDKController](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomSDKController.html)

## 3.4.0

#### Customization Updates

- The SDK now uses Material buttons instead of the old snackbar button styles on the confirmation view.
- Please check out the confirmation screens and the XML output in the [Surface Tool](https://jumio.github.io/surface-android/) for all adapted content.
  Changes:
- New style attribute **confirmationIcon** for customizing the info and warning icon on the confirmation screen.
- New confirmation button style **Netverify.Confirmation.MaterialButton** for the positive button.
- New confirmation button style **Netverify.Confirmation.MaterialButton.Outlined** for the negative button.

#### Dependency Changes

- Constraint layout dependency **androidx.constraintlayout:constraintlayout:1.1.3** or higher is now mandatory
- The following plugins are now required in the build.gradle of your application:

```
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'
apply plugin: 'kotlin-kapt'
```

- Dependency name and version change - com.facetec:zoom-authentication-hybrid:7.0.14 is replaced by **com.facetec:zoom-authentication:8.0.11@aar**
- ~~androidx.appcompat:appcompat:1.0.2~~ is replaced by androidx.appcompat:appcompat:1.1.0
- ~~androidx.room:room-runtime:2.0.0~~ is replaced by androidx.room:room-runtime:2.2.1

#### Custom UI Callbacks

- ~~onNetverifyDisplayFlipDocumentHint~~ has been removed
- A new parameter [NetverifyConfirmationType](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyConfirmationType.html) was added to [NetverifyCustomScanInterface$onNetverifyPresentConfirmationView](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanInterface.html#onNetverifyPresentConfirmationView-NetverifyConfirmationType-)

#### Proguard Changes

`-dontwarn com.facetec.zoom.sdk.**` needs to be added

## 3.3.2

No backward incompatible changes

## 3.3.1

No backward incompatible changes

## 3.3.0

#### Deallocation Callback

Added a new method [checkDeallocation](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#checkDeallocation-com.jumio.nv.NetverifyDeallocationCallback-) in the [NetverifySDK](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html) to check if the SDK resources have already been deallocated. The method requires a [NetverifyDeallocationCallback](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifyDeallocationCallback.html) instance as a parameter and calls `onNetverifyDeallocated` once the SDK is deallocated. The checkDeallocation method should only be called once the SDK has returned a result and another SDK instance is required.

#### Dependency Change

- ~~com.facetec:zoom-authentication-hybrid:7.0.12~~ is replaced by com.facetec:zoom-authentication-hybrid:7.0.14

#### Date Changes

All dates are now UTC based. This affects the dates in [NetverifyDocumentData](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifyDocumentData.html) and [NetverifyCustomNfcAccess](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/nfc/custom/NetverifyCustomNfcAccess.html)

#### New SDK Localizations Added

SDK Translations for the languages Italian and Portuguese have been added.

## 3.2.1

#### Fixed a Face Scanning Problem in Which a Black Screen Was Shown to the User

## 3.2.0

#### Dependency Change

- ~~androidx.appcompat:appcompat:1.0.0~~ is replaced by androidx.appcompat:appcompat:1.0.2
- ~~com.facetec:zoom-authentication-hybrid:7.0.9~~ is replaced by com.facetec:zoom-authentication-hybrid:7.0.12

#### API Changes in NetverifyCustomScanInterface

A new parameter [NetverifyCancelReason](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCancelReason.html) was added to [NetverifyCustomScanInterface$onNetverifyScanForPartCanceled](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanInterface.html#onNetverifyScanForPartCanceled-com.jumio.core.data.document.ScanSide-NetverifyCancelReason-)

#### Watchlist Screening

Two new methods for handling watchlist screening have been added. Please refer to the [Netverify guide](/docs/integration_bam-checkout.md#watchlist-screening)

```
netverifySDK.setWatchlistScreening(NVWatchlistScreening.ENABLED);
netverifySDK.setWatchlistSearchProfile("YOURPROFILENAME");
```

#### Additional Functions in NetverifyCustomScanInterface

For the new NFC scanning functionality in custom ui, there has been some additions in [NetverifyCustomScanInterface](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanInterface.html):
`getNetverifyCustomNfcInterface()` should return an instance of [NetverifyCustomNfcInterface](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/nfc/custom/NetverifyCustomNfcInterface.html) or Null
`onNetverifyStartNfcExtraction(NetverifyCustomNfcPresenter)` is called when the NFC scanning can be started. The NFC scanning is controlled with the provided instance of [NetverifyCustomNfcPresenter](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/nfc/custom/NetverifyCustomNfcPresenter.html)

#### Customization

The following customization attribute have been added: `netverify_scanOverlayFill`

#### New Fastfill Offline Token Required

Due to a license model update in our Barcode implementation, it's necessary to regenerate the offline token when updating to version 3.2.0

#### Close Button cCustomization in Custom UI

The position and image of the close button for face scanning can now be customized. Please have a look at the [NetverifyCustomScanView](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanView.html)

#### Custom UI Help Animation Support

[NetverifyCustomScanPresenter$getHelpAnimation](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomScanPresenter.html#getHelpAnimation-com.jumio.nv.custom.NetverifyCustomAnimationView-) has been added to get the specific help animation in case the scan part is canceled. An instance of [NetverifyCustomAnimationView](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/custom/NetverifyCustomAnimationView.html) needs to be passed where the animation is rendered in.

## 3.1.0

#### Dependency Changes

- ~~com.madgag.spongycastle:prov:1.58.0.0~~ is replaced by org.bouncycastle:bcprov-jdk15on:1.61
- Proguard rules containing _org.spongycastle_ have been replaced with _org.bouncycastle_
- ~~com.facetec:zoom-authentication-hybrid:7.0.5~~ is replaced by com.facetec:zoom-authentication-hybrid:7.0.9

## 3.0.0

#### Renamed Dependency NV-Face to Face

The dependency `com.jumio.android:nv-face` was renamed to `com.jumio.android:face`, reflecting the internal restructuring of the dependencies that was necessary for adding the new product Authentication

#### Renamed Public API Methods and Parameters

The following methods and the related parameters have been renamed to ensure consistency across all platforms

- `setRequireFaceMatch(..)` -> `setEnableIdentityVerification(..)`
- `setRequireVerification(..)` -> `setEnableVerification(..)`
- `setMerchantReportingCriteria(..)` -> `setReportingCriteria(..)`
- `setMerchantIdScanReference(..)` -> `setCustomerInternalReference(..)`
- `setCustomerId(..)` -> `setUserReference(..)`

#### Additional Property in NetverifyCustomScanView

`setMode(..)` must be called before the view is used. Possible values: NetverifyCustomScanView.MODE_ID or NetverifyCustomScanView.MODE_FACE

## 2.15.0

#### Added Room

Dependencies that have been added to the SDK:

- androidx.room:room-runtime:2.0.0

#### Added 3D Liveness

###### Dependency Changes

- com.jumio.android:nv-face:2.15.0@aar
- com.facetec:zoom-authentication-hybrid:7.0.2@aar
- ~~com.jumio.android:nv-liveness:2.14.0@aar~~ The old liveness module is not supported anymore

The Facetec Maven repository also needs to be added: maven `{ url 'http://maven.facetec.com' }`

###### Localization

Please have a look at the [strings-jumio-sdk.xml](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml) for all the new added strings prefixed with `zoom_`.
The following strings have been removed: `netverify_scanview_liveness_follow_hint`, `netverify_scanview_liveness_move_closer`, `netverify_scanview_liveness_move_back`, `netverify_scanview_liveness_description`, `netverify_helpview_full_description_liveness_glasses`, `netverify_helpview_full_description_liveness_cap` and `netverify_helpview_full_description_liveness_light`.

###### Customization

The following customization attributes have been added: `netverify_scanOverlayFaceBackground`, `netverify_scanOverlayFaceFeedbackText`, `netverify_scanOverlayFaceFeedbackBackground`, `netverify_scanOverlayFaceProgress`, `netverify_scanOverlayFaceOval`
The following customization attributes have been removed: `netverify_scanOverlayLivenessValid`, `netverify_scanOverlayLivenessInvalid`, `netverify_scanOverlayLivenessBackground`, `netverify_scanOverlayLivenessText`

###### Proguard

The following lines need to be added in your `proguard-rules.pro` file for 3D Liveness:

```
-keep class com.facetec.zoom.** { *; }
-dontwarn javax.annotation.Nullable
```

## 2.14.0

#### Migrate to AndroidX

The support library was migrated to [`AndroidX`](https://developer.android.com/jetpack/androidx/). As the developer page outlines, this is a mandatory step since all new Support Library development and maintenance will occur in the AndroidX library. This [`migration guide`](https://developer.android.com/jetpack/androidx/migrate) shows you how to migrate your application to AndroidX.

Check out the changed dependencies in the [`dependencies section`](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#dependencies) or in the [`build.gradle`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/build.gradle) of the sample application.
The mapping for all support libraries is listed in section "Artifact mappings" [here](https://developer.android.com/jetpack/androidx/migrate)

Dependencies that changed in the SDK:

- com.android.support:appcompat-v7:27.1.1 -> androidx.appcompat:appcompat:1.0.0
- com.android.support:cardview-v7:27.1.1 -> androidx.cardview:cardview:1.0.0
- com.android.support:design:27.1.1 -> com.google.android.material:material:1.0.0

* com.android.support:support-v4:27.1.1 -> androidx.legacy:legacy-support-v4:1.0.0 (was merged by AndroidX and can be therefore be fully removed)

#### Default Settings

The default values for [`requireVerification`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#setRequireVerification-boolean-) and [`requireFaceMatch`](https://jumio.github.io/mobile-sdk-android/com/jumio/nv/NetverifySDK.html#setRequireFaceMatch-boolean-) were changed to `true`. Please make sure that they are explicitly set to false in case a scan in Fastfill mode should be performed.

## 2.13.0

#### API Change in NetverifyDocumentData

The function `getMiddleName()` has been removed. If a middle name is available, it will be contained with the first name.

#### Removed Deprecated ABIs mips, mips64 and armeabi

These ABIs were deprecated in recent NDK toolsets as mentioned here - https://developer.android.com/ndk/guides/abis and are not used any more.

## 2.12.1

#### Fixed a Problem in Which the User Could Get Stuck in the Selfie Capturing Process

## 2.12.0

#### Fallback for Google Vision Not Operational Added

A fallback to manual image picker will now be used if Google Vision is not operational due to problems on the device. This guarantees the face workflow to be finished despite problems with the availablility of the Google Play services.
The method `netverifySDK.isMobileVisionOperational` remains in the SDK but doesn't need to be checked now necessarily.

#### New SDK Localizations Added

In addition to English, the translations for the languages Chinese (Simplified), Dutch, French, German and Spanish have been added.

#### Remove Unused Strings for Localization

Along with the additional languages, we removed some Strings that were unused in the SDK. The following keys have been removed: `netverify_confirmation_snackbar_help_default`, `netverify_accessibility_select_your_country`, `netverify_accessibility_action_double_click`, `netverify_accessibility_select_your_country`, `netverify_scan_options_country_title`, `netverify_overlay_liveness_advice` and `netverify_scan_options_preselected_hint`.

#### Additional Information Method Removed

SDK method `netverifySDK.setAdditionalInformation` has been removed.

#### New Callback in NetverifyCustomScanInterface

`onNetverifyDisplayBlurHint()` was added for custom scan view.

## 2.11.0

#### New Error Scheme

The schema for `errorCode` changed and it's type is now String instead of Integer.
Read more detailed information on this in chapter [Error codes](/docs/integration_guide.md#error-codes)

## 2.10.1

No backward incompatible changes.

## 2.10.0

- SDK updated to Android plugin for gradle 3.0 - https://developer.android.com/studio/build/gradle-plugin-3-0-0-migration.html
- Minimum API level was raised from Android 4.1 (API level 16) to Android 4.4 (API level 19)

## 2.9.0

#### Changes in SDK Code

- New cardview dependency was added `com.android.support:cardview-v7:26.1.0` for the screen redesign. This dependency is mandatory for Netverify
- Multidex is now mandatory, follow the steps Android Developers guide https://developer.android.com/studio/build/multidex.html#mdex-gradle to enable it if necessary in your app.
- Additional Proguard rules for the updated Barcode Scanner have to be added:

```
-keep class com.microblink.** { *; }
-keep class com.microblink.**$* { *; }
-dontwarn com.microblink.**
```

- SDK method for checking the Google Mobile Vision API operationality was added (see method documentation in [NetverifyFragment](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/NetverifyFragment.java) in the Sample app))

```
GoogleVisionStatus NetverifySDK.isMobileVisionOperational(Activity activity, int requestCode);
```

#### Changes in Localizable Strings

Multiple additions and changes in regards to the new selection screen.

#### Changes in Customization

Additions and changes in regards to the new selection screen (see XML output in [Surface Tool](https://jumio.github.io/surface-android/)).
Attributes added for replacing the previous selection screen: `netverify_scanOptionsItemHeaderBackground`, `netverify_scanOptionsItemForeground` and `netverify_scanOptionsItemBackground`.

## 2.8.0

- Dependency `com.jumio.android:nv-liveness:2.8.0@aar` is mandatory now.

## 2.7.0

- New Dependency `com.jumio.android:nv-liveness:2.7.0@aar` was added for face-liveness functionality.
- Dependency `com.google.android.gms:play-services-vision` is now mandatory required because of added functionality.
- Change SDK method `setEnableEpassport(boolean)` to `setEnableEMRTD(boolean)` because of to the support for NFC ID documents.
- If the dependencies `com.jumio.android:nv-liveness` and `com.jumio.android:nv-barcode-vision` are both used in the application, the following lines have to be added to the application tag in the AndroidManifest.xml to avoid merge issues.

```
<meta-data
			android:name="com.google.android.gms.vision.DEPENDENCIES"
			android:value="barcode, face"
			tools:replace="android:value"/>
```

- Additional Proguard rules for the Samsung Camera SDK have to be added:

```
-keep class com.samsung.** { *; }
-keep class com.samsung.**$* { *; }
-dontwarn com.samsung.**
```

## 2.6.1

No backward incompatible changes.

## 2.6.0

#### Changes in SDK API

- Removed SDK method `setShowHelpBeforeScan(boolean)` because the collapsed help view is now constantly visible during scanning.
- Add NetverifySDK method `isRooted(Context)` for device root-check before starting the SDK

#### Changes in Localizable Strings

Multiple additions and changes in regards to the new guidance / help screen.

#### Changes in Customization

Additions and changes in regards to the new guidance / help screen.

## 2.5.0

No backward incompatible changes.

## 2.4.0

#### Remove okHttp

The build.gradle was adapted to support standard UrlConnection for replacing okHttp

#### Changes in Customization

Override the theme that is used for Netverify in the manifest by calling `netverifySDK.setCustomTheme(CUSTOMTHEMEID)`. Use the resource id of a customized theme that uses `Theme.Netverify` as parent.
Additions and changes for customization options for the launch of the surface tool.

#### Provide Possibility to Avoid Loading Spinner After SDK Start

Use the following method to initialize the SDK before displaying it

```
netverifySDK.initiate(new NetverifyInitiateCallback() {
 @Override
 public void onNetverifyInitiateSuccess() {
 }
 @Override
 public void onNetverifyInitiateError(int errorCode, int errorDetail, String errorMessage, boolean retryPossible) {
 }
});
```

#### Removed Name Match Feature

Name matching by comparing a provided name with the extracted name from a document was removed. The method `setName("FIRSTNAME LASTNAME")` in the NetverifySDK was removed.

## 2.3.0

#### Changes in Customization

Additions for the customization options to support the configuration of all scan overlays.

## Copyright

&copy; Jumio Corp. 395 Page Mill Road, Palo Alto, CA 94306

---

# Known Issues

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/known_issues

![Header Graphic](images/jumio_feature_graphic.jpg)

# Known Issues

# SDK Version 4.18.0 and Above

## Jetifier Fails on BouncyCastle 1.83 (NFC module)

Starting with SDK 4.18.0 the `com.jumio.android:nfc` module pulls in `org.bouncycastle:bcprov-jdk18on:1.83`, a multi-release jar that contains Java 25 (class major version 69) bytecode. If you still have Jetifier enabled (`android.enableJetifier=true` in your `gradle.properties`), the build fails because Jetifier cannot scan that bytecode:

```
Jetifier failed to transform … bcprov-jdk18on-1.83.jar
java.lang.IllegalArgumentException - Unsupported class file major version 69
```

Add BouncyCastle to the Jetifier ignorelist in your `gradle.properties`:

```
android.jetifier.ignorelist=bcprov-jdk18on
```

This excludes the jar from Jetifier's transform step only - it stays on the classpath and ships in the APK unchanged, so NFC keeps working. The transform is a no-op anyway, since BouncyCastle does not reference any `android.support.*` APIs; Jetifier crashes only because it eagerly scans the bytecode before discovering there is nothing to rewrite. See [Google issue tracker #184622491](https://issuetracker.google.com/issues/184622491) for background.

# SDK Version 4.14.0 and Above

## LiteRT Version override

JumioSDK bundles LiteRT Version 1.0.1 which supports 16kb page size for ARM64-v8 but not x86_64. This is fine for the JumioSDK as only ARM cpus are supported. An update to 1.4.0 is currently not possible because the min API level of LiteRT 1.4.0 (25) exceeds the min API level of the Jumio SDK (21).
If you don't use LiteRT elsewhere in the code you can remove the x86 and x86_64 libraries by excluding them in the packagingOptions:

```gradle
android {
	...
	packagingOptions {
		...
		it.excludes.add("lib/x86_64/libtensorflowlite_jni.so")
		it.excludes.add("lib/x86/libtensorflowlite_jni.so")
	}
}
```

If your apps min API level is at least 25 then the LiteRT dependency can be overridden:

```gradle
implementation ("com.jumio.android:docfinder:4.14.0") {
	exclude group: 'com.google.ai.edge.litert', module: 'litert'
	exclude group: 'com.google.ai.edge.litert', module: 'litert-metadata'
}
implementation ("com.jumio.android:liveness:4.14.0") {
	exclude group: 'com.google.ai.edge.litert', module: 'litert'
}
implementation 'com.google.ai.edge.litert:litert:1.4.0'
implementation 'com.google.ai.edge.litert:litert-support:1.4.0'
```

# SDK Version 4.0.0 and Above

## Duplicate Files for 'libc++\_shared.so' Library

If build fails with error message:

_2 files found with path 'lib/arm64-v8a/libc++\_shared.so' from inputs ..._

Please add the following `packagingOptions` to the configuration in your `build.gradle` file:

```
android{
  packagingOptions {
      pickFirst 'lib/armeabi-v7a/libc++_shared.so'
      pickFirst 'lib/arm64-v8a/libc++_shared.so'
  }
}

```

## Picking a file does not work on some Xiaomi devices {#xiaomi-file-picker}

On some Xiaomi devices (e.g. Redmi Note 4) it can happen that picking a file from local storage for document verification fails. This boils down to a problem with Xiaomi's default file manager.
To fix this, please install and use a different file manager on those devices when loading a file for document verification.

# SDK Version 3.9.2 and 4.0.0

## Face Scan Crash at Start

If the face scan crashes without warning on camera start and/or the following error message is displayed:

_java.lang.SecurityException: To use the sampling rate of 0 microseconds, app needs to declare the normal permission HIGH_SAMPLING_RATE_SENSORS._

Please make sure to add the following permission to your `AndroidManifest.xml` file:

```
<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS"/>
```

# SDK Version 3.9.0

## Custom UI

- Make sure to display the `NetverifyCustomScanView` only AFTER calling `startScan()` as done in our [Sample](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/java/com/jumio/sample/kotlin/netverify/customui/NetverifyCustomScanFragment.kt), to ensure that the scan presenter is fully initialized and the camera callback `onNetverifyCameraAvailable()` will be fired.

# SDK Version 3.8.0 and Newer

## Stuck on 'Processing Documents' Screen

If user is getting stuck indefinitely after scanning process during 'Processing documents' stage without a callback or error message, please make sure the following dependencies

```
classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version

apply plugin: 'kotlinx-serialization'

dependencies {
  ...
  implementation "org.jetbrains.kotlinx:kotlinx-serialization-core:1.0.0"
  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0"
  ...
}
```

have been included in your `build.gradle` file. Missing Kotlin serialization will result in infinite loading without a callback.

Please also refer to the 3.8.0 **"Dependency Changes"** section of our [transition guide](transition_guide.md) and the `build.gradle`(https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/build.gradle) of our sample application for additional information.

## Fallback to Manual Capturing Using iProov

In some rare cases, the iproov Token Call can take too long to complete, which means the token is not yet available when the decision for the Liveness Vendor is made. When this happens, the scan mode `FACE_MANUAL` (Manual Capturing) will be used as a fallback. This also applies to **Tablets** and devices running on **Android Version 5** ("Lollipop") or lower.

**Note:** This is most likely to happen for applications implementing CustomUI that start with face scanning directly.

## Issues with okhttp3 Dependency Using iProov

iProov indirectly depends on okhttp 3.8.1. As of now, issues related to okhttp have been due to the use of okhttp 4.x.

This can be solved by downgrading the dependency that provides 4.x, by excluding the okhttp package from that dependency, or by a combination of both of these. (Please note that a 3.x version is not necessarily older than 4.x one.)

Please also refer to [iProov FAQ](https://github.com/iProov/android/wiki/Frequently-Asked-Questions#issues-with-okhttp3-dependency) for further information.

## Jetifier Issues

Due to a bug in the Jetifier, the Bouncycastle library needs to be added to the Jetifiers ignorelist in the [`gradle.properties`](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/gradle.properties)

```
android.jetifier.blacklist=bcprov-jdk15on
```

Please note that the naming of this will change with the Android Gradle Plugin 4 release and will become `android.jetifier.ignorelist`

## Custom UI

On using iProov in CustomUI, in case `NetverifySDKController$retry` function is called for an error EXX0000, the SDK can fail with the following exception: `java.lang.NoClassDefFoundError: Failed resolution of: Lcom/jumio/zoom/custom/ZoomCustomScanPresenter`. This issue was fixed in SDK version 3.9.0. As a workaround it is possible to only add `implementation "com.jumio.android:zoom:3.8.0@aar"` to the build.gradle dependencies.

# SDK Version 3.7.x

## Kotlin Integration

Since the Jumio SDK is partly written in Kotlin, it is necessary to add the Kotlin standard library dependency to your project, even if the project itself if written in Java.

# Miscellaneous

## Static Interface Methods Are only Supported with Android N

Error message "Static interface methods are only supported with Android N" will be displayed when Java 8 compatibility is not enabled. In this case, please make sure to enable compatibility in your `build.gradle` file:

```
android {
...
  compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

## SDK Crashes Trying to Display Animations (Android Version 5 and Lower)

Running the SDK on API Level 21/Android Version 5 ("Lollipop") or lower, the application might crash when trying to display Jumio animations. In this case it is necessary to add the line `AppCompatDelegate.setCompatVectorFromResourcesEnabled(true)` to the `onCreate()` method of your application or `Activity`, ideally before `setContentView()` is called.

:::note

Refer to [required for vector drawable compat handling](https://stackoverflow.com/a/37864531/1297835) for further information.
This is not needed anymore for SDK 4.14.0 and up as the minimum API Level was raised to 23.
:::

## Country Missing from the Country List

Countries with documents that are [MRZ](integration_glossary.md)-capable (which is the case for most passports) might not be available if the necessary MRZ dependency is missing. The dependency in question is:

```
implementation "com.jumio.android:nv-mrz:3.9.0@aar"
```

Countries with documents that have a barcode might not be available if the necessary MRZ dependency is missing. The dependency in question is:

```
implementation "com.jumio.android:nv-barcode:3.9.0@aar"
```

A complete list of all dependencies [can be found here.](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#dependencies)

**Note:** Version numbers may vary.

## Datadog in Dynamic feature modules

Datadog registers a Content Receiver through its AndroidManifest. Therefore Datadog needs to be linked in the base app, otherwise the app will crash during start.

```
api "com.datadoghq:dd-sdk-android-rum:2.0.0"
```

**Note:** Datadog was removed in SDK version 4.13.0

---

# Integration Glossary

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/integration_glossary

![Header Graphic](images/jumio_feature_graphic.jpg)

# Glossary

## Commonly Used Abbreviations

### CVV

Card Verification Value: A verification number on any credit card, usually 3-4 digits long

### DOB

Date Of Birth

### DV

Driver’s License

### GDPR

[General Data Protection Regulation](https://gdpr-info.eu) (EU): EU-wide data privacy regulation protecting natural persons and their personal data, especially in regards to collecting, processing and the free movement of that data

### ISO 3166-1

ISO standard detailing standard country code abbreviations (like AUT, DEU, etc); either [alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (using two letters) or [alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) (using three letters)

### KYC

Know Your Customer

### KYX

Know Your Everything: Jumio’s end-to-end [identity platform](https://www.jumio.com/kyx/)

### MRP

Machine Readable Passport

### MRTD

Machine Readable Travel Document

### eMRTD

Electronic Machine Readable Travel Document

### MRZ

Machine Readable Zone: Standardized, usually at the bottom of the identity page of a passports, between 2 and 3 lines long, varies in size

### NFC

[Near-Field Communication:](https://en.wikipedia.org/wiki/Near-field_communication#Identity_and_access_tokens) Establishes wireless connection from one device to another, but only if that device is in close enough proximity; can act as an electronic identity document / electronic identity token and is already used in many identity documents worldwide

### NV

Netverify

### OAuth2

An [industry-standard protocol for authorization](https://oauth.net/2/)

### OAuth2 Access Token

An [access token using the OAuth2 protocol](https://oauth.net/2/access-tokens/) to make safe API calls and securely access resources from a server

### OCR

[Optical Character Recognition:](https://en.wikipedia.org/wiki/Optical_character_recognition) Converts images of text, such as text on IDs, to machine-encoded and machine-readable text

### PII

Personal(ly) Identifiable Information: All of our products deal with highly sensitive data regarding information relating to an identifiable person, which is handled with great care, the best possible security and in compliance with the GDPR

### PP

Passport

### 3D-Liveness

Liveness check: The 3D-liveness check makes sure that a face scan performed was not of a picture, but of an actual, living person who also matches the picture on the previously scanned document

### DID

Digital Identity

---

# Integration FAQ

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/integration_faq

import consent_passive_jpg from './images/consent/consent_passive.jpg';
import consent_active_unchecked_jpg from './images/consent/consent_active_unchecked.jpg';
import consent_active_checked_jpg from './images/consent/consent_active_checked.jpg';
import autocapture_01_jpg from './images/capturing_methods/autocapture_01.jpg';
import autocapture_02_jpg from './images/capturing_methods/autocapture_02.jpg';
import autocapture_03_jpg from './images/capturing_methods/autocapture_03.jpg';
import autocapture_04_jpg from './images/capturing_methods/autocapture_04.jpg';

![Header Graphic](images/jumio_feature_graphic.jpg)

# FAQ

## User Consent

User consent is now acquired for all users to ensure the accordance with biometric data protection laws. Depending on the legal requirements, consent can be acquired in one of two ways: **Active** or **passive**.

For **active** consent instances, the user needs to accept the consent items explicitly, e.g. by enabling a UI switch or checking a checkbox for each consent item. For **passive** consent instances, it is enough to present the consent text and URL to the user. The user implicitly accepts the passive consent items by continuing with the journey.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={consent_passive_jpg} alt="Acquiring passive user consent" style={{ border: '1px solid black', padding: '5px' }} />
  <img src={consent_active_unchecked_jpg} alt="Acquiring active user consent" style={{ border: '1px solid black', padding: '5px' }} />
  <img src={consent_active_checked_jpg} alt="Acquired active user consent" style={{ border: '1px solid black', padding: '5px' }} />
</div>

## Improve User Experience and Reduce Drop-off Rate

When evaluating user flows, one of the most commonly used metrics is the rate of drop-offs. At Jumio, we see considerable variance in drop-off rates across industries and customer implementations. For some implementations and industries, we see a higher rate of drop-offs on the first screens when compared with the average.
Scanning an ID with sensitive personal data printed on it naturally creates a high barrier for participation on the part of the end user. Therefore, conversion rates can be significantly influenced when the application establishes a sense of trust and ensures that users feel secure sharing their information.

One pattern that is recognizable throughout all of our customers’ SDK implementations: the more seamless the SDK integration, and the better job is done of setting user expectations prior to the SDK journey, the lower the drop-off rate becomes.

Our SDK provides a variety of [customization options](integration_guide.md#customization) to help customers achieve a seamless integration. For customers using the standard SDK workflow, our [Surface tool](https://jumio.github.io/surface-android/) provides an easy-to-use WYSIWYG interface to see simple customization options that can be incorporated with minimal effort and generate the code necessary to implement them. For customers who want to have more granular control over look and feel, our SDK offers the [CustomUI](integration_guide.md#custom-ui) option, which allows you to customize the entire user interface.

### Example of a Non-Ideal SDK integration:

![Onboarding bad case](images/onboardingBadCase.jpg)

- Default SDK UI is used and is presented on one of the first screens during onboarding. The user is unprepared for the next steps and might not understand the intention behind the request to show their ID.

### Suggested Improvements with Additional Customization:

![Onboarding good case](images/onboardingGoodCase.jpg)

- Host application has an explanatory help screen that explains what will happen next and why this information is needed.
- SDK is either customized to have a more embedded appearance or [CustomUI](integration_guide.md#custom-ui) is used to create a completely seamless integration in the UX of our customers.
- Also after the Jumio workflow that shows the displayed results and/or a message that the ID is currently verified, which might take some minutes.

## Managing Errors

Not every error that is returned from the SDK should be treated the same. The error codes listed for [ID Verification](integration_guide.md#error-codes) should be handled specifically.

The following table highlights the most common error codes which are returned from the SDK and explains how to handle them appropriately in your application.

|    Code     | Cause                                                                                              | Recommended Handling                                                                                                                                              |
| :---------: | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A[xx][yyyy] | Caused by temporary network issues like a slow connection.                                         | Advise to check the signal and retry the SDK journey.                                                                                                             |
| E[xx][yyyy] | Flight mode is activated or no connection available.                                               | The user should be asked to disable flight mode or to verify if the phone has proper signal. Advise to connect to WIFI and retry the SDK journey afterwards.      |
| G[xx][0000] | The user pressed back or X to exit the SDK while no error view was presented.                      | Reasons for this could be manifold. Often it might be due to the fact that the user didn't have his identity document at hand. Give the user the option to retry. |
| J[xx][yyyy] | The SDK journey was not completed within the session's max. lifetime. (The default is 15 minutes.) | The user should be informed about the timeout and be directed to start a new Jumio SDK session.                                                                   |

### Ad Blockers or Firewall

End users might face the situation where they are connected to a network that can't reach our Jumio endpoints.

Possible reasons for this might be ad blockers on the device, network wide ad blockers or network specific firewall settings.  
In these cases the SDK will return a specific error code: **A10900** If this error is received, we suggest to add a screen where the user is advised to switch network and/or turn off possible ad blockers.

## Reducing the Size of Your App

The Jumio SDK contains a wide range of different scanning methods. The SDK is able to capture identity documents and extract information on the device using enhanced machine learning and computer vision technologies.
The current download size of the [sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/) containing all products is around **13.63 MB** as mentioned in the [ID Verification guide](integration_guide.md).
If you want to reduce the size of the SDK within your application, there are several ways to achieve this:

### Strip Unused Modules

Depending on your specific needs, you may want to strip out unused functionality. As most of our modules can be linked optionally, you can reduce file size by adapting your [Jumio dependencies](integration_guide.md#dependencies) in your build.gradle.

The following table shows a range of different product configurations with the size and modules that are linked for it. These measurements reflect the extra size that Jumio components add to your app download size and are based on our [sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/).

| Product Configuration                        |   Size   |                                              Modules                                              |
| :------------------------------------------- |:--------:| :-----------------------------------------------------------------------------------------------: |
| Base                                         | 1.42 MB  |                                               core                                                |
| Base + Autocapture                           | 3.42 MB  |                                          core, docfinder                                          |
| Base + Autocapture, Barcode-Vision           | 3.72 MB  |                                  core, docfinder, barcode-mlkit                                   |
| Base + Autocapture, Barcode-Vision, Liveness | 6.09 MB  |                                core, docfinder, barcode, liveness                                 |
| Base + Autocapture, Barcode-Vision, NFC      | 6.83 MB  |                                   core, docfinder, barcode, nfc                                   |
| All (Custom UI only)                         | 10.0 MB  |             core, docfinder, barcode-mlkit, nfc, digital-identity, camerax, liveness              |
| Base + Autocapture, Default UI               | 4.68 MB  |                                    core, docfinder, defaultui                                     |
| All (with Default UI)                        | 11.12 MB |       core, docfinder, barcode-mlkit, nfc, digital-identtity, camerax, defaultui, liveness        |

:::note
The size values in the table above depict the decompressed install size required on a device and are comparable to the estimated Play Store files size. The size value might vary by a few percent, depending on the actual device used. All sizes are calculated based on a build of our sample application using arm64 architecture, english translations and xxhdpi screen resolution.
:::

### App Bundles

Android offers a way to reduce the size of a customer's built application using [App bundles](https://developer.android.com/guide/app-bundle/)
Google Play’s new app serving model uses the _App bundle_ to generate and serve optimized APKs for each user’s device configuration, so they download only the code and resources they need to run your app.

### Architectures, ABI Filters & Splitting

The SDK supports _armeabi-v7a_ and _arm64-v8a_ architecture. You can filter which architecture to use by specifying the abiFilters. That way, you could manually filter for _armeabi-v7a_ as _arm64-v8a_.

**Be aware:** As of August 2019, Google Play Console will require that new apps and app updates with native libraries provide 64-bit versions in addition to their 32-bit versions, as mentioned in the [Android developers blog.](https://android-developers.googleblog.com/2017/12/improving-app-security-and-performance.html).

:::note
The abiFilters command in the ndk closure affects the Google Play Store filtering.
:::

```
defaultConfig {
	ndk {
		abiFilters armeabi-v7a","arm64-v8a","x86","x86_64"
	}
}
```

It's also possible to manually provide a split apk on Google Play. The apk can be split based on the architecture if multiple apks should be uploaded to the Google Play Store. Google Play Store manages to deliver the appropriate apk for the device.

```
splits {
	abi {
		enable true
		reset()
		include armeabi-v7a","arm64-v8a","x86","x86_64"
		universalApk false
	}
}
```

### Code Shrinking, Obfuscation and Optimization

The Jumio Android SDK is optimized using Google's R8 code shrinking tool. When utilizing the SDK and its dependencies it is important to apply several keep-rules in your project's proguard file to ensure that dependencies are available and the SDK can function correctly. A list of all required rules can be found [here](../README_Android.md#proguard) or [within our Sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/proguard-rules.pro).

#### R8 Full Mode

If using Gradle 8, `fullMode` is _enabled per default_. You may disable it and use compatibility mode instead by putting the following in your `gradle.properties` file:

```text
android.enableR8.fullMode=false
```

If you decide to use `fullMode` instead, the following rule needs to be applied to your application's `proguard-rules.pro` file, due to an issue with subclasses of `ConstraintLayout`'s `Key` class:

```text
# Enabling this rule is only needed if using fullMode for R8
# https://github.com/androidx/constraintlayout/issues/428
-keepclassmembers class * extends androidx.constraintlayout.motion.widget.Key {
  public <init>();
}
```

Enabling `fullMode` might help you further reduce your app's apk size.

## Jumio Authentication Workflow Integration

Jumio Authentication can be used for any use case in which you want your end-users to confirm their identities. As a result of the Authentication journey you get a success or failed result back from the SDK or from our server (callback or retrieval).

In case of a **successful result** you can grant the user access to your service or let him proceed with the user flow. In case of a **failed result**, a proper retry handling within your workflow is necessary. A failure could occur because of the following reasons:

- The user presenting their face is a different one than the user who owns the account
- An imposter is trying to spoof the liveness check
- User does not want to show their face at all, but is still trying to complete the onboarding
- User does not look straight into the camera
- User does not finish the first or second step of face scan
- User has bad lighting conditions (too dark, too bright, reflections on face, not enough contrast, …)
- User is covering (parts) of their face with a scarf, hat or something similar
- A different person is scanning their face in the second step than in the first one
- User is not able to align his face with the oval presented during scanning

In case an Authentication fail is returned, we recommend to allow the user between 3-5 Authentication attempts to prove their identity, before you lock the user from performing the action. This approach makes the most sense, as you don't want to lock out possible valid users who might not have completed the face capture task successfully for a legitimate reason. Don't worry about offering a potential fraudster more attempts to gain access to your system - our bullet proof liveness check does not allow them to get a successful result.

## Fallback and Manual Capturing

The property [`hasFallback`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/has-fallback.html) determines if a fallback for the current scan mode is available. If the property is true, the available fallback scan mode can be started with the method [`fallback()`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.scanpart/-jumio-scan-part/fallback.html).

The property [`isShutterEnabled`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-scan-view/is-shutter-enabled.html) determines if a shutter button needs to be shown if the image has to be taken manually. If the property is true, you will have to display your own shutter button and call the method [`takePicture()`](https://jumio.github.io/mobile-sdk-android/jumio-core/com.jumio.sdk.views/-jumio-scan-view/take-picture.html) to take a picture.

:::note
Please note that the method `showShutterButton()` does neither create nor display the actual shutter button!
:::

"Manual capturing" simply refers to the user being able to manually take a picture. "Fallback" refers to an alternative scan mode the SDK can resort to if possible, in case there is an issue during the original scanning process. The fallback scan mode might be manual capturing in some cases, but not all.

## Custom Theme

### Custom Theme Is Not Working

Any customized theme needs to be defined in a `styles.xml` file and has to inherit from the parent theme `Theme.Jumio`.

```
<style name="AppTheme.JumioCustom" parent="Theme.Jumio">
  <item name="colorPrimary">@color/colorPrimary</item>
  ...
</style>

```

The actual name of the customized theme is arbitrary and can be chosen at will.

Any customized theme needs to be added to the `AndroidManifest.xml` file by replacing the initial `Theme.Jumio`.

```
<activity
  android:name="com.jumio.defaultui.JumioActivity"
  android:theme="@style/AppTheme.JumioCustom"
  ...
<activity/>
```

### Scan Overlay Is Not Displayed

Make sure all necessary style attributes have been added to your custom theme specified in the `style.xml` file. In case of issues with scan overlay, all relevant attributes start with `jumio_scanOverlay` and `face_scanOverlay`.

An overview of all style attributes [can be found here](https://github.com/Jumio/mobile-sdk-android/blob/master/sample/JumioMobileSample/src/main/res/values/styles.xml)

## Language Localization

[`Jumio Android Localization`](../README_Android.md#language-localization) supports the [default Android localization features](https://developer.android.com/training/basics/supporting-devices/languages.html) for a number of different languages and cultures. Any language changes within the SDK or separate language support during runtime (meaning the SDK language differs from the overall device languages) are not possible.

All label texts and button titles in the SDK can be changed and localized by adding the required Strings you want to change in a `strings.xml` file in a `values` directory for the language and culture preference that you want to support. All modifiable strings can be modified can be found [within our Sample application](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/src/main/res/values/strings-jumio-sdk.xml).

Currently, the following languages are automatically supported for your convenience: [Supported languages](../README_Android.md#language-localization)

Runtime language changes _within_ the SDK or separate language support (meaning the SDK language differs from the overall device languages) is not possible. All of the used string values can be found in the [sample project resource folder](https://github.com/Jumio/mobile-sdk-android/tree/master/sample/JumioMobileSample/src/main/res). If you want to [manage certain strings individually](https://developer.android.com/guide/topics/resources/localization#managing-strings), please access them in the **values-xx** folder that corresponds to the language.

:::info
The last two letters of the values folder (marked "xx" above) refer to the [ISO alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), which has to be used for the localization to work automatically. Please refer to the country list if you have trouble determining which string file contains to which language.
:::

### Accessibility

Our SDK supports accessibility features. Visually impaired users can now enable **TalkBack** or increase the **text size** on their device. The accessibility-strings that are used by TalkBack contain _accessibility_ in their key and can be also modified in the `strings.xml`.

### String Updates

For an overview of all updates and changes of SDK string keys please refer to [the revision history](https://github.com/Jumio/mobile-sdk-android/blame/master/sample/JumioMobileSample/src/main/res/values/strings.xml) on Github.

## Java 8 Compatibility

Jumio SDK uses [Java 8 language.](https://developer.android.com/studio/write/java8-support.html) It is necessary to enable Java 8 source and target compatibility for in the `build.gradle` file using `compileOptions`:

```
android {
...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

## Overview of Scanning Methods

#### Autocapture

Combines all previously existing scanning methods into one automatic, seamless experience.

<div style={{display: 'flex', gap: '10px'}}>
  <img src={autocapture_01_jpg} alt="Autocapture Start" style={{width: '22%', height: 'auto'}} />
  <img src={autocapture_02_jpg} alt="Autocapture Center Document" style={{width: '22%', height: 'auto'}} />
  <img src={autocapture_03_jpg} alt="Autocapture Hold Still" style={{width: '22%', height: 'auto'}} />
  <img src={autocapture_04_jpg} alt="Autocapture Checking Image" style={{width: '22%', height: 'auto'}} />
</div>

#### Manual Capture

Manual scanning (taking a picture) using the shutterbutton, fallback option in case user is having trouble.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img src={require('./images/capturing_methods/manual_capturing_01.jpg').default} alt="Manual Capture Empty" style={{width: '38%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/manual_capturing_02.jpg').default} alt="Manual Capture Document" style={{width: '38%', height: 'auto'}} />
</div>

#### Enhanced Injection Detection

You may see additional detection screens during the ID Scan process. This is expected behavior and is part of Jumio’s enhanced fraud protection measures.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img
    src={require('./images/enhanced_injection_detection/enhanced_injection_detection_white_balance.jpg').default}
    alt="enhanced_injection_detection_white_balance"
    style={{width: '38%', height: 'auto'}}
  />
  <img
    src={require('./images/enhanced_injection_detection/enhanced_injection_detection_focus.jpg').default}
    alt="enhanced_injection_detection_focus"
    style={{width: '38%', height: 'auto'}}
  />
</div>

#### NFC

Data extraction from eMRTD documents, for example passports.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img src={require('./images/capturing_methods/nfc_scanning_01.jpg').default} alt="NFC Help" style={{width: '38%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/nfc_scanning_02.jpg').default} alt="NFC Scanning" style={{width: '38%', height: 'auto'}} />
</div>

#### Linefinder (deprecated)

**_As of SDK version 4.7.0 this module has been deprecated. Please use [Autocapture](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_faq.md#autocapture)
instead._**
Scanning using edge detection.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img src={require('./images/capturing_methods/linefinder_scanning_01.jpg').default} alt="Linefinder Empty" style={{width: '32%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/linefinder_scanning_02.jpg').default} alt="Linefinder Document" style={{width: '32%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/linefinder_scanning_03.jpg').default} alt="Linefinder Processing" style={{width: '32%', height: 'auto'}} />
</div>
#### MRZ (deprecated)

**_As of SDK version 4.7.0 this module has been deprecated. Please use [Autocapture](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_faq.md#autocapture)
instead._**
Data extraction from passports, some identity cards and some visas.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img src={require('./images/capturing_methods/mrz_scanning_01.jpg').default} alt="MRZ Empty" style={{width: '48%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/mrz_scanning_02.jpg').default} alt="MRZ Document" style={{width: '48%', height: 'auto'}} />
</div>

#### Barcode (deprecated)

**_As of SDK version 4.7.0 this module has been deprecated. Please use [Autocapture](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_faq.md#autocapture)
instead._**
PDF417 barcode data extraction, for example from US and Canadian driver licenses.

<div style={{display: 'flex', gap: '10px', flexWrap: 'wrap'}}>
  <img src={require('./images/capturing_methods/barcode_scanning_01.jpg').default} alt="Barcode Empty" style={{width: '48%', height: 'auto'}} />
  <img src={require('./images/capturing_methods/barcode_scanning_02.jpg').default} alt="Barcode Document" style={{width: '48%', height: 'auto'}} />
</div>

## Glossary

A [quick guide to commonly used abbreviations](integration_glossary.md) throughout the documentation which may not be all that familiar.

## Google Play Store Prominent Disclosure

Some parts of the SDK might require prominent disclosure - please see the [Privacy Notice](integration_guide.md#privacy-notice) section in the Integration Guide for further details

## Packaging Options

Multiple third party android libraries include the same meta files which will result in duplicates files during the build.
To get rid of them the following packagingOptions can be added to the build.gradle file:

```
android {
...
    packagingOptions {
    	...
		resources.pickFirsts.add("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
		resources.pickFirsts.add("META-INF/kotlin-project-structure-metadata.json")
		resources.pickFirsts.add("META-INF/kotlinx_coroutines_core.version")
		resources.excludes.add("META-INF/androidx/**/LICENSE.txt")
		resources.excludes.add("META-INF/LICENSE.md")
		resources.excludes.add("META-INF/LICENSE-notice.md")
		resources.excludes.add("commonMain/**/*")
		resources.excludes.add("linuxMain/**/*")
		resources.excludes.add("nativeMain/**/*")
		resources.excludes.add("nonJvmMain/**/*")
    	...
    }
}
```

## minSdkVersion 23 increases APK Size

Starting with API level 23, the Android platform can read native libraries directly from the APK without extracting them to save storage space.
Therefore native libraries are uncompressed when the minSdkVersion is 23 or up resulting in a much bigger apk size.
To get the same behaviour as with minSdkVersion 21 builds you can add the following packagingOptions

```
android {
...
    packagingOptions {
    	...
		jniLibs.useLegacyPackaging true
    	...
    }
}
```

## Jumio Support

The Jumio development team is constantly striving to optimize the size of our frameworks while increasing functionality, to improve your KYC and to fight fraud. If you have any further questions, please reach out to our [support team](mailto:support@jumio.com).

---

# Changelog

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/changelog

![Header Graphic](images/jumio_feature_graphic.jpg)

<div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
  <a href="../README_Android.md#release-notes">
    <img src="https://img.shields.io/github/v/release/Jumio/mobile-sdk-android?style=flat" alt="Version" />
  </a>
  <a href="https://jumio.github.io/mobile-sdk-android/">
    <img src="https://img.shields.io/github/v/release/Jumio/mobile-sdk-android?label=API%20doc&color=green&style=flat" alt="API Doc" />
  </a>
  <a href="../README_Android.md#copyright">
    <img src="https://img.shields.io/badge/license-commercial-3D3D3D?style=flat" alt="License" />
  </a>
  <a href="../README_Android.md#general-requirements">
    <img src="https://img.shields.io/badge/platform-Android-lightgrey?style=flat" alt="Platform" />
  </a>
  <a href="../README_Android.md#general-requirements">
    <img src="https://img.shields.io/badge/API%20level-24+-orange?style=flat" alt="API Level" />
  </a>
  <a href="../README_Android.md#integration">
    <img src="https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Frepo.mobile.jumio.ai%2Fcom%2Fjumio%2Fandroid%2Fcore%2Fmaven-metadata.xml?style=flat" alt="Maven" />
  </a>
</div>

[Improvement]: https://img.shields.io/badge/Improvement-green 'Improvement shield'
[Change]: https://img.shields.io/badge/Change-blue 'Change shield'
[Fix]: https://img.shields.io/badge/Fix-success 'Fix shield'

# Change Log

All notable changes, such as SDK releases, updates and fixes, are documented in this file.
For detailed technical changes please refer to our [Transition Guide](transition_guide.md).

## Support Period

Current SDK version: 4.18.0

Please refer to our [SDK maintenance and support policy](maintenance_policy.md) for more information about Mobile SDK maintenance and support.

## SDK Version: 4.18.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Global Digital ID Acceptance.

![Improvement](https://img.shields.io/badge/Improvement-green) Added controls for limiting and preventing Manual Capture (ID and Selfie).

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for localized default consent links.

![Change](https://img.shields.io/badge/Change-blue) The SDK's minSdkVersion has been increased to 24 (Nougat). Please check the [Transition Guide](transition_guide.md) for details.

## SDK Version: 4.17.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for the [Selfie.Done](https://www.jumio.com/products/selfie-done/) workflow.

![Improvement](https://img.shields.io/badge/Improvement-green) Redesigned loading screens.

## SDK Version: 4.16.0

![Improvement](https://img.shields.io/badge/Improvement-green) Redesign of the ID Autocapture user experience.

![Improvement](https://img.shields.io/badge/Improvement-green) Support for image upload for DocProof workflows.

![Improvement](https://img.shields.io/badge/Improvement-green) Support for Liveness capture using back camera.

## SDK Version: 4.15.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for NFC read-only scanning.

![Improvement](https://img.shields.io/badge/Improvement-green) Introduced a configurable max retry count for NFC scanning.

![Improvement](https://img.shields.io/badge/Improvement-green) Included NFC scanning result status in transaction details via the Retrieval API.

![Improvement](https://img.shields.io/badge/Improvement-green) Enhanced user experience for NFC scanning with automatic NFC chip location detection.

## SDK Version: 4.14.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added enhanced virtual camera injection detection [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Digital Identity using eIDAS for selected countries [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Accessibility updates for compliance with WCAG 2.2 AA and EAA.

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Digital Identity using eIDAS for selected countries [ID Verification]

![Fix](https://img.shields.io/badge/Fix-success) Added `kotlin.Pair` to `consumer-rules.pro` for SDK Wrapper

## SDK Version: 4.13.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for NFC Extraction of IDs

![Fix](https://img.shields.io/badge/Fix-success) Various bug fixes and improvements

## SDK Version: 4.12.1

![Fix](https://img.shields.io/badge/Fix-success) Rare crashes in Jumio Liveness

![Fix](https://img.shields.io/badge/Fix-success) Liveness Images not available

![Fix](https://img.shields.io/badge/Fix-success) Issues with CameraX not selecting a Camera

## SDK Version: 4.12.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Jumio Liveness Premium with enhanced deepfake detection [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Brazilian Digital Driver's License [ID Verification]

![Fix](https://img.shields.io/badge/Fix-success) Multiple bug fixes and improvements

![Change](https://img.shields.io/badge/Change-blue) Updated Android sample application UI, transitioning from XML-based layouts to using Jetpack Compose

## SDK Version: 4.11.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added tilted image capture for frontside of ID documents. Enhanced checks of certain document security features [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added unsupported documents check to improve quality of extracted data and improve user experience [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added an updated Authentication Service [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed issues with code obfuscation

## SDK Version: 4.10.0

Added `kotlin.Pair` to `co
![Improvement](https://img.shields.io/badge/Improvement-green) Support for 4k Image capture. Improved ML model input, enhanced image and fraud checks [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added flash capture for frontside of ID documents. Enhanced checks of certain document security features [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for Serbian language, for both Cyrillic and Latin [ID Verification, Selfie Verification, Document Verification]

## SDK Version: 4.9.1

![Fix](https://img.shields.io/badge/Fix-success) Fixed a rare issue that could lead to a crash when the SDK is recreated

## SDK Version: 4.9.0

![Improvement](https://img.shields.io/badge/Improvement-green) Automated document and country selection, powered by classifer ML model [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added possibility to pre-load required ML models. For more information checkout the according section in the [README](../README_Android.md#ml-models) [ID Verification, Identity Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Major UI Redesign [ID Verification, Selfie Verification, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved Liveness retry logic. Prepared for granular instant feedback, if configured accordingly [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 9.0.3 [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for R8's `fullMode` for code shrinking and obfuscation

![Change](https://img.shields.io/badge/Change-blue) Removed Device Risk module from SDK [Selfie Verification]

## SDK Version: 4.8.2

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 8.5.2 [Selfie Verification]

## SDK Version: 4.8.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.8.0

![Improvement](https://img.shields.io/badge/Improvement-green) Managing Liveness dependencies to help better conversion [Selfie Verification]

## SDK Version: 4.7.2

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 8.5.2 [Selfie Verification]

## SDK Version: 4.7.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.7.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for [CameraX](https://developer.android.com/training/camerax)

![Improvement](https://img.shields.io/badge/Improvement-green) Datadog SDK version update to 2.0: Added possibility to have a dedicated Jumio Datadog instance

![Improvement](https://img.shields.io/badge/Improvement-green) Improved Jumio Liveness capturing experience [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Updated Jumio Liveness module [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Removed previous scanning functionalities, now all included in Autocapture functionality [ID Verification]

![Change](https://img.shields.io/badge/Change-blue) Removed Microblink barcode scanning, switched to MLkit [ID Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed Liveness customization bug [Selfie Verification]

## SDK Version: 4.6.2

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 8.5.2 [Selfie Verification]

## SDK Version: 4.6.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.6.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added Jumio Liveness module to enhance the Liveness user experience and interface (Selfie Verification)

![Improvement](https://img.shields.io/badge/Improvement-green) Improved Liveness customization options (Selfie Verification)

## SDK Version: 4.5.2

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 8.5.2 [Selfie Verification]

## SDK Version: 4.5.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.5.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added possibility for users to verify their identity using [Digital Identity](../README_Android.md#digital-identity) [ID Verification, Identity Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 8.3.1 [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved user consent handling [ID Verification, Selfie Verification]

<details>     
<summary>More details</summary>

### User consent

User consent is now acquired for all users to ensure the accordance with biometric data protection laws. Please also refer to the [User Consent section](integration_faq.md#user-consent) in our FAQ.

</details>

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, passport scanning issue for certain countries [ID Verification]

## SDK Version: 4.4.2

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.4.1

![Fix](https://img.shields.io/badge/Fix-success) Bug fix: Internal crashes for certain edge cases

## SDK Version: 4.4.0

![Improvement](https://img.shields.io/badge/Improvement-green) Fully redesigned ID Autocapture experience - seamless capturing, precise guidance and faster user journey [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Major iProov SDK version update to 8.0.3 - no more face scanning filter, improved UI and more customization options [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Mandatory NFC scanning option [ID Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, internal crashes

## SDK Version: 4.3.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.3.0

![Improvement](https://img.shields.io/badge/Improvement-green) Autocapture functionality (introduced in SDK 4.2.0) is no longer in beta stage [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) [Document Verification](../README_Android.md#document-verification) functionality added.

![Improvement](https://img.shields.io/badge/Improvement-green) Improved user guidance: Clear distinction between scanning frontside or backside of ID document [ID Verification]

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 7.5.0 [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) The SDK's minSdkVersion has been increased to 21 (Lollipop). Please check the [Transition Guide](transition_guide.md) for details.

![Fix](https://img.shields.io/badge/Fix-success) UI bugs, internal crashes [Selfie Verification]

## SDK Version: 4.2.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.2.0

![Improvement](https://img.shields.io/badge/Improvement-green) Alignment of previously existing scanning method and improved user experience through addition of Autocapture module (Beta) [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for device fingerprint capability [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Addition of NFC image extraction for similarity check [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved liveness customization: Centered Floating prompt for better user guidance during face scanning [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, internal crashes

## SDK Version: 4.1.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 4.1.0

![Improvement](https://img.shields.io/badge/Improvement-green) Improved, granular user feedback for improved user experience and workflow through addition of Instant Feedback [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for Dark Mode for DefaultUI and CustomUI [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Addition of optional Datadog diagnostics module for monitoring SDK behavior and performance, as well as more efficient troubleshooting

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 7.2.0 [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, security improvements, internal crashes

## SDK Version: 4.0.0

This is a complete rewrite of our SDK. The SDK was built with CustomUI as a basis and restructured to align Android and iOS to reduce overall complexity and integration effort.

![Improvement](https://img.shields.io/badge/Improvement-green) Improved security by switching to one-time authorization tokens for SDK initialization instead of relying on API token and secret

![Improvement](https://img.shields.io/badge/Improvement-green) Redesigned Default UI flow

![Improvement](https://img.shields.io/badge/Improvement-green) Slimline SDK configuration of only 1.8 MB size

![Improvement](https://img.shields.io/badge/Improvement-green) Improved data extraction via enhancing the SDK capabilities with server-side extraction capabilities

![Improvement](https://img.shields.io/badge/Improvement-green) Manual capture is now available as a fallback option for all other capture methods

## SDK Version: 3.9.5

![Fix](https://img.shields.io/badge/Fix-success) Removed Location handling to fix potential Google Play Store rejections

## SDK Version: 3.9.4

![Changes](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 6.4.3 [Selfie Verification]

## SDK Version: 3.9.3

![Changes](https://img.shields.io/badge/Improvement-green) Internal dependency update [Selfie Verification]

## SDK Version: 3.9.2

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 6.4.1, which improves performance and offers additional customization options [Selfie Verification]

## SDK Version: 3.9.1

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 6.3.1, which fixes cross-dependency problems with OkHttp 4.x versions [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved customization options [Selfie Verification]

## SDK Version: 3.9.0

![Improvement](https://img.shields.io/badge/Improvement-green) Improved SDK lifecycle and state handling to reduce specific scenarios in which SDK crashes could have happened [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved retry guidance for Selfie Verification [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved customization options [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added more granular differentiations for `ScanMode` in CustomUI [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed rare issue that caused "Blur Hint" toast being displayed multiple times on certain devices [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed possible Camera Exception using CustomUI [ID Verification/Fastfill, Selfie Verification, Authentication]

![Fix](https://img.shields.io/badge/Fix-success) Fixed possible app crash when calling `NetverifyCustomSDKController.retry()` [ID Verification/Fastfill, Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed Zoom Authentication 412 error handling, preventing user from getting stuck in certain scenarios [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Removed deprecated Android Kotlin plugins [ID Verification/Fastfill, Selfie Verification, Authentication, Document Verification]

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 6.3.0, which includes accuracy improvements using Liveness Assurance [Selfie Verification]

## SDK Version: 3.8.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added better guidance for devices with a fixed focal distance [ID Verification/Fastfill, Document Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed crashes that could occur in edge cases [ID-Verification, Identity-Verification]

![Change](https://img.shields.io/badge/Change-blue) Added iProov as an additional liveness vendor to the [Jumio KYX platform](https://www.jumio.com/kyx/) [Selfie Verification]

## SDK Version: 3.7.3

![Improvement](https://img.shields.io/badge/Improvement-green) New error code is returned in case an ad blocker or a firewall is detected [ID Verification/Fastfill, Authentication, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added additional 3D Liveness customization options [ID Verification, Authentication]

![Fix](https://img.shields.io/badge/Fix-success) Fixed stroke color customization on negative action button [ID Verification/Fastfill, Authentication, Document Verification]

![Fix](https://img.shields.io/badge/Fix-success) Fixed compatibility issues caused by Firebase Performance Plugin.

## SDK Version: 3.7.2

![Fix](https://img.shields.io/badge/Fix-success) Fixed a problem that face could not be captured anymore in certain cases [ID Verification Custom UI]

## SDK Version: 3.7.1

![Fix](https://img.shields.io/badge/Fix-success) Fixed problem in handling the user consent [ID Verification, Authentication]

## SDK Version: 3.7.0

![Change](https://img.shields.io/badge/Change-blue) Full redesign of NFC passport workflow [ID Verification]

![Change](https://img.shields.io/badge/Change-blue) Update to newest 3D Liveness technology [ID Verification, Authentication]

![Change](https://img.shields.io/badge/Change-blue) Adjusted Jumio logo and default color to reflect new Jumio appearance [ID Verification/Fastfill, Authentication, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support of 24 new languages [ID Verification/Fastfill, Authentication, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Possibility to retrieve the captured images directly in the SDK [ID Verification/Fastfill]

## SDK Version: 3.6.2

![Improvement](https://img.shields.io/badge/Improvement-green) Security enhancements [Netverify/Fastfill, Authentication, Document Verification, BAM Checkout]

## SDK Version: 3.6.1

![Fix](https://img.shields.io/badge/Fix-success) Fixed wrong date parsing on magstripe encoded barcodes [Netverify/Fastfill]

## SDK Version: 3.6.0

![Change](https://img.shields.io/badge/Change-blue) Added support for right-to-left languages [Netverify/Fastfill, Authentication, Document Verification]

![Change](https://img.shields.io/badge/Change-blue) Provide access to document guidance animation [Netverify Custom UI]

![Change](https://img.shields.io/badge/Change-blue) Advanced custom UI sample implementation [Netverify Custom UI Sample]

![Change](https://img.shields.io/badge/Change-blue) Adjusted handling of document types which don’t support plastic documents [Netverify]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for 5 new languages (Czech, Greek, Hungarian, Polish, Romanian) [Netverify/Fastfill, Authentication, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved accessibility handling [Netverify/Fastfill, Authentication, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Reduced SDK size by ~1.5 MB [Netverify/Fastfill, Authentication, Document Verification, BAM Checkout]

![Fix](https://img.shields.io/badge/Fix-success) Various smaller bug fixes/improvements [Netverify/Fastfill, Authentication, Document Verification]

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. [Check it out at here.](https://support.jumio.com.)

---

# Maintenance Policy

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/docs/maintenance_policy

![Header Graphic](images/jumio_feature_graphic.jpg)

# Maintenance and Support Policy

## Overview

This document outlines the maintenance policy for Jumio’s Software Development Kits (“SDKs”), including Mobile and Web SDK and their dependencies.
Our SDK releases are published publicly as indicated in our documentation as well as to package managers. Documentation and sample implementations are available as source code on GitHub ([Android](https://github.com/Jumio/mobile-sdk-android) and [iOS](https://github.com/Jumio/mobile-sdk-ios)).

We are consistently updating the Jumio SDKs in order to provide the best possible experience for you. Upgrading to the latest SDK version will not only ensure you benefit from various performance enhancements and bug fixes, but will also allow you to take advantage of new capabilities. All releases undergo comprehensive testing by our teams before being deployed.

If you are using a Mobile SDK, please ensure your apps have been released and your end-users have updated before the End-of-Support date. Jumio does not provide support after the End-of-Support date.

Customers should review the [Jumio Terms and Conditions](https://www.jumio.com/legal-information/privacy-notices/) for requirements related to the implementation of updates.

## Versioning

Jumio SDK release versions are in the form of X.Y.Z:

- X major version - very rarely updated
- Y minor version - normally updated once in a quarter
- Z patch version - updated on demand

Major versions of Jumio’s SDKs are released rarely, and only in case of substantial changes to support new features and patterns. Breaking changes can happen in Major and Minor versions. Applications need to be updated in order for them to work with the newest SDK version. Breaking changes are highlighted in our [Android](https://github.com/Jumio/mobile-sdk-android) and [iOS](https://github.com/Jumio/mobile-sdk-ios) implementation guides for each release.

Jumio will only provide patches or additional updates on the latest version regardless if it’s Major, Minor or Patch.

## SDK Version Lifecycle

The life-cycle for SDK versions consists of these phases, which are outlined below:

- **Developer Preview** (Phase 0) - During this phase, SDKs are not supported, must not be used in production environments, and are meant for early access and feedback purposes only. It is possible for future releases to introduce breaking changes. It can be alpha, beta, or release candidate.

- **General availability / Full support** (Phase 1) - During this phase, SDKs are fully supported. Jumio will provide active support on this version and will provide required bug fixes or security fixes within new / upcoming versions (major, minor, patch).

- **End-of-Support** (Phase 2) - Each SDK version reaches end of support 9 months after the release date. Issues that appear after the End-of-Support date will only be addressed in the upcoming SDK releases. Previously published releases will continue to be available via public package managers and the code will remain on GitHub. Use of an SDK that has reached End-of-Support is done at the business customers’ discretion. We recommend upgrading to the latest version.

- **End-of-Life** (Phase 3) - By default, our SDK will reach the end of life 24 months after the release date. The SDK may continue to work but Jumio will no longer provide support or updates. Customers will be notified at least 3 months prior to the end of life of a product should it be less than 24 months.

The following table is a visual representation of the SDK 4.x.x version life-cycle.  
⚠️&nbsp;&nbsp;SDK 3.x.x has reached its End-of-Life on December 31, 2023.

| Version |      Release      |  End of Support   |    End of Life    |
|:-------:|:-----------------:|:-----------------:|:-----------------:|
| 4.18.0  |   10 July 2026    |   10 April 2027   |   10 July 2028    |
| 4.17.0  |   16 March 2026   | 16 December 2026  |   16 March 2028   |
| 4.16.0  | 11 February 2026  | 11 November 2026  | 11 February 2028  |
| 4.15.0  |  10 October 2025  |   10 July 2026    |  10 October 2027  |
| 4.14.0  | 3 September 2025  |    3 June 2026    | 3 September 2027  |
| 4.13.0  |   3 April 2025    |  3 January 2026   |   3 April 2027    |
| 4.12.1  |  14 January 2025  | 6 September 2025  |  6 December 2026  |
| 4.12.0  |  6 December 2024  | 6 September 2025  |  6 December 2026  |
| 4.11.0  |  20 August 2024   |    20 May 2025    |  20 August 2026   |
| 4.10.0  |    5 June 2024    |   5 March 2025    |    5 June 2026    |
|  4.9.1  |   3 April 2024    | 21 November 2024  | 21 February 2026  |
|  4.9.0  | 21 February 2024  | 21 November 2024  | 21 February 2026  |
|  4.8.2  |   7 March 2024    |  7 December 2024  |   7 March 2026    |
|  4.8.1  |  23 October 2023  |   17 July 2024    |  17 October 2025  |
|  4.8.0  |  17 October 2023  |   17 July 2024    |  17 October 2025  |
|  4.7.2  |   7 March 2024    |  7 December 2024  |   7 March 2026    |
|  4.7.1  |  23 October 2023  |   27 June 2024    | 27 September 2025 |
|  4.7.0  | 27 September 2023 |   27 June 2024    | 27 September 2025 |
|  4.6.2  |   7 March 2024    |  7 December 2024  |   7 March 2026    |
|  4.6.1  |  23 October 2023  |   5 March 2024    |    5 June 2025    |
|  4.6.0  |    5 June 2023    |   5 March 2024    |    5 June 2025    |
|  4.5.2  |   7 March 2024    |  7 December 2024  |   7 March 2026    |
|  4.5.1  |  23 October 2023  |  14 January 2024  |   14 April 2025   |
|  4.5.0  |   14 April 2023   |  14 January 2024  |   14 April 2025   |
|  4.4.2  |  23 October 2023  |  18 October 2023  |  18 January 2025  |
|  4.4.1  |  18 January 2023  |  18 October 2023  |  18 January 2025  |
|  4.4.0  | 20 December 2022  | 20 September 2023 | 20 December 2024  |
|  4.3.1  |  23 October 2023  | 25 February 2023  |    25 May 2024    |
|  4.3.0  |  30 August 2022   |    30 May 2023    |  30 August 2024   |
|  4.2.1  |  23 October 2023  | 25 February 2023  |    25 May 2024    |
|  4.2.0  |    25 May 2022    | 25 February 2023  |    25 May 2024    |
|  4.1.1  |  23 October 2023  | 28 November 2022  | 28 February 2024  |
|  4.1.0  | 28 February 2022  | 28 November 2022  | 28 February 2024  |
|  4.0.0  | 16 November 2021  |  16 August 2022   | 16 November 2023  |

## Upgrade & Maintenance Practices

- Follow Semantic Versioning and test updates in staging.
- Monitor documentation (https://github.com/Jumio/{Platform}/releases) for changes and depreciation notices.
- Perform regression testing after upgrades.

## Troubleshooting

- Share workflowExecutionId, app version, OS, device, timestamp, and screenshots with support.

---

# Native iOS SDK

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/README_iOS

![Jumio](docs/images/jumio_feature_graphic.jpg)

<div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
  <a href="#release-notes"><img src="https://img.shields.io/github/v/release/Jumio/Mobile-SDK-IOS?style=flat" alt="Version" /></a>
  <a href="https://jumio.github.io/mobile-sdk-ios/Jumio/"><img src="https://img.shields.io/github/v/release/Jumio/Mobile-SDK-IOS?label=API%20doc&color=green&style=flat" alt="API Doc" /></a>
  <a href="#copyright"><img src="https://img.shields.io/cocoapods/l/JumioMobileSDK.svg?style=flat" alt="License" /></a>
  <a href="#general-requirements"><img src="https://img.shields.io/cocoapods/p/JumioMobileSDK.svg?style=flat" alt="Platform" /></a>
  <a href="https://cocoapods.org/pods/Jumio"><img src="https://img.shields.io/cocoapods/v/Jumio.svg?style=flat" alt="Pod Version" /></a>
  <a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage" /></a>
  <a href="https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/"><img src="https://img.shields.io/badge/Swift_Package_Manager-compatible-orange?style=flat-square" alt="SPM" /></a>
  <a href="https://swift.org/"><img src="https://img.shields.io/badge/Swift-4.x,%205.x%20&%206.x-orange.svg?style=flat" alt="Carthage" /></a>
</div>

## Overview

The Jumio Software Development Kit (SDK) provides you with a set of tools and UIs (default or custom) to develop an iOS application perfectly fitted to your specific needs.

Onboard new users and easily verify their digital identities, by making sure the IDs provided by them are valid and authentic. Extract data from ID documents completely automatically and within seconds. Confirm users really are who they say they are by having them take a quick selfie and match it to their respective documents. Jumio uses cutting-edge biometric technology to make sure there is an actual, real-life person in front of the screen.

![SDK Overview](docs/images/images_overview/images_overview.png)

Using the Jumio SDK will allow you to create the best possible solution for your individual needs, providing you with a range of different services to choose from.

---

# Get Started

Please note that [basic setup](#basics) is required before continuing with the integration of any of the following services.

## Jumio SDK Integration

Jumio KYX platform and related services are a secure and easy solution that allows you to establish the genuine identity of your users in your mobile application, by verifying their passports, government-issued IDs and actual liveness in real-time. Very user-friendly and highly customizable, it makes onboarding new customers quick and simple.

:arrow_right:&nbsp;&nbsp;[SDK INTEGRATION GUIDE](docs/integration_guide.md)  
:arrow_right:&nbsp;&nbsp;[Changelog](docs/changelog.md)  
:arrow_right:&nbsp;&nbsp;[Transition Guide](docs/transition_guide.md)

#### Previous SDK Versions

If you need information on older SDK versions, please refer to:

- [3.9.4](https://github.com/Jumio/mobile-sdk-ios/tree/v3.9.4)
- [3.9.3](https://github.com/Jumio/mobile-sdk-ios/tree/v3.9.3)
- [3.9.2](https://github.com/Jumio/mobile-sdk-ios/tree/v3.9.2)
- [3.9.1](https://github.com/Jumio/mobile-sdk-ios/tree/v3.9.1)
- [3.9.0](https://github.com/Jumio/mobile-sdk-ios/tree/v3.9.0)

## Code Documentation

Full API documentation for the Jumio iOS SDK can be found [here](https://jumio.github.io/mobile-sdk-ios/Jumio).

## FAQ

Link to Jumio iOS SDK FAQ can be found [here](docs/integration_faq.md).

## Known Issues

List of known issues can be found [here](docs/known_issues.md).

---

# Quickstart

This section provides a quick overview on how to get started with the [iOS sample application](https://github.com/Jumio/mobile-sdk-ios/tree/master/sample) that can be found here on Github. You will require a **commercial Jumio License** to successfully run any of our examples; for details, contact sales@jumio.com. You will also need a current Xcode version to open and try out the sample project.

Start by downloading the iOS sample application from the Jumio Github repo. You can do this either by cloning the repo (using SHH oder HTTPS) to your local device or simply downloading everything as a ZIP. Once you’ve got the sample application downloaded and unzipped if necessary, open Xcode. You’ll be faced with a couple of options. Choose **Open another project** in the bottom right corner and navigate to where you’ve saved your sample application. Select the **SampleApp.xcodeproj** and open it.

You also have the option of simply starting Xcode and choosing the option **Clone an existing project** in the left-hand menu. In this case, you’ll need to add the URL of the [entire repository on Github](https://github.com/Jumio/mobile-sdk-ios). If prompted, choose **master** and start cloning to your local device.

When the cloning is done, once again just choose the **SampleApp.xcodeproj** and open it.

**Note:** Our sample project on GitHub contains the sample implementation without our frameworks. The project contains a pre-action run script `jumio-sdk-checkout.sh`, which downloads our frameworks automatically during build time.

The iOS sample application contains two packages `CustomUI` and `DefaultUI`, as well as Delegates and the classes `ViewController.swift` and `ResultViewController.swift`. Use the ViewController class to either start CustomUI or DefaultUI by using a valid SDK token and data center.

If you haven't done so already, please refer to the [Authentication and Encryption section](#authentication-and-encryption) for more details on how to obtain your SDK token. Add your individual SDK token instead of the placeholder `""`. The default setting for the data center is `JumioDataCenter.US`.

⚠️&nbsp;&nbsp;**Note:** We strongly recommend not storing any credentials inside your app! We suggest loading them during runtime from your server-side implementation.

In the `DefaultUI` package, you will find the class `DefaultUI.swift`. In the `CustomUI` package you will find:

- `ViewController` containing several ViewController classes
- `Handling` containing `ControllerHandling.swift`, `CredentialHandling.swift` and `ScanPartHandling.swift`
- `CustomUINavigationController.swift`

In each class, the most important methods for this service is shown and quickly outlined.

Once you start up the sample application, you'll be given the option of trying out the Jumio SDK. Select a service from the action bar at the bottom to try out different services. Your application will also need camera permission, which will be prompted for automatically once you try to start any of services.

⚠️&nbsp;&nbsp;**Note:** We only support the Jumio SDK on physical devices. The app will compile on simulator, but you won't be able to run the SDK.

---

# Basics

## General Requirements

The minimum requirements for the SDK are:

- iOS 13.0 and higher
- Internet connection
- Jumio KYX or Jumio API v3

The following architectures are supported in the SDK:

- device: arm64
- simulator: arm64 x86_64

## Authentication and Encryption

ℹ️&nbsp;&nbsp;**As of version 4.0.0 and onward, the SDK can only be used in combination with Jumio KYX or Jumio API v3. API v2 as well as using API token and secret to authenticate against the SDK will no longer be compatible.**

Before starting a session in our SDK, an SDK token has to be obtained. Refer to out [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/Integration_Intro) for further details. To authenticate against the API calls, an OAuth2 access token needs to be retrieved from the Jumio Portal.

Within the response of the [Account Creation or Account Update](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) API, an SDK token is returned, which needs to be applied to initiate the mobile SDK.

### Authentication with OAuth2

Your OAuth2 credentials are constructed using your API token as the Client ID and your API secret as the Client secret. You can view and manage your API token and secret in the Jumio Portal under:

- **Settings > API credentials > OAuth2 Clients**

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation.

#### Access Token URL (OAuth2)

- US: `https://auth.amer-1.jumio.ai/oauth2/token`
- EU: `https://auth.emea-1.jumio.ai/oauth2/token`
- SG: `https://auth.apac-1.jumio.ai/oauth2/token`

The [TLS Protocol](https://tools.ietf.org/html/rfc5246) is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [supported cipher suites](https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites#supported-cipher-suites).

ℹ️&nbsp;&nbsp; Calls with missing, incorrect or suspicious headers or parameter values will result in HTTP status code **400 Bad Request Error** or **403 Forbidden**

#### Request Access Token (OAuth2)

```
curl --request POST --location 'https://auth.amer-1.jumio.ai/oauth2/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-raw 'grant_type=client_credentials' \
    --basic --user CLIENT_ID:CLIENT_SECRET
```

#### Response Access Token (OAuth2)

```
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

#### Access Token Timeout (OAuth2)

Your OAuth2 access token is valid for 60 minutes. After the token lifetime is expired, it is necessary to generate a new access token.

### Workflow Transaction Token Timeout

The token lifetime is set to 30 minutes per default. It can be configured via the [Jumio Portal](https://documentation.jumio.ai/docs/portals/welcome_to_the_jumio_portal) and can be overwritten using the API call (`tokenLifetime`). Within this token lifetime the token can be used to initialize the SDK.

As soon as the workflow (transaction) starts, a 15 minutes session timeout is triggered. For each action performed (capture image, upload image) the session timeout will reset, and the 15 minutes will start again.

After creating/updating a new account you will receive a `sdk.token` (JWT) for initializing the SDK. Use this SDK token with your iOS code:

```
sdk = Jumio.SDK()
sdk.token = "YOUR_SDK_TOKEN"
sdk.dataCenter = jumioDataCenter
```

## Permissions

The app’s Info.plist must contain the `NSCameraUsageDescription` key with a string value explaining to the user how the app uses this data. Example: _“This will allow `<your-app-name>` to take photos of your credentials."_

## Integration

The [SDK Setup Tool](https://jumio.github.io/mobile-configuration-tool/out/) is a web tool that helps determine available product combinations and corresponding dependencies for the Jumio SDK, as well as an export feature to easily import the applied changes straight into your codebase.

[![Jumio Setup](docs/images/setup_tool.png)](https://jumio.github.io/mobile-configuration-tool/out/)

Additionally, check out the [Xcode sample project](https://github.com/Jumio/mobile-sdk-ios/tree/master/sample) to learn the most common use. Make sure to use the device only-frameworks for app submissions to the AppStore. Read more detailed information on this here: [Manual integration](docs/integration_guide.md#manually)

## App Thinning and Size Matters

App thinning (app slicing, bitcode and on-demand resources) is supported within the SDK. For app slicing, the image resources are placed within a xcassets collection. For ID Verification, some resource files (e.g. images) are loaded on demand.

## Language Localization

Our SDK supports localization for different languages. All label texts and button titles can be changed and localized using the `Localizable-Jumio.strings` file. Just adapt the values to your required language, add it to your app or framework project and mark it as Localizable. This way, when upgrading our SDK to a newer version your localization file won't be overwritten. Make sure, that the content of this localization file is up to date after an SDK update.

ℹ️&nbsp;&nbsp;**Note:** If using CocoaPods, the original file is located under `/Pods/Jumio/Localizations`.

ℹ️&nbsp;&nbsp;**Note:** If using Swift Package Manager, make sure to add your supported languages in the Info.plist under the CFBundleLocalizations key.

Jumio SDK products support following languages for your convenience:

_Afrikaans, Arabic, Bulgarian, Burmese, Chinese (Simplified), Chinese (Traditional), Croatian, Czech, Danish, Dutch, Estonian, English, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Khmer, Korean, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese (Portugal), Portuguese (Brazil), Romanian, Russian, Serbian (Cyril), Serbian (Latin), Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese, Zulu_

Please check out our [sample project](https://github.com/Jumio/mobile-sdk-ios/tree/master/sample) to see how to use the strings files in your app.

Our SDK supports accessibility features. Visually impaired users can enable **VoiceOver** or increase **text size** on their device. VoiceOver uses separate values in the localization file, which can be customized.

---

# ML Models

The Jumio SDK utilizes ML Models to enable client-/server-side verification.

Required models can be provided by downloading and adding them manually to the bundle or preloading them. The SDK will load them on demand if none of the previous is applied.

Loading the models in advance will improve startup time of the SDK.

For more details, please refer to our [integration guide](docs/integration_guide.md#ml-models).

---

# Document Verification

As of iOS SDK 4.3.0, Document Verification functionality is available.
This functionality allows users to submit a number of different document types (e.g. a utility bill or bank statement) in digital form and verify the validity and authenticity of this document.

Documents can be submitted using one of two ways: Taking a photo of the document or uploading a file.
For more details, please refer to our [integration guide](docs/integration_guide.md#jumio-document-credential).

### Supported Documents:

- BC (Birth certificate)
- BS (Bank statement)
- CAAP (Cash advance application)
- CB (Council bill)
- CC (Credit card)
- CCS (Credit card statement)
- CRC (Corporate resolution certificate)
- CUSTOM (Custom document type)
- HCC (Health care card)
- IC (Insurance card)
- LAG (Lease agreement)
- LOAP (Loan application)
- MEDC (Medicare card)
- MOAP (Mortgage application)
- PB (Phone bill)
- SEL (School enrollment letter)
- SENC (Seniors card)
- SS (Superannuation statement)
- SSC (Social security card)
- STUC (Student card)
- TAC (Trade association card)
- TR (Tax return)
- UB (Utility bill)
- VC (Voided check)
- VT (Vehicle title)
- WWCC (Working with children check)

ℹ️&nbsp;&nbsp;**Note:** To enable the use of this feature, please contact [Jumio support](https://support.jumio.com).

---

# Digital Identity

As of Jumio iOS SDK 4.5.0, users may use their Digital Identity to verify their identity.
For now, 'Brazil CNH-e PDF', 'ID by Mastercard' and 'eIDAS' are the only Digital Identity providers supported by our SDK.

If you want to enable Digital Identity verification for your account please [contact us](https://support.jumio.com).
In case you are already set up to use Digital Identity verificaiton within your app, check out the integration steps explained [here](docs/integration_guide.md#digital-identity-setup).

---

# Security

All SDK related traffic is sent over HTTPS using TLS and public key pinning, and additionally, the information itself within the transmission is also encrypted utilizing **Application Layer Encryption** (ALE). ALE is Jumio custom-designed security protocol which utilizes RSA-OAEP and AES-256 to ensure that the data cannot be read or manipulated even if the traffic was captured.

---

# Release Notes

Please refer to our [Change Log](docs/changelog.md) for more information about our current SDK version and further details.

# Maintenance and Support

Please refer to our [SDK maintenance and support policy](docs/maintenance_policy.md) for more information about Mobile SDK maintenance and support.

## Two-factor Authentication

If you want to enable two-factor authentication for your Jumio Portal account [please contact us.](https://support.jumio.com). Once enabled, users will be guided through the setup upon their first login to obtain a security code using the "Google Authenticator" app.

## Licenses

The source code and software available on this website (“Software”) is provided by Jumio Corporation or its affiliated group companies (“Jumio”) “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Jumio be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services, loss of use, data, profits, or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this Software, even if advised of the possibility of such damage.

In any case, your use of this Software is subject to the terms and conditions that apply to your contractual relationship with Jumio. As regards Jumio’s privacy practices, please see our privacy notice available here: [Privacy Policy](https://www.jumio.com/privacy-center/privacy-notices/online-services-notice/).

The software contains third-party open source software. For more information, please see [licenses](licenses).

This software is based in part on the work of the Independent JPEG Group.

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. [Check it out at here](https://support.jumio.com).

## Copyright

&copy; Jumio Corporation, 100 Mathilda Place Suite 100 Sunnyvale, CA 94086

---

# Integration Guide

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/integration_guide

![Header Graphic](images/jumio_feature_graphic.jpg)

# Integration Guide for iOS SDK

Jumio’s products allow businesses to establish the genuine identity of their users by verifying government-issued IDs in real-time. ID Verification, Selfie Verification and other services are used by financial service organizations and other leading brands to create trust for safe onboarding, money transfers and user authentication.

## Release Notes

Please refer to our [Change Log](changelog.md) for more information. Current SDK version: **4.18.0**

For technical changes that should be considered when updating the SDK, please read our [Transition Guide](transition_guide.md).

## Code Documentation

Full API documentation for the Jumio iOS SDK can be found [here](https://jumio.github.io/mobile-sdk-ios/Jumio).

## Setup

The [basic setup](../README_iOS.md#basics) is required before continuing with the following setup for the Jumio SDK. If you are updating your SDK to a newer version, please also refer to:

:arrow_right:&nbsp;&nbsp;[Changelog](changelog.md)  
:arrow_right:&nbsp;&nbsp;[Transition Guide](transition_guide.md)

### Dependencies

#### Via Cocoapods

Jumio supports CocoaPods as dependency management tool for easy integration of the SDK. You are required to use **Cocoapods 1.11.0** or newer.

If you are not yet using Cocoapods in your project, first run:

```
sudo gem install cocoapods
pod init
```

Then update your local clone of the specs repo in Terminal to ensure that you are using the latest podspec files using:

```
pod repo update
```

Adapt your Podfile and add the pods according to the product(s) you want use. Check the following example how a Podfile could look like, with a list of all available Jumio pods:

:::note
Please do not include everything! Make sure to **only** use pods that provide to the services you need! It's only possible to add 1 core functionality, but as many addons as needed.
:::

```
source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '13.0'
use_frameworks! # Required for proper framework handling

#Core (always add):
pod 'Jumio/Jumio', '~>4.18.0' # Manual & DocFinder Capture

#Addons:
pod 'Jumio/Liveness', '~>4.18.0' # Liveness functionality
pod 'Jumio/DefaultUI', '~>4.18.0' # Default UI functionality
pod 'Jumio/NFC', '~>4.18.0' # NFC functionality

#All:
pod 'Jumio/All', '~>4.18.0' # All Jumio products with all available scanning methods
```

#### Via Swift Package Manager

Jumio supports Swift Package Manager for easy integration of the SDK for version **4.4.0 and above**.

To integrate the Jumio SDK with Swift Package Manager, add this [repo](https://github.com/Jumio/mobile-sdk-ios.git) as a dependency to your project.

The Jumio SDK contains five different targets. Add them to your project based on the functionality that you need in your application.

```

#Core (always add):
Jumio # Manual & DocFinder Capture

#Addons:
JumioLiveness # Jumio liveness functionality
JumioDefaultUI # Default UI functionality
JumioNFC # NFC functionality
JumioLocalization # Adds strings for localization

```

#### Via Carthage

Starting from SDK 4.5.0 Jumio supports Carthage as dependency management tool for easy integration of the SDK.

Adapt you Cartfile and add Jumio dependencies. Check the following example how a Cartfile could look like:

```

#Core (always add):
binary "https://raw.githubusercontent.com/Jumio/mobile-sdk-ios/master/Carthage/Jumio.json" == 4.18.0

#Addons:
binary "https://raw.githubusercontent.com/Jumio/mobile-sdk-ios/master/Carthage/JumioLiveness.json" == 4.18.0
binary "https://raw.githubusercontent.com/Jumio/mobile-sdk-ios/master/Carthage/JumioDefaultUI.json" == 4.18.0
binary "https://raw.githubusercontent.com/Jumio/mobile-sdk-ios/master/Carthage/JumioNFC.json" == 4.18.0

```

Update you Carthage dependencies via Terminal:

```

carthage update --use-xcframeworks

```

### Manually

Download our frameworks manually via [ios-jumio-mobile-sdk-4.18.0.zip](https://repo.mobile.jumio.ai/com/jumio/ios/jumio-mobile-sdk/4.18.0/ios-jumio-mobile-sdk-4.18.0.zip).

:::note
Our sample project on GitHub contains the sample implementation without our frameworks. The project file contains a “Run Script Phase” which downloads our frameworks automatically during build time.
:::

The Jumio Mobile SDK consists of several dynamic frameworks. Depending on which product you use, you'll have to add the right frameworks to your project.

Please see [Strip unused frameworks](integration_faq.md#strip-unused-frameworks) for more information.

Add the following linker flags to your Xcode Build Settings:  
:::note
Added automatically if using CocoaPods.
:::

- "-lc++"
- "-ObjC" (recommended) or -all_load

Make sure that the following Xcode build settings in your app are set accordingly:

| Setting                       | Value |
| :---------------------------- | :---: |
| Link Frameworks Automatically |  YES  |

### SDK Version Check

Use [`Jumio.SDK.version`][sdkVersion] to check which SDK version is being used.

### Device & App Integrity
We strongly suggest to run the SDK only on uncompromised devices and in untampered apps. We advise the following checks and settings to further hinder attackers from modifying the SDKs behaviour. 

#### Jailbreak Detection
For security reasons, applications implementing the SDK should not run on jailbroken devices. We strongly advise to add a self-devised check to prevent users from running the SDK on jailbroken devices. We provide the below method [`isJailbroken`][isJailbroken] as a fallback mechanism.
```
Jumio.SDK.isJailbroken
```

⚠️&nbsp;&nbsp;__Note:__ Please be aware that this jailbreak check uses various lightweight mechanisms for detection and doesn't guarantee to detect 100% of all jailbroken devices.

#### Build Settings
For security reasons, you should set the following build settings:
Activate the Enhanced Security capability and check "Enable Additional Runtime Platform Restrictions" and "Enable-Read-only Platform Memory" to leverage the platform's advanced hardening features.
To generate a position independent executable, the build settings "Generate Position-Dependent Executable" and "Generate Position-Dependent Code" should both be set to "No".
For Objective-C projects, you should enable stack canaries by adding "-fstack-protector-all" to "Other C Flags".
For Objective-C projects, you should set "Objective-C Automatic Reference Counting" to "Yes".

#### App Attest
Use App Attest to check whether an attacker modified the binary of your application before installing it. We suggest to sign API token requests with App Attest and to return tokens only to legitimate applications.

#### Deny Debugger Usage
We recommend to deny debugging of publicly released apps. We published a [Guide](https://medium.com/jumio/the-invisible-shield-implementing-low-level-anti-debugging-in-ios-1a70a905c318), which provides detailed instructions on how to prevent attackers from debugging your app.

### NFC Setup

To make our SDK capable of reading NFC chips you will need to set the following settings:

Add the Near Field Communication Tag Reading capability to your project, App ID and provisioning profiles in [Apple Developer portal](https://developer.apple.com).
Add `NFCReaderUsageDescription` to your **info.plist** file with a proper description of why you are using this feature. You will also need to add the following key and value to your plist file to be able to read NFC chips from passports and identity cards:

```

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
</array>

```

### Digital Identity Setup

Over the course of Digital Identity verification with 'ID by Mastercard' the SDK will launch an according third party application representing your Digital Identity.
Communication between both applications (your integrating application and the Digital Identity application) is done via a so-called "deep link".

#### Deep link setup

To enable your app specific deep link, our support team has to setup an according scheme of your choice for you. This scheme will be used by the SDK to identify your application while returning from the Digital Identity provider's application. For the scheme basically any string can be used, however it is recommended that it is unique to your application in some way.

Following snippet shows how the deep link needs to be setup in your application's `AppDelegate.swift` file:

```swift
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any]) -> Bool{
    guard Jumio.SDK.handleDeeplinkURL(url) else {
        return false
    }
    return true
}
```

#### Other Digital Identity providers

Other Digital Identity providers, like 'Brazil CNH-e PDF' or 'eIDAS', stay within the app. Follow [Jumio ID Credential](#jumio-id-credential) and implement the [Scan Steps](#scan-steps) needed for the [`Jumio.Scan.Mode`][jumioScanMode] `digital`.

### Risk Signal: Device Risk

If you want to include risk signals into your application, please check our [Risk Signal guide](https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRisk).

#### Iovation setup

To integrate the device risk vendor Iovation into your application, please follow the [Iovation integration guide](https://github.com/iovation/deviceprint-SDK-iOS).

#### API call

To provide Jumio with the generated Device Risk blackbox, please follow the [Device Risk API guide](https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRiskwithMobileSDK).

---

## ML Models

By default, required models get downloaded by the SDK if not provided via the bundle or preloaded.

### Bundling models in the app

You can download our encrypted models and add them to your bundle for the following frameworks.

⚠️&nbsp;&nbsp;**Note:** Make sure not to alter the downloaded models (name or content) before adding them to your bundle.

#### ID Verification

You can find the models required for the [`Jumio.Scan.Mode`][jumioScanMode] `docFinder` [here](https://cdn.mobile.jumio.ai/ios/model/mobile-classifier-model-1.0.0.enc) and [here](https://cdn.mobile.jumio.ai/ios/model/docfinderModel_121923.enc).

#### Liveness

If you are using JumioLiveness.xcframework, find the required models [here](https://cdn.mobile.jumio.ai/ios/model/liveness_sdk_assets_v_1_1_5.enc).

### Preloading models

In version `4.9.0` we introduced the [`Jumio.Preloader`][jumioPreloader]jumioPreloader. It provides functionality to preload models without the JumioSDK being initialized. To do so call:

```swift
Jumio.Preloader.shared.preloadIfNeeded()
```

The [`Jumio.Preloader`][jumioPreloader] will identify which models are required based on your configuration.

Preloaded models are cached so they will not be downloaded again. To clean the models call:

```swift
Jumio.Preloader.clean()
```

⚠️&nbsp;&nbsp;**Note:** `clean` should never be called while the SDK is running.

To get notified that preloading has finished, you can implement the [`Jumio.Preloader.Delegate`][jumioPreloaderDelegate] methods and set the delegate as follows:

```swift
Jumio.Preloader.shared.delegate = {your delegate}
```

---

## Initialization

Your OAuth2 credentials are constructed using your previous API token as the Client ID and your previous API secret as the Client secret. You can view and manage your Client ID and secret in the Jumio Portal under:

- **Settings > API credentials > OAuth2 Clients**

Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation. Send a workflow request using the acquired OAuth2 access token to receive the SDK token necessary to initialize the Jumio SDK. For more details, please refer to [Authentication and Encryption](../README_iOS.md#authentication-and-encryption).

```
sdk = Jumio.SDK()
sdk.token = "YOUR_SDK_TOKEN"
sdk.dataCenter = jumioDataCenter
```

Make sure that your SDK token is correct. If it isn't, an exception will be thrown. Then provide a reference to identify the scans in your reports (max. 100 characters or `null`). Data center is set to `JumioDataCenter.US` by default. If your customer account is in the EU data center, use `JumioDataCenter.EU` instead. Alternatively, use `JumioDataCenter.SG` for Singapore.

⚠️&nbsp;&nbsp;**Note:** We strongly recommend storing all credentials outside of your app! We suggest loading them during runtime from your server-side implementation.

Make sure initialization and presentation are timely within one minute. On iPads, the presentation style `UIModalPresentationFormSheet` is default and mandatory.

```
self.present(jumioViewController, animated: true, completion: nil)
```

## Configuration

Every Jumio SDK instance is initialized using a specific [`sdk.token`][token]. This token contains information about the workflow, credentials, transaction identifiers and other parameters. Configuration of this token allows you to provide your own internal tracking information for the user and their transaction, specify what user information is captured and by which method, as well as preset options to enhance the user journey. Values configured within the [`sdk.token`][token] during your API request will override any corresponding settings configured in the Jumio Portal.

### Session Initialization Best Practices

- Generate SDK tokens just-in-time before SDK launch.
- Implement backend-controlled retry logic.
- Use reportingCriteria and Customer Internal Reference for tracking.
- Ensure runtime permissions are granted before launch.

### Workflow Selection

Use ID verification callback to receive a verification status and verified data positions (see [Callback section](https://documentation.jumio.ai/docs/developer-resources/callback)). Make sure that your customer account is enabled to use this feature. A callback URL can be specified for individual transactions (for URL constraints see chapter **Jumio Callback IP Addresses**). This setting overrides any callback URL you have set in the Jumio Portal. Your callback URL must not contain sensitive data like PII (Personally Identifiable Information) or account login. Set your callback URL using the `callbackUrl` parameter.

Use the correct [workflow definition key](https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/standardServices) in order to request a specific workflow. Set your key using the `workflowDefinition.key` parameter.

```
'{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": X,
  },
  "callbackUrl": "YOUR_CALLBACK_URL"
}'
```

For more details, please refer to our [Workflow Description Guide](https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/standardServices).

### Transaction Identifiers

There are several options in order to uniquely identify specific transactions. `customerInternalReference` allows you to specify your own unique identifier for a certain scan (max. 100 characters). Use `reportingCriteria`, to identify the scan in your reports (max. 100 characters). You can also set a unique identifier for each user using `userReference` (max. 100 characters).

For more details, please refer to **Request Body** section in our [KYX Guide](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).

```
'{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": X,
  },
  "reportingCriteria": "YOUR_REPORTING_CRITERIA",
  "userReference": "YOUR_USER_REFERENCE"
}'
```

⚠️&nbsp;&nbsp;**Note:** Transaction identifiers must not contain sensitive data like PII (Personally Identifiable Information) or account login.

### Preselection

You can specify issuing country using [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country codes, as well as ID types to skip selection during the scanning process. In the example down below, Austria ("AUT") and the USA ("USA") have been preselected. PASSPORT and DRIVER_LICENSE have been chosen as preselected document types. If all parameters are preselected and valid and there is only one given combination (one country and one document type), the document selection screen in the SDK can be skipped entirely.

For more details, please refer to **Request Body** section in our [KYX Guide](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).

```
'{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": X,
    "credentials": [
      {
        "category": "ID",
        "type": {
          "values": ["DRIVING_LICENSE", "PASSPORT"]
        },
        "country": {
          "values": ["AUT", "USA"]
        }
      }
    ]
  }
}'
```

Digital Identity documents can also be preselected by specifying `"DIGITAL_IDENTITY"` as the type. To narrow down to a specific digital identity subtype, use the optional `"subType"` field with a single value. Supported subtypes are: `EIDAS`, `DIGITAL_DRIVING_LICENSE_PDF`. If only one digital identity type is available for the preselected country (and no physical documents), the document selection screen in the SDK can be skipped entirely.

```json
{
  "customerInternalReference": "CUSTOMER_REFERENCE",
  "workflowDefinition": {
    "key": X,
    "credentials": [
      {
        "category": "ID",
        "type": {
          "values": [
            "DIGITAL_IDENTITY"
          ]
        },
        "subType": {
          "values": [
            "EIDAS"
          ]
        },
        "country": {
          "values": [
            "AUT"
          ]
        }
      }
    ]
  }
}
```

### Camera Handling

Use [`cameraFacing`][cameraFacing] attribute of [`Jumio.Scan.View`][jumioScanView] to configure the default camera and set it to `front` or `back`.

```
scanView.cameraFacing = .front
```

Use boolean [`hasFlash`][hasFlash] of [`Jumio.Scan.View`][jumioScanView] to see if flash is available for the current device camera. Use boolean [`flash`][flash] to toggle the camera flash.

## SDK Workflow

Implement the delegate methods of the [`DefaultUIDelegate`][defaultUIDelegate] protocol to be notified of successful initialization, successful scans, and errors. Dismiss the [`Jumio.ViewController`][jumioViewController] instance in your app in case of success or error.

### Initialization

When this method is fired, the SDK has finished initialization and loading tasks, and is ready to use. The error object is only set when an error has occurred (e.g. wrong credentials are set or a network error occurred).

```
sdk.startDefaultUI()
```

### Success

Upon success, the extracted document data is returned within a [`Jumio.Result`][jumioResult] object that includes `workflowExecutionId` and `accountId`. The parameter [`isSuccess`][isSuccess] will be `true`.

```
func jumio(sdk: Jumio.SDK, finished result: Jumio.Result) {
        delegate?.defaultUIDidFinish(with: result)
}
```

### Error

A workflow will result in an error when the user presses the cancel button during the workflow or in an error situation. [`Jumio.Result`][jumioResult] returns `workflowExecutionId` and `accountId`. It will also return a [`Jumio.Error`][jumioError] object, which contains an error code and error message. The parameter [`isSuccess`][isSuccess] will be `false`.

```
func jumio(sdk: Jumio.SDK, finished result: Jumio.Result) {
        delegate?.defaultUIDidFinish(with: result)
}
```

### Retrieving information

The following tables give information on the specification of all data parameters and errors:

- [`Jumio.IDResult`][jumioIDResult]
- [`Jumio.FaceResult`][jumioFaceResult]
- [`Jumio.RejectReason`][jumioRejectReason]
- [`Jumio.Error`][jumioError]

#### Class **_Jumio.IDResult_**

| Parameter        | Type            | Max. length | Description                                                                                                                                                            |
| :--------------- | :-------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| issuingCountry   | String          | 3           | Country of issue as [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code                                                                |
| idType           | String          |             | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA as provided or selected                                                                                                |
| idSubType        | String          |             | Sub type of the scanned ID                                                                                                                                             |
| firstName        | String          | 100         | First name of the customer                                                                                                                                             |
| lastName         | String          | 100         | Last name of the customer                                                                                                                                              |
| dateOfBirth      | String          |             | Date of birth                                                                                                                                                          |
| issuingDate      | String          |             | Date of issue                                                                                                                                                          |
| expiryDate       | String          |             | Date of expiry                                                                                                                                                         |
| documentNumber   | String          | 100         | Identification number of the document                                                                                                                                  |
| personalNumber   | String          |             | Personal number of the document                                                                                                                                        |
| curp             | String          |             | Unique Population Registry Code                                                                                                                                        |
| gender           | String          |             | Gender M, F or X                                                                                                                                                       |
| nationality      | String          |             | Nationality of the customer                                                                                                                                            |
| placeOfBirth     | String          | 255         | Place of birth                                                                                                                                                         |
| country          | String          |             | Country of residence                                                                                                                                                   |
| address          | String          | 64          | Street name of residence                                                                                                                                               |
| city             | String          | 64          | City of residence                                                                                                                                                      |
| subdivision      | String          | 3           | Last three characters of [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) or [ISO 3166-2:CA](https://en.wikipedia.org/wiki/ISO_3166-2:CA) subdivision code |
| postalCode       | String          | 15          | Postal code of residence                                                                                                                                               |
| mrzLine1         | String          | 50          | MRZ line 1                                                                                                                                                             |
| mrzLine2         | String          | 50          | MRZ line 2                                                                                                                                                             |
| mrzLine3         | String          | 50          | MRZ line 3                                                                                                                                                             |
| extractionMethod | Jumio.Scan.Mode |             | Extraction method used during scanning (manual, barcode, nfc, docFinder)                                                                                               |
| imageData        | Jumio.ImageData |             | Wrapper class for accessing image data of all credential parts from an ID verification session. This feature has to be enabled by your account manager.                |

#### Class **_Jumio.FaceResult_**

| Parameter        | Type            | Max. length | Description                                                                                                                                             |
| :--------------- | :-------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| passed           | Boolean         |             |
| extractionMethod | Jumio.Scan.Mode |             | Extraction method used during scanning (faceManual, liveness, livenessPremium)                                                                          |
| imageData        | Jumio.ImageData |             | Wrapper class for accessing image data of all credential parts from an ID verification session. This feature has to be enabled by your account manager. |

#### Class **_Jumio.RejectReason_**

List of all possible reject reasons returned if Instant Feedback is used. The actually returned reasons depend on the server-side configuration of your merchant:

| Code | Message              | Description                                                 |
| :--- | :------------------- | :---------------------------------------------------------- |
| 104  | DIGITAL_COPY         | Document appears to be a digital copy                       |
| 200  | NOT_READABLE         | Document is not readable                                    |
| 201  | NO_DOC               | No document could be detected                               |
| 206  | MISSING_BACK         | Backside of the document is missing                         |
| 214  | MISSING_FRONT        | Frontside of the document is missing                        |
| 401  | UNSUPPORTED_DOCUMENT | Frontside or backside of document is unsupported            |
| 501  | INVALID_CERTIFICATE  | Document has no valid certificate, relevant for digital ids |
| 2001 | BLURRY               | Document image is unusable because it is blurry             |
| 2003 | MISSING_PART_DOC     | Part of the document is missing                             |
| 2005 | DAMAGED_DOCUMENT     | Document appears to be damaged                              |
| 2004 | HIDDEN_PART_DOC      | Part of the document is hidden                              |
| 2006 | GLARE                | Document image is unusable because of glare                 |

#### Error Codes

List of all **_error codes_** that are available via the `code` and `message` property of the [`Jumio.Error`][jumioError] object. The first letter (A-Z) represents the error case. The remaining characters are represented by numbers that contain information helping us understand the problem situation ([xx][yyyy]).

|    Code     | Message                                                            | Description                                                   |
| :---------: | :----------------------------------------------------------------- | :------------------------------------------------------------ |
| A[xx][yyyy] | We have encountered a network communication problem                | Retry possible, user decided to cancel                        |
| B[xx][yyyy] | Authentication failed                                              | Secure connection could not be established, retry impossible  |
|  C[xx]0401  | Authentication failed                                              | API credentials invalid, retry impossible                     |
|  E[xx]0000  | No Internet connection available                                   | Retry possible, user decided to cancel                        |
|   F000000   | Scanning not available at this time, please contact the app vendor | Resources cannot be loaded, retry impossible                  |
|   G000000   | Cancelled by end-user                                              | No error occurred                                             |
|   H000000   | The camera is currently not available                              | Camera cannot be initialized, retry impossible                |
|   I000000   | Certificate not valid anymore. Please update your application      | End-to-end encryption key not valid anymore, retry impossible |
|   J000000   | Transaction already finished                                       | User did not complete SDK journey within session lifetime     |
|   N000000   | Scanning not available at this time, please contact the app vendor | Required images are missing to finalize the acquisition       |

⚠️&nbsp;&nbsp;**Note:** Please always include the whole error code when filing an error related issue to our support team.

## Default UI

You can use Jumio SDK with the default theme or specify a custom theme (see [Customization](#customization) for details). Please note that the Jumio SDK launches in portrait mode only.
You can start DefaultUI by calling `startDefaultUI` method on `Jumio.SDK` instance.
Please make sure to include the dependency `Jumio/DefaultUI`.

## Custom UI

ID Verification can also be implemented as a **custom scan view.** This means that only the scan view controllers (including the scan overlays) are provided by the SDK.
The handling of the lifecycle, document selection, readability confirmation, error handling, and all other steps necessary to complete a scan have to be handled by the client application that implements the SDK.

The following sequence diagram outlines components, callbacks and functions for a basic ID Verification workflow:

![Custom UI Happy Path Diagram](images/happy_paths/custom_ui_happy_path_diagram.png)

Custom UI enables you to create and use a custom scan view with a plain scanning user interface. In order to do that, initialize the SDK instance by setting [`sdk.token`][token] and [`sdk.dataCenter`][dataCenter]. Specify a `delegate` instance which creates a [`Jumio.Controller`][jumioController].

:::note
Instead of setting a `defaultUIDelegate` property, like you would do for DefaultUI, you need to pass a [`Jumio.Controller.Delegate`][jumioControllerDelegate] to the `start` function.
:::

```
sdk = Jumio.SDK()
sdk?.token = "YOUR_SDK_TOKEN"
sdk?.dataCenter = jumioDataCenter
```

- [`JumioDataCenter`][dataCenter] values: `US`, `EU`, `SG`

Create a [`Jumio.Controller`][jumioController] instance and start the SDK:

```
var controller = Jumio.Controller?
controller = sdk?.start(controllerDelegate)
```

### UI/UX Best Practices

- Launch SDK only after explicit user consent.
- Show pre-permission screens explaining camera use.
- Prompt better lighting for retries.
- Avoid flashlight use by default.
- Use SDK localization.

### Controller Handling

Once the controller is initialized, the following delegate methods will be available to handle [`Jumio.Controller`][jumioController]:

```
// initialization finished
func jumio(controller: Jumio.Controller, didInitializeWith credentialInformations: [Jumio.Credential.Info], consentItems: [Jumio.ConsentItem]?, termsOfUse: Jumio.TermsOfUse?)

// result handling
func jumio(controller: Jumio.Controller, finished result: Jumio.Result)
func jumio(controller: Jumio.Controller, error: Jumio.Error)
func jumio(controller: Jumio.Controller, logicalError: Jumio.LogicalError)
```

#### Consent Handling

To support compliance with various data protection laws, if a user's consent is required the parameter `consentItems` will provide a list of `Jumio.ConsentItem`. Each consent item contains a text, a consent type and an URL that will redirect the user to Jumio's consent details. Each `Jumio.ConsentItem` also provides an attributedText where the text is parsed and link holder is underlined.

If no consent is required, the parameter `consentItems` will be `null`.

Each consent item can be one of two types:

- `Jumio.ConsentType.active`
- `Jumio.ConsentType.passive`

For `active` types, the user needs to accept the consent items explicitly, e.g. by enabling an UISwitch or checking a checkbox for each consent item. For `passive` types, it is enough to present the consent text and URL to the user. The user implicitly accepts the passive consent items by continuing with the journey.

The user can open and continue to the provided consent link if they choose to do so. If the user consents to the Jumio policy, [`controllerHandling?.userConsented(consentItem: Jumio.ConsentItem, decision: Bool)`][userConsented] is required to be called internally before any credential can be initialized and the user journey can continue. If no consent is required, the list of `consentItems` will be `null`. If the user does not consent or if [`controllerHandling?.userConsented(consentItem: Jumio.ConsentItem, decision: Bool)`][userConsented] is not called for all the items inside the`consentItems` list, the user will not be able to continue the user journey.

**_Please note that biometric data protection laws and other laws governing consent can change over time and therefore you must include user consent handling as described above, even if a record of the user’s consent is not required for your current use case._**

⚠️&nbsp;&nbsp;**Note:** Please be aware that in cases where list of `consentItems` is not null, the user **must consent** to Jumio's processing of personal information, including biometric data, and be provided a link to Jumio's Privacy Notice. Do not accept automatically without showing the user any terms.

#### Terms of Use Handling

The `termsOfUse` parameter provides a [`Jumio.TermsOfUse`][jumioTermsOfUse] containing:
- `text`: The localized string containing the terms of use text.
- `url`: The URL to redirect the user to Jumio’s terms of use details.

If the `termsOfUse` parameter is `null`, then it should be ignored.

### Credential Handling

The [`Jumio.Credential`][jumioCredential] object contains all necessary information about the scanning process. You will receive a specific subclass depending on the verification type, such as an [`IDCredential`][jumioIDCredential] for ID Verification or a [`FaceCredential`][jumioFaceCredential] for Selfie Verification.

Initialize the credential and check if it is already preconfigured. If the [`isConfigured`][isConfigured] parameter is true, the credential can be started right away. If you are using digital identities and do not want the user to select a specific document type for physical document scanning, call [`setDefaultDocumentConfiguration()`][setDefaultDocumentConfiguration] on the IDCredential. This allows the user to skip country selection and proceed directly to document scanning.


```
var currentCredential: Jumio.Credential?
currentCredential = controller?.start(credentialInfo: currentCredentialInfo)

if currentCredential?.isConfigured {
   scanSides = currentCredential?.scanSides
   // start next scan part
}
```

If the credential is not yet configured, configuration needs to be set before scanning can be initialized for available countries. In case of ID verification, all available countries for a specific [`IDCredential`][jumioIDCredential] are returned in [`countries`][countries] parameter of the individual credential. Use [`isSupportedConfiguration()`][isSupportedConfiguration] function to check if a certain configuration (e.g. a specific combination of country and documents) is supported for a certain ID credential. Use [`setConfiguration()`][setConfiguration] to set a valid country / document combination:

```
currentCredential.isSupportedConfiguration(country: country, document: document) else { return }
currentCredential.setConfiguration(country: country, document: document)
```

Make sure to initialize credentials in the order defined in the [`Jumio.Credential.Info.order`][jumioCredentialInfoOrder]. If multiple credentials have the same order, you can initialize them in any order.

#### Jumio ID Credential

To use the document found in `Jumio.LookupResult` for the Selfie.Done workflow, a consent value `true` is mandatory. If the user does not want to use the document, an explicit `false` (non-consent) must still be recorded before the process can proceed:

```
let idCredential = ...
// The legalStatment is retrieved from the `Jumio.LookupResult.LegalStatement`
idCredential.userConsented(to: legalStatement, decision: true)
```

In case of [`Jumio.IDCredential`][jumioIDCredential], you can retrieve all available countries from [`supportedCountries`][supportedCountries]. After selecting a specific country from that list, you can query available documents for that country by either calling `physicalDocuments(for:)` or `digitalDocuments(for:)`. To configure the [`Jumio.IDCredential`][jumioIDCredential], pass your desired document as well as the country to `setConfiguration()`:

Retrieve the supported countries:

```
let idCredential = ...
let supportedCountries = idCredential.supportedCountries
```

Retrieve the Physical documents for a country:

```
let idCredential = ...
let physicalDocuments = idCredential.physicalDocuments(for: countryCode)
```

Retrieve the Digital documents for a country:

```
let idCredential = ...
let digitalDocuments = idCredential.digitalDocuments(for: countryCode)
```

Set a valid country / document combination:

```
let idCredential = ...
idCredential.setConfiguration(country: country, document: document)
```

Retrieve the first credential part of the credential to start the scanning process by calling:

```
var credentialParts: [Jumio.Credential.Part]?
credentialParts = currentCredential?.parts
```

Check if current [`Credential.Part`][jumioCredentialPart] is the first one:

```
var index = credentialParts?.firstIndex { $0 == previousCredentialPart } ?? 0
index += previousCredentialPart != nil ? 1 : 0
guard credentialParts?.count ?? 0 > index,
              let credentialPart = credentialParts?[index] else { return }
```

- [`Jumio.Credential.Category`][credentialCategory] values: `id`, `face`, `document`

- [`Jumio.Document`][jumioDocument] values: `Jumio.Document.Physical`, `Jumio.Document.Digital`

- [`Jumio.Document.Physical`][jumioPhysicalDocument] represents a single JumioDocumentType and JumioDocumentVariant combination

  - [`Jumio.Document.Physical.DocumentType`][jumioDocumentType] values: `passport`, `visa`, `drivingLicense`, `identityCard`

  - [`Jumio.Document.Physical.DocumentVariant`][jumioDocumentVariant] values: `paper`, `plastic`

- [`Jumio.Document.Digital`][jumioDigitalDocument] represents a digital document ("Digital Identity")

  - [`JumioDigitalDocumentType`][jumiodigitaldocumenttype] values: `TRUST_CHECK`, `EIDAS`, `MASTERCARD`, `DIGITAL_DRIVING_LICENSE_PDF`

#### Jumio Face Credential

In case of [`Jumio.FaceCredential`][jumioFaceCredential], Jumio uses Certified Liveness technology to determine liveness. The mode can be detected by checking the [`Jumio.Scan.Mode`][jumioScanMode] of the [`Jumio.Scan.Part`][jumioScanPart]. Make sure to also implement `faceManual` as a fallback, in case `liveness` is not available.

Retrieve the credential part of the credential to start the scanning process by calling:

```
var credentialPart = [Jumio.Credential.Part]?
var scanPart = credential?.initScanPart(credentialPart, scanPartDelegate: self)
```

:::note
Portrait orientation is required when performing the face credential.
:::

#### Jumio Document Credential

In case of [`Jumio.DocumentCredential`][jumioDocumentCredential], there is the option to either acquire the image using the camera or selecting a file from the device. Call `setConfiguration` with a [`Jumio.Acquire.Mode`][jumioAcquireMode] to select the preferred mode as described in the code documentation.

- [`Jumio.Acquire.Mode`][jumioAcquireMode] values: `camera`, `file`

```
func select(acquireMode: Jumio.Acquire.Mode?) {
        guard let documentCredential = credential as? Jumio.DocumentCredential,
              let acquireMode = acquireMode,
              documentCredential.isSupportedConfiguration(acquireMode: acquireMode) else {
            delegate?.configurationNotSupported()
            return
        }
        documentCredential.setConfiguration(acquireMode: acquireMode)
        delegate?.loaded(scanSides: createViewModels(from: documentCredential.parts))
    }
```

Retrieve the credential part of the credential to start the scanning process by calling:

```
func initScanPart(with credentialPart: Jumio.Credential.Part) {
        guard let scanPart = createScanPart(credentialPart: credentialPart) else { return }
        activeCredentialPart = credentialPart
        self.scanPart = scanPart
        isScanPartFinishable = false
}

```

If [`Jumio.Acquire.Mode`][jumioAcquireMode] `file` is used, the [`JumioFileAttacher`][jumioFileAttacher] needs to be utilized to add a File or FileDescriptor for the selected [`Jumio.Scan.Part`][jumioScanPart].

```
let attacher = Jumio.FileAttacher()
attacher.attach(scanPart: scanPart)
attacher.set(url: "path/to/your/file")

```
Check the [`Jumio.FileRequirements`][jumioFileRequirements] to know the specifications of the file. Currently, the SDK supports `application/pdf`, `image/webp`, `image/jpeg`, `image/png` and `image/heic`.

### ScanPart Handling

The following sequence diagram outlines an overview of ScanPart handling details:
![ScanPart Happy Path Diagram](images/happy_paths/scanpart_happy_path_diagram.png)

Start the scanning process by initializing the scan part. Provide a `Jumio.Credential.Part` from the list below:

- [`Jumio.Credential.Part`][jumioCredentialPart] values: `front`, `back`, `face`, `nfc`, `document`, `multipart`, `digital`

Each [`Jumio.Scan.Part`][jumioScanPart] has an associated `scanMode`. Depending on the scan mode, you need to provide a different user guidance. The following scan modes are available for the different `Jumio.Credential.Part`s:

- [`Jumio.Scan.Mode`][jumioScanMode] values:
  - `front`, `back`, `multipart`: `manual`, `barcode`, `docFinder`
  - `digital`: `web`, `file`
  - `nfc`: `nfc`
  - `face`: `faceManual`, `liveness`, `livenessPremium`
  - `document`: `manual`, `file`

During the scanning process, use the `scanPart` delegate method to check on the scanning progress.

#### Scan Steps

A [`Jumio.Scan.Step`][jumioScanStep] is sent via `jumio(scanPart: Jumio.Scan.Part, step: Jumio.Scan.Step, data: Any?)` and covers lifecycle events which require action from the customer to continue the process.

- [`Jumio.Scan.Step`][jumioScanStep] values: `prepare`, `started`, `scanView`, `digitalIdentityView`, `thirdPartyVerification`, `attachFile`, `imageTaken`, `processing`, `nextPart`, `confirmationView`, `retry`, `rejectView`, `canFinish`, `addonScanPart`.

[`prepare`][prepare] is only sent if a scan part requires upfront preparation and the customer should be notified (e.g. by displaying a loading screen).

[`started`][started] is always sent when a scan part is started. If a loading view was triggered before, it can now be dismissed. It additionally returns the started [`Jumio.Credential.Part`][jumioCredentialPart] as data object.

[`scanView`][scanView] is sent, when the scan view should be displayed. On this view, the user will capture a photo or a sequence of photos of a document or of a face with the camera.

[`digitalIdentityView`][digitalIdentityView] is only sent if a scan part is digital and is triggered to indicate that the scan part needs a `Jumio.DigitalIdentity.View` attached.

[`thirdPartyVerification`][thirdPartyVerification] is triggered to indicate that the scan part will switch to a third party's application to continue verification. As this might take some time, showing a loading indicator is recommended.

[`attachFile`][attachFile] is sent, when the user needs to select and upload a file. For this, you should create a [`JumioFileAttacher`][jumioFileAttacher] and provide the document. The step is only sent, when the scan method is `file`.

[`imageTaken`][imageTaken] is triggered as soon as all images of one part are taken. There can't be more than one [`imageTaken`][imageTaken] step during one part. Instead, [`Jumio.Scan.Update.nextPosition`][nextPosition] events are sent, when multiple images are taken.

[`Jumio.Scan.Step.processing`][processing] is triggered when background processing happens. The camera preview is stopped during that step.

When a [`multipart`][multipart] scan part is started, an additional [`nextPart`][nextPart] step is sent after all images from the current part are taken. This signals that another side of the document should be scanned now. The step returns the [`Jumio.Credential.Part`][jumioCredentialPart], which should be scanned next, as data object. We suggest to actively guide the user to move to the next part, e.g. by showing an animation and by disabling the extraction during the animation.

When a confirmation view should be displayed, depending on the outcome either [`Jumio.Scan.Step.confirmationView`][confirmationView] or [`Jumio.Scan.Step.rejectView`][rejectView] is triggered. To display the ScanPart in the confirmation or reject view, instantiate a [`Jumio.Confirmation.Handler`][jumioConfirmationHandler] or [`Jumio.Reject.Handler`][jumioRejectHandler], and simply attach the ScanPart to the handler and render the views once the steps are triggered:

```
func jumio(scanPart: Jumio.Scan.Part, step: Jumio.Scan.Step, data: Any?) {
  switch step {
  case .confirmationView:
    if let scanPart = self.scanPart {
      confirmationHandler?.attach(scanPart: scanPart)
      delegate?.showConfirmationViews()
    }
  case .rejectView:
    // Use the rejectReasons to show the user why the scan was rejected
    let rejectReasons = data as? [Jumio.Credential.Part: Jumio.RejectReason] ?? [:]

    if let scanPart = self.scanPart {
      rejectHandler?.attach(scanPart: scanPart)
      delegate?.showRejectViews()
    }
  }
}

func showRejectViews() {
    rejectHandler?.parts.forEach { part in
        let rejectView = Jumio.Reject.View()
        rejectHandler?.render(part: part, view: rejectView)
        delegate?.display(rejectView)
    }
}
```

The scan part can be confirmed by calling `confirmationHandler?.confirm()` or the scan can be taken again: Either by calling `confirmationHandler?.retake()` in case the scan attempt was successful, or by calling `rejectHandler?.retake()` in case the scan attempt was rejected. (Bad lighting conditions or glare, image was blurry, etc. ...)

The retry scan step returns a data object of type [`Jumio.Retry.Reason`][jumioRetryReason]. On [`retry`][retry], a retry has to be triggered on the credential.

```
func jumio(scanPart: Jumio.Scan.Part, step: Jumio.Scan.Step, data: Any?) {
  case .retry:
    activeRetryReason = data as? Jumio.Retry.Reason
    var code = activeRetryReason?.code
    var message = activeRetryReason?.message
}
```

As soon as the scan part has been confirmed and all processing has been completed [`canFinish`][canFinish] is triggered. `scanPart.finish()` can now be called. During the finish routine the SDK checks if there is an add-on functionality for this part available, e.g. possible NFC scanning after a DocFinder scan part. If an add-on is available, the `addonScanPart` step is triggered.

To see if the finished credential part was the last one of the credential, check `currentCredentialPart == currentCredential?.credentialPart?.last()` Check if the credential is complete by calling [`currentCredential?.isComplete`][isComplete] and finish the current credential by calling [`currentCredential?.finish()`][credentialFinish].

Continue that procedure until all necessary credentials (e.g. `id`, `face`, `document`, `data`) are finished. Check if the last credential is finished with:

```
var index = credentialParts?.firstIndex { $0 == previousCredentialPart } ?? 0
index += previousCredentialPart != nil ? 1 : 0
guard credentialParts?.count ?? 0 > index,
              let credentialPart = credentialParts?[index] else { return }
```

Then call [`controller?.finish()`][controllerFinish] to end the user journey.

#### Scan Updates

[`Jumio.Scan.Update`][jumioScanUpdate]s are sent via `jumio(scanPart: Jumio.Scan.Part, updates update: Jumio.Scan.Update, data: Any?)` and cover scan information that is relevant and might need to be displayed during the scanning process.

- [`Jumio.Scan.Update`][jumioScanUpdate] values: `fallback(FallbackReason)`, `nfcExtractionStarted`, `nfcExtractionProgress`, `nfcExtractionFinished`, `extractionState(ExtractionState)`, `flash(FlashState)`, `nextPosition`, `cameraAvailable`

  - In case of a `fallback`, the `scanMode` changed and you should adapt the user interface to reflect the new scan mode. For example, if you fallback to a manual scan method, you might want to show a shutter button.
  - `nfcExtractionStarted`, `nfcExtractionProgress`, and `nfcExtractionFinished` make it possible to track the progress of a NFC scan. `nfcExtractionProgress` additionally delivers an integer in the data parameter in the range of 0-100 to signal the progress in the current data group.
  - `extractionState`s signal a desired user behaviour.
  - `flash` signals the enabling or disabling of the camera flash.
  - `nextPosition` signals that the user needs to take a second image, e.g., needs to move the face in a liveness scan.
  - `cameraAvailable` signals that the camera loaded successfully. Note that `cameraAvailable` is also called when the camera facing was successfully changed.

* [`Jumio.Scan.Update.FallbackReason`][jumioFallbackReason] values: `userAction`, `lowPerformance`

  - `userAction` is sent after `scanPart.fallback()` was called.
  - `lowPerformance` is sent, when the device is not capable of running the current `scanMode`.

* [`Jumio.Scan.Update.ExtractionState`][jumioExtractionState]:

  - We send the following extraction states for the scan mode `docFinder`: `centerId`, `tooClose`, `moveCloser`, `holdStraight`, `tilt`, `imageAnalysis`, `rotate`
  - Please note - fallback and camera switch will also not be available during the states `FLASH` and `IMAGE_ANALYSIS`.

  * We send the following extraction states for the scan modes `liveness` and `livenessPremium`: `centerFace`, `faceTooClose`, `moveFaceCloser`, `moveFaceIntoFrame`, `levelEyesAndDevice`, `holdStill`, `tiltFaceUp`, `tiltFaceDown`, `tiltFaceLeft`, `tiltFaceRight`

* [`Jumio.Scan.Update.FlashState`][jumioFlashState] values: `on`, `off`

* [`Jumio.Scan.Update.TiltState`][jumioTiltState] is sent in the data parameter of `jumio(scanPart: Jumio.Scan.Part, updates: Jumio.Scan.Update, data: Any?)` for the update `extractionState(.tilt)` and returns the current tilt angle as well as the target tilt angle.
  - When a tilt update is sent, advise the user to tilt the identity document by e.g. showing an animation or an overlay.

### Result and Error Handling

The method `jumio(controller: Jumio.Controller, finished result: Jumio.Result)` has to be implemented to handle data after a successful scan, which will return [`Jumio.Result`][jumioResult].

```
func jumio(controller: Jumio.Controller, finished result: Jumio.Result) {
        delegate?.controller(finished: result)
        // handle success case
    }
```

⚠️&nbsp;&nbsp;**Note:** We recommend to hide any sensitive data, which you display to the user, when the app goes to the background. This includes the results you receive from us.

The delegate method `jumio(controller: Jumio.Controller, error: Jumio.Error)` has to be implemented to handle data after an unsuccessful scan, which will return [`Jumio.Error`][jumioError]. Check the parameter [`error.isRetryable`][isRetryable] to see if the failed scan attempt can be retried. If an error is not retryable, the only possibility is to cancel the controller. This will result in a finished call with a [`Jumio.Result`][jumioResult] instance containing this error.

```
func jumio(controller: Jumio.Controller, error: Jumio.Error) {
    guard controller === self.controller else { return }
    guard error.isRetryable else {
        Task {
            await controller.cancel()
        }
        return
    }
    ...
    // handle error case
}
```

The delegate method `(controller: Jumio.Controller, error: Jumio.LogicalError)` has to be implemented to handle data after an unsuccessful scan. [`Jumio.LogicalError`][jumioLogicalError] case occurs whenever some kind of logical error occurs. (For example: `.deadCredential: Credential` is returned when a credential has already been finished or canceled and can’t execute any action anymore. Controller has to be finished or canceled before a new one can be initialized.

- [`Jumio.LogicalError`][jumioLogicalError] values: `dependencyWrongVersion`, `notYetImplemented`, `deadController`, `errorNotRetryable`, `needToConsentFirst`, `controllerNotCompleted`, `isBeingFinished`, `multipleCredentials`, `unknownCredential`, `deadCredential`, `credentialNotCompleted`, `multipleScanParts`, `unknownScanPart`, `scanPartNotCompleted`, `deadScanPart`, `noFallbackAvailable`, `takePictureNotAllowed`, `tokenValidationFailed`, `dataCenterValidationFailed`

```
func jumio(controller: Jumio.Controller, logicalError: Jumio.LogicalError) {
        var logicalErrorMessage: String = ""
        switch logicalError {
        case .dependencyWrongVersion:
            logicalErrorMessage = "3rd party dependency have wrong version"
        case
          ...
          // handle error cases
        @unknown default:
            logicalErrorMessage = "unknown logical error reported"
        }
        delegate?.display(logicalErrorMessage: logicalErrorMessage)
    }
```

#### Instant Feedback

The use of Instant Feedback provides immediate end user feedback by performing a usability check on any image the user took and prompting them to provide a new image immediately if this image is not usable, for example because it is too blurry. Please refer to the [JumioRejectReason table](#class-jumiorejectreason) for a list of all reject possibilities.

#### Error Handling & Retry Strategy

- Categorize errors: soft (retry allowed) vs hard (exit flow).
- On failure: create new accountId or reuse existing accountId with new session.
- Redirect to retry/support screen instead of immediate SDK relaunch.
- Log errors without storing PII.

## Customization

### Customization Tool

[Jumio Surface](https://jumio.github.io/surface-tool) is a web tool that offers the possibility to apply and visualize, in real-time, all available customization options for the Jumio SDK, as well as an export feature to import the applied changes straight into your codebase.

[![Jumio Surface](images/surface_tool.png)](https://jumio.github.io/surface-tool)

### Default UI customization

The surface tool utilizes each screen of Jumio's [Default UI](#default-ui) to visualize all items and colors that can be customized. If you are planning to use the [Default UI](#default-ui) implementation, you can specify the [`Jumio.Theme`][jumioTheme] as a parent style and overriding attributes within this theme.

After customizing the SDK via the surface tool, you can click the `Swift` button in the **Output** menu on the bottom right to copy the code from the theme [`Jumio.Theme`][jumioTheme] to your iOS app's.

You can customize Jumio SDK UI. By using [`Jumio.Theme`][jumioTheme] class you can create your own theme and set it to your Jumio instance. You can use ['our sample app'](https://github.com/Jumio/mobile-sdk-ios/blob/master/sample/SampleApp/DefaultUI+Customization.swift) as guide to create your theme.

#### Dark Mode

[`Jumio.Theme`][jumioTheme] attributes can also be customized for dark mode. For each [`Jumio.Theme.Value`][jumioThemeValue] you can initiate with either only one color or with `light and dark`. If `light and dark` colors have been specified, they will be applied to the modes respectively.
Dark mode will be applied when darkmode is enabled in system settings.

### Custom UI customization

If you implement your own UI, you can still customize how some views provided by the SDK look.
By following the steps explained in [Default UI customization](#default-ui-customization) you can see potential attributes to override.

## Testing & Validation

- Use Jumio official sample apps to validate flows.
- Test on varied device tiers and OS versions.
- Test multiple ID types and lighting conditions.

---

# Security

All SDK related traffic is sent over HTTPS using TLS and public key pinning. Additionally, the information itself within the transmission is also encrypted utilizing **Application Layer Encryption** (ALE). ALE is a Jumio custom-designed security protocol that utilizes RSA-OAEP and AES-256 to ensure that the data cannot be read or manipulated even if the traffic was captured.

## Token Management & Session Security

- Always create SDK tokens server-side.
- Auth tokens are valid for 60 Mins. Kindly reuse them.
- Pass Auth tokens securely using HTTPS only and store in-memory only.
- Never hard-code or store the token creation mechanism on devices.
- Always log accountId and workflowExecutionId.

# Support

## Licenses

The software contains third-party open source software. For more information, see [licenses](../licenses).

This software is based in part on the work of the Independent JPEG Group.

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com. The [Jumio online helpdesk](https://support.jumio.com) contains a wealth of information regarding our services including demo videos, product descriptions, FAQs, and other resources that can help to get you started with Jumio.

## Copyright

&copy; Jumio Corporation, 395 Page Mill Road, Suite 150, Palo Alto, CA 94306

The source code and software available on this website (“Software”) is provided by Jumio Corp. or its affiliated group companies (“Jumio”) "as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Jumio be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services, loss of use, data, profits, or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this Software, even if advised of the possibility of such damage.

In any case, your use of this Software is subject to the terms and conditions that apply to your contractual relationship with Jumio. As regards Jumio’s privacy practices, please see our privacy notice available here: [Privacy Policy](https://www.jumio.com/legal-information/privacy-policy/).

[token]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/SDK.html#/s:5JumioAAV3SDKC5tokenSSvp
[dataCenter]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/DataCenter.html
[sdkVersion]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/SDK.html#/s:5JumioAAV3SDKC17defaultUIDelegateAA0a7DefaultD0_pSgvp
[isJailbroken]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/SDK.html#/s:5JumioAAV3SDKC12isJailbrokenSbvpZ
[defaultUIDelegate]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/SDK.html#/s:5JumioAAV3SDKC17defaultUIDelegateAA0a7DefaultD0_pSgvp
[cameraFacing]: https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html#/s:5Jumio0A8ScanViewC12cameraFacingA2AV06CameraE0Ovp
[supportedCountries]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html#/s:5JumioAAV12IDCredentialC18supportedCountriesSaySSGvp
[hasFlash]: https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html#/s:5Jumio0A8ScanViewC8hasFlashSbvp
[flash]: https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html#/s:5Jumio0A8ScanViewC5flashSbvp
[isSuccess]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Result.html#/s:5JumioAAV6ResultC9isSuccessSbvp
[userConsented]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Controller.html#/s:5JumioAAV10ControllerC13userConsentedyyF
[isConfigured]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential.html#/s:5JumioAAV10CredentialC12isConfiguredSbvp
[setDefaultDocumentConfiguration]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html#/s:5JumioAAV12IDCredentialC31setDefaultDocumentConfigurationyyF
[countries]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html#/s:5JumioAAV12IDCredentialC9countriesSDySSSayAA0A8Document_pGGvp
[isSupportedConfiguration]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html#/s:5JumioAAV12IDCredentialC24isSupportedConfiguration7country8documentSbSS_AB8DocumentVtF
[setConfiguration]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html#/s:5JumioAAV12IDCredentialC16setConfiguration7country8documentySS_AB8DocumentVtF
[credentialCategory]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential.html#/s:5JumioAAV10CredentialC8CategoryO
[prepare]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO7prepareyA2FmF
[started]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO7startedyA2FmF
[imageTaken]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO10imageTakenyA2FmF
[processing]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO10processingyA2FmF
[digitalIdentityView]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO19digitalIdentityViewyA2FmF
[thirdPartyVerification]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO22thirdPartyVerificationyA2FmF
[attachFile]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO10attachFileyA2FmF
[scanView]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO8scanViewyA2FmF
[confirmationView]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO16confirmationViewyA2FmF
[rejectView]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO10rejectViewyA2FmF
[canFinish]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO9canFinishyA2FmF
[nextPart]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO8nextPartyA2FmF
[isComplete]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential.html#/s:5JumioAAV10CredentialC10isCompleteSbvp
[credentialFinish]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential.html#/s:5JumioAAV10CredentialC6finishyyF
[controllerFinish]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Controller.html#/s:5JumioAAV10ControllerC6finishyyF
[retry]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html#/s:5JumioAAV4ScanV4StepO5retryyA2FmF
[isRetryable]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Error.html#/s:5JumioAAV5ErrorV11isRetryableSbvp
[multipart]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential/Part.html#/s:5JumioAAV10CredentialC4PartO9multipartyA2FmF
[nextPosition]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update.html#/s:5JumioAAV4ScanV6UpdateO12nextPositionyA2FmF
[jumioScanView]: https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html
[jumioTheme]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Theme.html
[jumioThemeValue]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Theme.html#/s:5JumioAAV5ThemeV5ValueV
[jumioViewController]: https://jumio.github.io/mobile-sdk-ios/Jumio/Classes.html#/c:@M@Jumio@objc(cs)JumioViewController
[jumioResult]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Result.html
[jumioIDResult]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDResult.html
[jumioFaceResult]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/FaceResult.html
[jumioRejectReason]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/RejectReason.html
[jumioRetryReason]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Retry.html#/s:5JumioAAV5RetryV6ReasonC
[jumioError]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Error.html
[jumioSetupError]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/SetupError.html
[jumioLogicalError]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/LogicalError.html
[jumioController]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Controller.html
[jumioControllerDelegate]: https://jumio.github.io/mobile-sdk-ios/Jumio/Protocols/JumioControllerDelegate.html
[jumioCredential]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential.html
[jumioCredentialInfoOrder]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential/Info.html#/s:5JumioAAV10CredentialC4InfoV5orderSivp
[jumioIDCredential]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/IDCredential.html
[jumioPhysicalDocument]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/PhysicalDocument.html
[jumioDigitalDocument]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/DigitalDocument.html
[jumiodigitaldocumenttype]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/DigitalDocument.html
[jumioDocumentCredential]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/DocumentCredential.html
[jumioDataCredential]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/DataCredential.html
[jumioFaceCredential]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/FaceCredential.html
[jumioDocument]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Document.html
[jumioDocumentType]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/PhysicalDocument/DocumentType.html
[jumioDocumentVariant]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/PhysicalDocument/DocumentVariant.html
[jumioScanStep]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Step.html
[jumioScanUpdate]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update.html
[jumioScanMode]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Mode.html
[jumioCredentialPart]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Credential/Part.html
[jumioScanPart]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Part.html
[jumioConfirmationHandler]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Confirmation/Handler.html
[jumioRejectHandler]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Reject/Handler.html
[jumioFallbackReason]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update/FallbackReason.html
[jumioExtractionState]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update/ExtractionState.html
[jumioFlashState]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update/FlashState.html
[jumioTiltState]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Update/TiltState.html
[jumioPreloader]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Preloader.html
[jumioPreloaderDelegate]: https://jumio.github.io/mobile-sdk-ios/Jumio/Protocols/JumioPreloaderDelegate.html
[jumioAcquireMode]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Acquire/Mode.html
[jumioFileAttacher]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/FileAttacher.html
[jumioFileAttachHelpUrl]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/FileAttacher.html#/s:5JumioAAV12FileAttacherC7helpUrlSSSgvp
[jumioFileRequirements]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/FileRequirements.html
[jumioTermsOfUse]: https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/TermsOfUse.html

---

# Transition Guide

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/transition_guide

![Header Graphic](images/jumio_feature_graphic.jpg)

# Transition Guide for iOS SDK

This section covers all technical changes that should be considered when updating from previous versions, including, but not exclusively: API breaking changes or new functionality in the public API, major dependency changes, attribute changes, deprecation notices.

:::note
When updating your SDK version, **all** changes/updates made in in the meantime have to be taken into account and applied if necessary.
**Example:** If you're updating from SDK version **3.7.2** to **3.9.2**, the changes outlined in **3.8.0, 3.9.0** and **3.9.1** are **still relevant**.
:::

## 4.18.0

#### Changes to Public API

- `Jumio.DigitalDocument.DocumentType` enum has been added with the following supported values: `TRUST_CHECK`, `EIDAS`, `MASTERCARD`, `DIGITAL_DRIVING_LICENSE_PDF`
- `Jumio.DigitalDocument` property `type` has changed from `String` to `Jumio.DigitalDocument.DocumentType`
- `Jumio.DigitalDocument` contains new optional property `logoUrl`
- `Jumio.IDCredential` contains new function `setDefaultDocumentConfiguration()` 

#### Preselection

- Digital Identity documents can now be preselected via the account request. See the [Preselection](integration_guide.md#preselection) section in the integration guide for details.

#### Localization Keys

The following keys have been added:

- `jumio_di_continue_with_provider`
- `jumio_di_doctype_digital_id_subheader`
- `jumio_di_external_instructions_one`
- `jumio_di_external_instructions_two`
- `jumio_di_external_instructions_three`
- `jumio_di_external_sub_header`
- `jumio_di_select_from_list_below`
- `jumio_di_unexpected_error_description`
- `jumio_di_unexpected_error_title`
- `jumio_di_use_another_id`
- `jumio_di_what_happens_next`
- `jumio_physical_id`

The following keys have been renamed:

- `jumio_idtype_subtitle_id` has been renamed to `jumio_select_id_type`
- `jumio_di_vendor_selection_title` has been renamed to `jumio_di_choose_digital_id`

## 4.17.2

- Adds `CFBundleShortVersionString` to JumioLivenessClient.xcframework.

## 4.17.1

- Adds x86_64 simulator support to JumioLivenessClient.xcframework.

## 4.17.0

#### Changes to Public API

- Added `Jumio.LookupResult`
- Added `Jumio.LookupResult.LegalStatement`
- Added `Jumio.IDCredential.lookupResult`
- Added `Jumio.IDCredential.userConsented(to: Jumio.LookupResult.LegalStatement, decision: Bool)
- Added `Jumio.Credential.Info.order`
- Added `Jumio.TermsOfUse`
- Changed `Jumio.Controller.Delegate.jumio(controller: Jumio.Controller, didInitializeWith credentialInformations: [Jumio.Credential.Info], consentItems: [Jumio.ConsentItem]?)` to `Jumio.Controller.Delegate.jumio(controller: Jumio.Controller, didInitializeWith credentialInformations: [Jumio.Credential.Info], consentItems: [Jumio.ConsentItem]?, termsOfUse: Jumio.TermsOfUse?)`.

#### Logical Errors

- Added `pendingLowOrderCredential` for starting a credential when not all lower order credentials are completed.

#### Customization options

- Added `Jumio.Theme.termsOfUseForeground`

#### Localization Keys

The following keys have been added:

- `jumio_loaders_almost_there`
- `jumio_loaders_finishing_up`
- `jumio_loaders_starting_camera`
- `jumio_loaders_success`
- `jumio_loaders_this_will_take_a_moment`
- `jumio_loaders_working_on_it`
- `jumio_selfiedone_ID_Found`
- `jumio_selfiedone_continue`
- `jumio_selfiedone_scan_ID_manually`
- `jumio_selfiedone_we_found_your_ID`

The following key has been removed:

- `jumio_analyzing_biometric`
- `jumio_dv_confirm_file_info`
- `jumio_dv_method_description`
- `jumio_dv_retry_not_readable`
- `jumio_dv_retry_size_limit`
- `jumio_error_instant_feedback_bw_copy_tip_color_image`
- `jumio_error_instant_feedback_bw_copy_title`
- `jumio_error_instant_feedback_color_photocopy_title`
- `jumio_liveness_scanning_completed`
- `jumio_uploading_success`
- `jumio_uploading_title`

## 4.16.0

#### DefaultUI

- Removed support for landscape orientation on iPhones in DefaultUI.

#### Modules

- Removed `Jumio/IProov`, please use `Jumio/Liveness` instead.
- Removed NFC functionality from Jumio core:
  - Removed `Jumio/Slim` as now `Jumio/Jumio` acts as the only Jumio core product.
  - Added `Jumio/NFC` as new dependency for NFC functionality.
  - Check out the [Integration guide](integration_guide.md#via-cocoapods)

#### Customization options

- Added `Jumio.Theme.ScanView.shutter`
- Removed `Jumio.Theme.ScanView.documentShutter`
- Removed `Jumio.Theme.ScanView.faceShutter`

#### Document Verification

- Document Verification supports additional mime types:
    - `image/webp`
    - `image/jpeg`
    - `image/png`
    - `image/heic`
    
#### Scan Updates

- Added `Jumio.Scan.Update.ExtractionState.rotate`

## 4.15.0

#### Changes to Public API

The following functions and property-getters are now `async`:

- `Jumio.Controller.cancel()`
- `Jumio.Credential.cancel()`
- `Jumio.ScanPart.cancel()`
- `Jumio.ScanPart.finish()`
- `Jumio.Scan.View.isShutterEnabled`
- `Jumio.Scan.View.flash`
  - Added `Jumio.Scan.View.set(flash:)` as `Jumio.Scan.View.flash` is get-only.
- `Jumio.Scan.View.hasFlash`

The following functions and properties are now annotated with `@MainActor`:

- `Jumio.Confirmation.Handler.parts`
- `Jumio.Confirmation.Handler.renderPart(part:,view:)`
- `Jumio.Reject.Handler.parts`
- `Jumio.Reject.Handler.renderPart(part:,view:)`
- All functions in `Jumio.DefaultUI.Delegate`
- All functions in `Jumio.Controller.Delegate`
- All functions in `Jumio.ScanPart.Delegate`
- All functions in `Jumio.Preloader.Delegate`

The following classes, structs and enums conform now to `Sendable`:

- `Jumio.Theme` and all structs within
- `Jumio.Scan.Mode`
- `Jumio.Scan.Step`
- `Jumio.Scan.Update`
- `Jumio.Scan.Update.ExtractionState`
- `Jumio.Scan.Update.FallbackReason`
- `Jumio.Scan.Update.FlashState`
- `Jumio.Scan.Update.TiltState`

#### Customization options

- Added `Jumio.Theme.NFC.phoneScreen`
- Added `Jumio.Theme.NFC.chipPrimary`
- Added `Jumio.Theme.NFC.chipSecondary`
- Added `Jumio.Theme.NFC.chipBorder`
- Added `Jumio.Theme.NFC.pulse`

#### Localization Keys

The following keys have been added:

- `jumio_nfc_error_description_id`
- `jumio_nfc_error_description_other`
- `jumio_nfc_error_description_us`

The following key has been removed:

- `jumio_nfc_retry_error_general`

## 4.14.0

#### Scan Updates

- Added `Jumio.Scan.Update.ExtractionState.imageAnalysis`
- Added `Jumio.Scan.Update.cameraAvailable`

#### Localization Keys

The following keys have been added:

- `jumio_id_scan_prompt_analyzing`
- `jumio_scan_switch_to_back_camera`
- `jumio_scan_switch_to_front_camera`
- `jumio_switched_to_back_camera`
- `jumio_switched_to_front_camera`
- `jumio_button_continue`
- `jumio_change_issuing_country`
- `jumio_current_issuing_country`
- `jumio_eidas_description`
- `jumio_eidas_login_header`
- `jumio_european_did_login_header`
- `jumio_id_scan_hint_error_fallback`
- `jumio_select`

## 4.13.0

- Increased minimum iOS version to 13.0.
- Removed `Jumio/Datadog` module.

## 4.12.0

#### Scan Modes

- Added `Jumio.Scan.Mode.livenessPremium`

#### Scan Updates

- Added `Jumio.Scan.Update.ExtractionState.tiltFaceUp`
- Added `Jumio.Scan.Update.ExtractionState.tiltFaceDown`
- Added `Jumio.Scan.Update.ExtractionState.tiltFaceLeft`
- Added `Jumio.Scan.Update.ExtractionState.tiltFaceRight`
- Added `Jumio.Scan.Update.ExtractionState.moveFaceIntoFrame`

#### Jumio IDResult

- Added `curp` to `Jumio.IDResult`
- Removed `rawBarcodeData` from `Jumio.IDResult`

#### Localization Keys

The following keys have been added:

- `jumio_liveness_prompt_keep_centered`
- `jumio_liveness_prompt_keep_still`
- `jumio_liveness_prompt_keep_upright`
- `jumio_liveness_prompt_move_away`
- `jumio_liveness_prompt_success_another_scan`
- `jumio_liveness_prompt_tilt_down`
- `jumio_liveness_prompt_tilt_left`
- `jumio_liveness_prompt_tilt_right`
- `jumio_liveness_prompt_tilt_up`
- `jumio_liveness_scanning_completed`
- `jumio_error_scanning_not_possible`

The following keys have been removed:

- `jumio_liveness_prompt_success_another_shot`
- `jumio_error_ocr_failed`

#### Reject Reasons

- Added `Jumio.RejectReason.invalidCertificate`

#### File Attacher

- Added property `helpUrl`

#### ML Models

- Replaced model for determining liveness. Find the new model [here](https://cdn.mobile.jumio.ai/ios/model/liveness_sdk_assets_v_1_1_5.enc).

## 4.11.1

- Removed `Jumio/Datadog` from default podspec configuration. This fixes [this known issue](known_issues.md#xcode16).

## 4.11.0

#### SPM

- Library `JumioLocalization` makes it possible to localize strings with Swift Package Manager.

#### Scan Updates

- Added `Jumio.Scan.Update.ExtractionState.tilt`
- Added `Jumio.Scan.Update.TiltState`
- Added additional time parameter (in seconds) for `Jumio.Scan.Update.ExtractionState.holdStill` update
- Added `Jumio.Scan.Update.nextPosition`

#### Scan Steps

- `Jumio.Scan.Step.imageTaken` is sent exactly once per scan.
  - Please use `Jumio.Scan.Update.nextPosition` to determine the position change for Jumio Liveness instead.

#### Logical Errors

- Deprecated `noDataCenterSet` error
- Added `tokenValidationFailed` error for starting SDK with empty token
- Added `dataCenterValidationFailed` error for starting SDK without datacenter

#### Localization Keys

The following keys have been added:

- `jumio_id_scan_guide_photo_side_tilt`
- `jumio_id_scan_prompt_tilt_less`
- `jumio_id_scan_prompt_tilt_more`

#### Reject Reasons

- Added `401 unsupportedDocument` to `Jumio.RejectReason`.

## 4.10.1

- Removed `Jumio/Datadog` from default podspec configuration. This fixes [this known issue](known_issues.md#xcode16).

## 4.10.0

- Added `Jumio.Scan.Update.flash(FlashState)`
- Added `Jumio.Scan.Update.FlashState`
- Changed customization options
  - Renamed `Jumio.Theme.bubble.circleItemForeground` to `Jumio.Theme.bubble.outline`
  - Renamed `Jumio.Theme.scanView.bubbleForeground` to `Jumio.Theme.scanView.tooltipForeground`
  - Renamed `Jumio.Theme.scanView.bubbleBackground` to `Jumio.Theme.scanView.tooltipBackground`
  - Removed `Jumio.Theme.bubble.circleItemBackground`
  - Removed `Jumio.Theme.searchBubble.backgroundSelected`
  - Removed `Jumio.Theme.scanOverlay.fill`
  - Removed `Jumio.Theme.scanOverlay.scanOverlayTransparent`

#### Localization Keys

The following keys have been added:

- `jumio_id_scan_prompt_captured`

The following keys have been removed:

- `jumio_id_scan_prompt_front_captured`
- `jumio_id_scan_prompt_back_captured`

#### Localization

- Added Serbian (Cyril) `sr-Cyrl`
- Added Serbian (Latin) `sr-Latn`

## 4.9.1

- Fixed a crash on iOS 12 app startup.

## 4.9.0

- Minimum iOS version raised to 12.
- Removed `Jumio/DocFinder` dependency as the functionality was moved to Jumio core. Every dependency now contains DocFinder functionality.
- Removed `Jumio/DeviceRisk` dependency as the functionality was moved to Jumio API. Plase check out our [Integration guide](integration_guide.md#risk-signal-device-risk).
- Removed Default UI from Jumio core functionality
  - Added `Jumio/DefaultUI`
  - Check out the [Integration Guide](integration_guide.md)
- Added `idSubType` to `Jumio.IDResult`
- Added `Jumio/Preloader`, check out the [Integration Guide](integration_guide.md#preloading-models)
- New `Jumio.Retry.Reason.Face`
  - generic
  - tooMuchMovement
  - lightingTooBright
  - lightingTooDark
  - eyesClosed
  - obscuredFace
  - multipleFaces
  - sunglasses
- Changed customization options
  - Added `Jumio.Theme.face`
  - Added `Jumio.Theme.PrimaryButton.outline`
  - Added `Jumio.Theme.SecondaryButton.foregroundPressed`
  - Added `Jumio.Theme.SecondaryButton.foregroundDisabled`
  - Added `Jumio.Theme.SecondaryButton.outline`
  - Added `Jumio.Theme.SearchBubble.outline`
  - Added `Jumio.Theme.Loading.loadingAnimationGradient`
  - Added `Jumio.Theme.Loading.loadingAnimationErrorGradient`
  - Added `Jumio.Theme.Confirmation.imageBorder`
  - Renamed `Jumio.Theme.Bubble.selectionIconForeground` to `Jumio.Theme.selectionIconForeground`
  - Renamed `Jumio.Theme.SearchBubble.listItemSelected` to `Jumio.Theme.SearchBubble.backgroundSelected`

## 4.8.1

- Removed `Starscream` dependency for `Jumio/IProov`.

## 4.8.0

#### Manual Integration

- Framework `JumioLiveness.xcframework` is now required when using `JumioIProov.xcframework`

#### Carthage Integration

- Framework `JumioLiveness.xcframework` is now required when using `JumioIProov.xcframework`

## 4.7.1

- Removed `Starscream` dependency for `Jumio/IProov`.

## 4.7.0

#### Barcode

- Removed `Jumio/Barcode` dependency as the functionality was moved to Jumio core. Every dependency now contains Barcode functionality.

#### MRZ

- Removed `Jumio/MRZ` dependency. Please use `Jumio/Jumio` instead.

#### NFC

- Removed `Jumio/NFC` dependency. Please use `Jumio/Jumio` instead.

#### Linefinder

- Removed `Jumio/LineFinder` dependency. Please use `Jumio/Slim` in combination with `Jumio/DocFinder` instead.

#### Changes to Public API

- Deprecated `Jumio.Theme.IProov.animationForeground`
  - Added `Jumio.Theme.ScanHelp.faceAnimationForeground`
- Deprecated `Jumio.Theme.IProov.animationBackground`
  - Added `Jumio.Theme.ScanHelp.faceAnimationBackground`
- Deprecated `Jumio.Theme.PrimaryButton.text`
  - Added `Jumio.Theme.PrimaryButton.foreground`
- Deprecated `Jumio.Theme.SecondaryButton.text`
  - Added `Jumio.Theme.SecondaryButton.foreground`
- Added `Jumio.Theme.PrimaryButton.foregroundPressed`
- Added `Jumio.Theme.PrimaryButton.foregroundDisabled`
- Removed `Jumio.Scan.Mode.lineFinder`
- Removed `Jumio.Scan.Mode.mrz`
- Deprecated `Jumio.Scan.Update.legalHint`
- Deprecated `Jumio.SDK.giveDataDogConsent(enabled: Bool)`
- Deprecated `Jumio.IDResult.rawBarcodeData`

#### Localization Keys

The following keys have been added:

- jumio_id_scan_guide_photo_side
- jumio_id_scan_guide_back_side
- jumio_id_scan_guide_photo_side_manually
- jumio_id_scan_guide_back_side_manually

The following keys have been removed:

- jumio_id_scan_guide_take_photo_front_idc
- jumio_id_scan_guide_take_photo_back_idc
- jumio_id_scan_guide_take_photo_passport
- jumio_id_scan_guide_take_photo_front_dl
- jumio_id_scan_guide_take_photo_back_dl
- jumio_id_scan_guide_take_photo_front_pd
- jumio_id_scan_guide_take_photo_back_pd

#### Localization

- Replaced Portuguese `pt` with Portuguese (Portugal) `pt-PT`
- Added Portugise (Brasil) `pt-BR`

#### SPM

- Library `JumioDatadog` which can be used to integrate JumioDatadog.

#### Carthage

- Added `JumioDatadog.json`.

#### Frameworks

- Datadog dependency `DatadogSDK` is removed

## 4.6.2

- Removed `Starscream` dependency for `Jumio/IProov`.

## 4.6.1

#### Cocoapods

- `pod 'Jumio/DeviceRisk'` was removed from `pod 'Jumio/All'`.

## 4.6.0

#### Liveness

- Added new library `JumioLiveness` to enhance the Liveness user experience/interface. Check out our [Integration Guide](integration_guide.md).
- Removed liveness confirmation handling

#### Cocoapods

- `pod 'Jumio/IProov'` replaces ~~`pod 'Jumio/Liveness'`~~ as new pod for using iProov liveness technology.
- `pod 'Jumio/Liveness'` is now required to use the Jumio liveness solution.

#### SPM

- Library `'JumioIProov'` replaces ~~`'JumioLiveness'`~~ as new library for our iProov liveness solution.
- Library `'JumioLiveness'` is now required to use the Jumio liveness solution.

#### Carthage

- Added `'JumioLiveness.json'` which is now required to use the Jumio liveness solution.

#### Changes to Public API

- Deprecated `Jumio.Theme.ScanView.shutter`:
  - Added `Jumio.Theme.ScanView.documentShutter`
  - Added `Jumio.Theme.ScanView.faceShutter`

## 4.5.0

#### Customization

- Option `Jumio.Theme.ScanView.animationBackground` has been removed.

#### Changes to Public API

- Error code format updated from `[A][x][yyyy]` to `[A][xx][yyyy]`
- Deprecated `Jumio.IDCredential.countries`:
  - Added `Jumio.IDCredential.supportedCountries`
  - Added `Jumio.IDCredential.physicalDocuments(for:)`
  - Added `Jumio.IDCredential.digitalDocuments(for:)`
- Added `Jumio.SDK.handleDeeplinkURL()`
- Added `Jumio.Document.Physical`
- Added `Jumio.Document.Digital`
- New `Jumio.Credential.Part`
  - digital
- New `Jumio.Scan.Step`
  - digitalIdentityView
  - thirdPartyVerification
- New `Jumio.Retry.Reason.DigitalIdentity`
  - unknown
  - expired
  - thirdPartyVerificationError
  - serviceError
- Changed `JumioScanView`
  - Changed `extraction` variable to get-only
  - Added `startExtraction()` function
  - Added `stopExtraction(hidePreview: Bool)` function
- Changed `JumioControllerDelegate`
  - Changed `jumio(controller: Jumio.Controller, didInitializeWith credentialInformations: [Jumio.Credential.Info], policyUrl: String?)` to `jumio(controller: Jumio.Controller, didInitializeWith credentialInformations: [Jumio.Credential.Info], consentItems: [Jumio.ConsentItem]?)`
- Changed `Jumio.Controller`
  - Changed `userConsented()` to be `userConsented(to consentItem: Jumio.ConsentItem, decision: Bool)`
  - Added `getUnconsentedItems() -> [Jumio.ConsentItem]?`

#### Localization Keys

The following keys have been added:

- jumio_idtype_di
- jumio_di_vendor_selection_title
- jumio_di_retry_unknown
- jumio_di_retry_third_party_verification_error
- jumio_di_retry_service_error
- jumio_di_back_to_document_selection

#### Cocoapods

- install hook for liveness is changed in the `podfile`:

```
post_install do |installer|
   installer.pods_project.targets.each do |target|
     if ['iProov', 'Starscream'].include? target.name
       target.build_configurations.each do |config|
           config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
       end
     end
    end
end
```

#### Frameworks

- iProov dependency `SwiftProtobuf` is removed

## 4.4.0

#### Changes to Public API

- New `Jumio.Credential.Part`
  - `multipart`: This is the new Autocapture scan part. Instead of having a single scan part for all parts of a document (front, back), there is now a single `multipart` scan part that combines the two. Within this scan part all needed parts of a document are captured at once.
- New `Jumio.Scan.Step`
  - `nextPart`: This scan step shows that the previous part has been captured and the next one can be started (e.g. frontside has been captured, now switch to the backside of the document). Contains the `Jumio.Credential.Part` as additional data. We suggest to actively guide the user to move to the next part, e.g. by showing an animation and by disabling the extraction during the animation.
- Updated `Jumio.Scan.Step.started`
  - Added `Jumio.Credential.Part` as additional data
- Changed confirmation and reject handling
  - Added `Jumio.Confirmation.Handler`
  - Added `Jumio.Reject.Handler`
  - Moved `attach`, `detach`, `retake` and `confirm` methods from `Jumio.Confirmation.View` to `Jumio.Confirmation.Handler`
  - Moved `attach`, `detach` and `retake` methods from `Jumio.Reject.View` to `Jumio.Reject.Handler`
  - As a result the confirmation views for front and/or back within multipart scans are obsolete and not existing anymore.
- New `Jumio.Retry.Reason.iProov`:
  - faceMisaligned
  - eyesClosed
  - faceTooFar
  - faceTooClose
  - sunglasses
  - obscuredFace
  - userTimeout
  - notSupported
- Updated `Jumio.Scan.Step.rejectView`:
  - The returned scan step data now contains a dictionary `[Jumio.Credential.Part: Jumio.RejectReason]` instead of a single `Jumio.RejectReason`.
- Removed `Jumio.Retry.Reason.iProov`:
  - ambiguousOutcome
  - lightingFlash
  - lightingBacklit
  - motionMouth
- New options in `Jumio.Theme.IProov`:
  - filterBackgroundColor
  - surroundColor
  - livenessAssuranceCompletedOvalStrokeColor
- Renamed options in `Jumio.Theme.IProov`:
  - lineColor to filterForegroundColor
  - headerTextColor to titleTextColor
  - floatingPromptRoundedCorners to promptRoundedCorners
  - genuinePresenceAssuranceReadyOverlayStrokeColor to genuinePresenceAssuranceReadyOvalStrokeColor
  - genuinePresenceAssuranceNotReadyOverlayStrokeColor to genuinePresenceAssuranceNotReadyOvalStrokeColor
  - livenessAssuranceOverlayStrokeColor to livenessAssuranceOvalStrokeColor
  - genuinePresenceAssuranceReadyFloatingPromptBackgroundColor to promptBackgroundColor
  - genuinePresenceAssuranceNotReadyFloatingPromptBackgroundColor to promptBackgroundColor
  - livenessAssuranceFloatingPromptBackgroundColor to promptBackgroundColor
- Removed options in `Jumio.Theme.IProov`:
  - headerBackgroundColor
  - footerBackgroundColor
  - livenessAssurancePrimaryTintColor
  - livenessAssuranceSecondaryTintColor
  - genuinePresenceAssuranceProgressBarColor
  - genuinePresenceAssuranceNotReadyTintColor
  - genuinePresenceAssuranceReadyTintColor
  - floatingPromptEnabled

#### Localization Keys

The following keys have been added:

- IProov_PromptAlignFace
- IProov_FailureEyesClosed
- IProov_FailureFaceTooClose
- IProov_FailureFaceTooFar
- IProov_FailureMisalignedFace
- IProov_FailureNotSupported
- IProov_FailureObscuredFace
- IProov_FailureSunglasses
- IProov_FailureTooBright
- IProov_FailureTooDark
- IProov_FailureTooMuchMovement
- IProov_FailureUnknown
- IProov_FailureUserTimeout
- IProov_AccessibilityPromptAlignFace
- IProov_AccessibilityPromptScanning
  The following keys have been renamed:
- IProov_ErrorCameraPermissionDeniedMessageIos to IProov_ErrorCameraPermissionDeniedMessage
  The following keys have been removed:
- IProov_MessageFormat
- IProov_PromptTapToBegin
- IProov_PromptLivenessAlignFace
- IProov_PromptLivenessNoTarget
- IProov_PromptGenuinePresenceAlignFace
- IProov_ProgressStreamingSlow
- IProov_PromptGrantPermission
- IProov_PromptGrantPermissionMessage
- IProov_FailureAmbiguousOutcome
- IProov_FailureLightingBacklit
- IProov_FailureLightingFaceTooBright

* IProov_FailureLightingFlashReflectionTooLow

- IProov_FailureLightingTooDark
- IProov_FailureMotionTooMuchMouthMovement
- IProov_FailureMotionTooMuchMovement

#### Liveness

- We have seperated our liveness solution in `JumioIProov.xcframework`. You need to add this framework beside `Jumio.xcframework` to your project.

#### Cocoapods

- The following pods have been removed. Instead `Jumio/Liveness` should be added in your pod file.
  - `pod 'Jumio/SlimLiveness'`
  - `pod 'Jumio/LineFinderLiveness'`
  - `pod 'Jumio/MRZLiveness'`
  - `pod 'Jumio/BarcodeLiveness'`
  - `pod 'Jumio/NFCLiveness'`
- install hook for liveness is changed in the `podfile`:

```
post_install do |installer|
   installer.pods_project.targets.each do |target|
     if ['iProov', 'SwiftProtobuf', 'Starscream'].include? target.name
       target.build_configurations.each do |config|
           config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
       end
     end
    end
end
```

#### Frameworks

- iProov dependency `SwiftProtobuf` is added
- iProov dependency `SocketIO` is removed

## 4.3.1

No backward incompatible changes.

## 4.3.0

#### Changes to the Public API

- `Jumio.Scan.Update.fallback` has now an additional `Jumio.Scan.Update.FallbackReason`:

  - `userAction`: Initiated by the user through the call of `Jumio.Scan.ScanPart.fallback()`.
  - `lowPerformance`: Initiated due to low performance on the current `Jumio.Scan.Mode`.

- Document Verification is now supported. Please check the [Integration Guide](integration_guide.md#jumio-document-credential) for more information.

#### Cocoapods

- One new pod added, containing data analysis functionality:
  - `pod 'Jumio/Datadog'`
  - `pod 'Jumio/DocFinder'`
  - `pod 'Jumio/All'` replaces ~~`pod 'Jumio/Jumio'`~~ as default subspec of `pod 'Jumio'`

#### Simulator Slice

- Minimum iOS version for simulator slice was increased to 15.0

## 4.2.0

#### Changes to the Public API

- `Jumio.Theme.Value(light: UIColor?, dark: UIColor?)` has been replaced by `Jumio.Theme.Value(light: UIColor, dark: UIColor)`.
- `Jumio.Theme.Value(_: UIColor)` has been added. This initializer should be used to provide one color for both light and dark mode.
- `Jumio.Scan.Side` has been renamed to `Jumio.Credential.Part`.

## 4.1.2

No backward incompatible changes.

## 4.1.1

#### Customization

Added Customization functionality to enable customizing Jumio Theme. `Jumio.Theme` is a class that can be used to create a custom theme and override colors for Jumio views.

For more details on Customization, please refer to [Customization](integration_guide.md#customization) in our guides.

#### ObjC support

Added DefaultUI support for Objective-C based projects. Now `JumioSDK` class can be reached and initiated form Objective-C code with it's own configuration and delegate `JumioDefaultUIDelegate`.

## 4.1.0

#### Cocoapods

- Two new pods added, containing NFC scan functionality:
  - `pod 'Jumio/NFC'`
  - `pod 'Jumio/NFCLiveness'`

#### Instant Feedback Reject Reasons

Added Instant Feedback functionality to give more granular user feedback with new reject reasons:

- blackWhiteCopy
- colorPhotocopy
- digitalCopy
- notReadable
- noDoc
- missingBack
- missingFront
- blurry
- missingPartDoc
- damagedDocument
- hiddenPartDoc
- glare

## 4.0.0

#### Authentication

ℹ️&nbsp;&nbsp;**As of version 4.0.0 and onward, the SDK can only be used in combination with Jumio KYX or Jumio API v3. API v2 as well as using API token and secret to authenticate against the SDK will no longer be compatible.**

#### Cocoapods

Please refer to the [Integration section](integration_guide.md#via-cocoapods) of our guides for a detailed description of all Cocoapods and framework changes.

#### Default UI Updates

As of SDK version 4.0.0, a lot of SDK parameters that previously could be set in the actual code are now contained within and provided by the `sdk.token`. These parameters have to be configured beforehand, during the API call that requests the token.

Please refer to the [Configuration section](integration_guide.md#configuration) of our integration guides for a detailed description of all Default UI changes and updates.

Information about which user journey (ID Verification, Identity Verification, Authentication, ...) the SDK is going to provide now also has to be specified during the API call that request the `sdk.token`.

For more details on individual Jumio workflows, please refer to [Workflow Descriptions](https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/standardServices) in our guides.

#### Custom UI Updates

As of SDK version 4.0.0, Custom UI workflow has been completely restructured.

Please refer to the [Custom UI section](integration_guide.md#custom-ui) of our integration guides for a detailed description of all Custom UI changes and updates.

---

# Known Issues

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/known_issues

![Header Graphic](images/jumio_feature_graphic.jpg)

# Known Issues

## Portrait Effect

The Liveness check will fail, if you add the key `NSCameraPortraitEffectEnabled` to your Info.plist file. Make sure that it is not set.

## Xcode16

There might be crashes on app startup when using our Datadog frameworks with Xcode16 via Cocoapods.
For versions `4.10.0` and `4.11.0` if you use `Jumio` default podspec (`All`) please use the fixed versions `4.10.1` and `4.11.1`.
For versions below `4.10.0` or if you use `Jumio/Datadog` pod we advise to remove the Datadog dependency (`Jumio/Datadog`) or update to the newer versions.

## Apple Privacy Guidelines

The guide of Jumio SDK compliance to Apple Privacy Guidelines is in [integration FAQ](integration_faq.md#apple-privacy-guidelines)

## 4.9.0

There might be crashes on app startup when using our `4.9.0` frameworks on iOS 12.
Please use version `4.9.1` instead.

## SDK Runs Fine on Debug Build, Fails on Release Build

For Xcode 13 and above, application might build and run fine for debug builds, but crash on release builds. This might also occur with Testflight. When archiving / exporting an app with Xcode 13, Jumio SDK cannot be initialized and might throws the following exception, despite the fact that SDK version and all framework versions appear to be correct:

```
SDKVersionNotCompatibleException: JumioFRAMEWORK is expected to be of version X.X.X
```

This is due to Xcode 13 introducing a new option to their **App Store Distribution Options**:

**"Manage Version and Build Number"** (see image below)

If checked, this option changes the version and build number of all content of your app to the overall application version, including third-party frameworks. **This option is enabled by default.** Please make sure to disable this option when archiving / exporting your application to the App Store. Otherwise, the Jumio SDK version check, which ensures all bundled frameworks are up to date, will fail.

![Xcode13 Issue](images/known_issues_xcode13.png)

Alternatively, it is also possible to set the key `manageAppVersionAndBuildNumber` in the **exportOptions.plist** to `false`:

```
<key>manageAppVersionAndBuildNumber</key>
<false/>
```

## Library Not Loaded: Image Not Found

Building an application using Objective C might result in the following error:

`Termination Description: DYLD, Library not loaded: @rpath/libswiftCore.dylib | Referenced from: {PATH} | Reason: image not found`

Please make sure `ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES` is set to `Yes` in the **Build Options.**

## Custom Theme Issues

### Language Localization Issues

Please make sure to select your project in the project and targets list in the **Project Navigator,** navigate to the **Info** tab. In the **Localizations** section, make sure that _"Use Base Internationalization"_ is checked. Otherwise, the system will fall back on the default localization.

To select a different language use the “+” button in the **Localizations** section. This will let you choose a new language you want to support from a dropdown list. Please refer to the [full list of languages supported by Jumio](../README_iOS.md#language-localization) for more details. Adding a new language from the list will generate files under a new language project folder named `[new language].lproj` For example, if Japanese support is added, a folder named `ja.lproj` will be created.

#### Localizable.strings File

The `Localizable-Jumio.strings` file makes it possible to easily add translations as key-value pairs. Adapt the values to your required language as needed and add it to your app or framework project. Again, please make sure to mark the project as _Localizable._ After SDK updates, make sure to check whether the content of this localization file is up to date, as individual strings may have changed.

:::tip
Refer to the transition guides for possible updates.
:::

#### Language Changes at Runtime

Runtime language changes _within_ the SDK or separate language support (meaning the SDK language differs from the overall device language) is not possible. This goes against Apple's basic iOS user model for switching languages in the Settings app.

---

# Integration Glossary

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/integration_glossary

![Header Graphic](images/jumio_feature_graphic.jpg)

# Glossary

## Commonly Used Abbrevations

### CVV

Card Verification Value: A verification number on any credit card, usually 3-4 digits long

### DOB

Date Of Birth

### DV

Driver’s License

### GDPR

[General Data Protection Regulation](https://gdpr-info.eu) (EU): EU-wide data privacy regulation protecting natural persons and their personal data, especially in regards to collecting, processing and the free movement of that data

### ISO 3166-1

ISO standard detailing standard country code abbreviations (like AUT, DEU, etc); either [alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (using two letters) or [alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) (using three letters)

### KYC

Know Your Customer

### KYX

Know Your Everything: Jumio’s end-to-end [identity platform](https://www.jumio.com/platform/)

### MRP

Machine Readable Passport

### MRTD

Machine Readable Travel Document

### eMRTD

Electronic Machine Readable Travel Document

### NFC

[Near-Field Communication:](https://en.wikipedia.org/wiki/Near-field_communication#Identity_and_access_tokens) Establishes wireless connection from one device to another, but only if that device is in close enough proximity; can act as an electronic identity document / electronic identity token and is already used in many identity documents worldwide

### NV

Netverify

### OAuth2

An [industry-standard protocol for authorization](https://oauth.net/2/)

### OAuth2 Access Token

An [access token using the OAuth2 protocol](https://oauth.net/2/access-tokens/) to make safe API calls and securely access resources from a server

### OCR

[Optical Character Recognition:](https://en.wikipedia.org/wiki/Optical_character_recognition) Converts images of text, such as text on IDs, to machine-encoded and machine-readable text

### PII

Personal(ly) Identifiable Information: All of our products deal with highly sensitive data regarding information relating to an identifiable person, which is handled with great care, the best possible security and in compliance with the GDPR.

### PP

Passport

### 3D-Liveness

Liveness check: The 3D-liveness check makes sure that a face scan performed was not of a picture, but of an actual, living person who also matches the picture on the previously scanned document.

---

# Integration FAQ

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/integration_faq

import enhanced_injection_detection_02 from './images/capturing_methods/enhanced_injection_detection_02.png';
import enhanced_injection_detection_01 from './images/capturing_methods/enhanced_injection_detection_01.png';
import manual_capturing_02 from './images/capturing_methods/manual_capturing_02.png';
import manual_capturing_01 from './images/capturing_methods/manual_capturing_01.png';
import barcode_scanning_02 from './images/capturing_methods/barcode_scanning_02.png';
import barcode_scanning_01 from './images/capturing_methods/barcode_scanning_01.png';
import autocapture_02 from './images/capturing_methods/autocapture_02.png';
import autocapture_01 from './images/capturing_methods/autocapture_01.png';
import user_consent_active_on from './images/consent/user_consent_active_on.png';
import user_consent_active_off from './images/consent/user_consent_active_off.png';
import user_consent_passive from './images/consent/user_consent_passive.png';

![Header Graphic](images/jumio_feature_graphic.jpg)

# FAQ

## User Consent

User consent is now acquired for all users to ensure the accordance with biometric data protection laws. Depending on the legal requirements, consent can be acquired in one of two ways: **Active** or **passive**.

For **active** consent instances, the user needs to accept the consent items explicitly, e.g. by enabling a UI switch or checking a checkbox for each consent item. For **passive** consent instances, it is enough to present the consent text and URL to the user. The user implicitly accepts the passive consent items by continuing with the journey.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={user_consent_passive} alt="Acquiring passive user consent" style={{ width: '30%', height: 'auto' }} />
  <img src={user_consent_active_off} alt="Acquiring active user consent" style={{ width: '30%', height: 'auto' }} />
  <img src={user_consent_active_on} alt="Acquiring passive user consent" style={{ width: '30%', height: 'auto' }} />
</div>

## Apple Privacy Guidelines

At WWDC23 Apple introduced new privacy manifest and signature for third-party software development kits (SDKs) and announced that developers will need to declare approved reasons for using a set of APIs in their app’s privacy manifest. These changes help app developers better understand how third-party SDKs use data, secure software dependencies, and provide additional privacy protection for end users.
On March 13, 2024, App updates or new Apps added to App Store Connect that use an API requiring approved reasons, Apple will send an email if the app’s privacy manifest is missing any reason.
On May 1, 2024, App updates or new Apps added to App Store Connect should comply with the Apple Privacy Guidelines.

After the WWDC23 announcement, the requested changes were applied and released with Jumio SDK 4.6.1. Starting from Jumio SDK 4.6.1 and the versions released afterward, Jumio frameworks follow the privacy guidelines requested from Apple.

Apple also published a list of most commonly used third-party SDKs. Any version of a listed SDK, as well as any SDKs that repackage those on the list, must contain a privacy manifest and a signature.
One of Jumio SDK optional dependencies, iProov, uses one of the SDKs mentioned in the list, Starscream. iProov SDK provided new releases v11.0.3 and v10.3.3 which follow the privacy guidelines. The new iProov version was included in Jumio SDK 4.9.0. Jumio SDK also included the updated iProov SDK in the versions 4.6.2, 4.7.1 and 4.8.1.

Jumio frameworks follow Apple privacy guidelines starting from version 4.6.1 and onwards.
Jumio frameworks and Jumio optional dependencies (iProov) follow Apple privacy guidelines on version 4.6.2, 4.7.1, 4.8.1, 4.9.0 and onwards.

## Apple Accessibility Nutrition Labels

At WWDC25 Apple introduced Accessibility Nutrition Labels, which inform users before download whether the app is accessible to them. Jumio conforms to and tests the following accessibility categories:

- VoiceOver: The Jumio SDK supports VoiceOver.
- Larger Text: It is possible to increase text size within the Jumio SDK.
- Dark Interface: The Jumio SDK supports both light and dark mode.
- Differentiate Without Color Alone: The Jumio SDK doesn't rely solely on color, but uses shapes to indicate required user actions.
- Sufficient Contrast: The Jumio SDK follows the color guidelines to have sufficient contrast.
- Reduced Motion: The Jumio SDK doesn't contain any animations, which could cause discomfort.
- Captions: The Jumio SDK doesn't play any videos.
- Audio Descriptions: The Jumio SDK doesn't play any audio.

## Autocapture

The new Autocapture experience allows users to capture multiple images within a single camera session. For example the user can be guided to first capture the front of a document, then flip the document and capture the back of a document.

https://user-images.githubusercontent.com/27801945/232710790-9caf1be0-145e-4cf6-b1ff-5a7b98d4ab66.mov

## Improve User Experience and Reduce Drop-off Rate

When evaluating user flows, one of the most commonly used metrics is the rate of drop-offs. At Jumio, we see considerable variance in drop-off rates across industries and customer implementations. For some implementations and industries, we see a higher rate of drop-offs on the first screens when compared with the average.
Scanning an ID with sensitive personal data printed on it naturally creates a high barrier for participation on the part of the end user. Therefore, conversion rates can be significantly influenced when the application establishes a sense of trust and ensures that users feel secure sharing their information.

One pattern that is recognizable throughout all of our customers’ SDK implementations: the more seamless the SDK integration, and the better job is done of setting user expectations prior to the SDK journey, the lower the drop-off rate becomes.

Our SDK provides a variety of [customization options](integration_guide.md#customization) to help customers achieve a seamless integration. For customers using the standard SDK workflow, our [Surface tool](https://jumio.github.io/surface-tool/) provides an easy-to-use WYSIWYG interface to see simple customization options that can be incorporated with minimal effort and generate the code necessary to implement them. For customers who want to have more granular control over look and feel, our SDK offers the [CustomUI](integration_guide.md#custom-ui) option, which allows you to customize the entire user interface.

### Example of a Non-Ideal SDK Integration:

![Onboarding bad case](images/onboardingBadCase.jpg)

- Default SDK UI is used and is presented on one of the first screens during onboarding. The user is unprepared for the next steps and might not understand the intention behind the request to show their ID.

### Suggested Improvements with Additional Customization:

![Onboarding good case](images/onboardingGoodCase.jpg)

- Host application has an explanatory help screen that explains what will happen next and why this information is needed.
- In `multipart` ScanParts, the user is guided to move to the next part (e.g. back side of the identity card) with an animation. The extraction should be disabled during this guidance.
- SDK is either customized to have a more embedded appearance or [CustomUI](integration_guide.md#custom-ui) is used to create a completely seamless integration in the UX of our customers.
- Also after the Jumio workflow that shows the displayed results and/or a message that the ID is currently verified, which might take some minutes.

## Managing Errors

Not every error that is returned from the SDK should be treated the same. The [error codes listed for ID Verification](integration_guide.md#error-codes) should be handled specifically.

The following table highlights the most common error codes which are returned from the SDK and explains how to handle them appropriately in your application.

|    Code     | Cause                                                                                              | Recommended Handling                                                                                                                                              |
| :---------: | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A[xx][yyyy] | Caused by temporary network issues like a slow connection.                                         | Advise to check the signal and retry the SDK journey.                                                                                                             |
| E[xx][yyyy] | Flight mode is activated or no connection available.                                               | The user should be asked to disable flight mode or to verify if the phone has proper signal. Advise to connect to WIFI and retry the SDK journey afterwards.      |
| G[00][0000] | The user pressed back or X to exit the SDK while no error view was presented.                      | Reasons for this could be manyfold. Often it might be due to the fact that the user didn't have his identity document at hand. Give the user the option to retry. |
| J[xx][yyyy] | The SDK journey was not completed within the session's max. lifetime. (The default is 15 minutes.) | The user should be informed about the timeout and be directed to start a new Jumio SDK session.                                                                   |

### Ad blockers or Firewall

End users might face the situation where they are connected to a network that can't reach our Jumio endpoints.
Possible reasons for this might be ad blockers on the device, network wide ad blockers or network specific firewall settings.
In these cases the SDK will return a specific error code: A10900. If this error is received we suggest to add a screen where the user is advised to switch network and/or turn off possible ad blockers.

## Reducing the Size of Your App

The Netverify SDK contains a wide range of different scanning methods. The SDK is able to capture identity documents and extract information on the device using enhanced machine learning and computer vision technologies. If you want to reduce the size of the SDK within your application, there are several ways to achieve this:

### Strip Unused Frameworks

Depending on your specific needs, you may want to strip out unused functionality. As most of our frameworks can be linked optionally, you can reduce file size by simply not adding them to your project.

The following table shows a range of different product configurations with the frameworks that are required and the corresponding application size. These measurements reflect the extra size that Jumio components add to your app download size and are based on our [sample application](../sample) after being uploaded to the [Appstore](https://apps.apple.com/us/app/jumio-showcase/id639531180).

| Product Configuration |  Size   |            Modules             |
| :-------------------- | :-----: | :----------------------------: |
| Core                  | 3.08 MB |              base              |
| Core + NFC            | 4.94 MB |           base, nfc            |
| Core + DefaultUI      | 4.42 MB |       base, defaultUI          |
| Core + Liveness       | 4.96 MB |        base, liveness          |
| Core + all            | 8.16 MB | base, nfc, defaultUI, liveness |

In case you use a combination of these products, make sure to add frameworks only once to your app and that those frameworks are linked and embedded in your Xcode project.

## Jumio Authentication Workflow Integration

Jumio Authentication can be used for any use case in which you want your end-users to confirm their identities. As a result of the Authentication journey you get a success or failed result back from the SDK or from our server (callback or retrieval).

In case of a **successful result** you can grant the user access to your service or let him proceed with the user flow. In case of a **failed result**, a proper retry handling within your workflow is necessary. A failure could occur because of the following reasons:

- The user presenting their face is a different one than the user who owns the account
- An imposter is trying to spoof the liveness check
- User does not want to show their face at all, but is still trying to complete the onboarding
- User does not look straight into the camera
- User does not finish the first or second step of face scan
- User has bad lighting conditions (too dark, too bright, reflections on face, not enough contrast, …)
- User is covering (parts) of their face with a scarf, hat or something similar
- A different person is scanning their face in the second step than in the first one
- User is not able to align his face with the oval presented during scanning

In case an Authentication fail is returned, we recommend to allow the user between 3-5 Authentication attempts to prove their identity, before you lock the user from performing the action. This approach makes the most sense, as you don't want to lock out possible valid users who might not have completed the face capture task successfully for a legitimate reason. Don't worry about offering a potential fraudster more attempts to gain access to your system - our bullet proof liveness check does not allow them to get a successful result.

## Fallback and Manual Capturing

The variable [`hasFallback`](https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Part.html#/s:5JumioAAV4ScanV4PartC11hasFallbackSbvp) determines if a fallback for the current scan mode is available and returns a boolean. If the method returns true, the available fallback scan mode will have to be started with the method [`fallback()`](https://jumio.github.io/mobile-sdk-ios/Jumio/Structs/Jumio/Scan/Part.html#/s:5JumioAAV4ScanV4PartC8fallbackyyF).

The variable [`isShutterEnabled`](https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html#/s:5Jumio0A8ScanViewC16isShutterEnabledSbvp) determines if a shutter button needs to be shown because the image has to be taken manually and returns a boolean. If the method returns true, you will have to display your own shutter button and call the method [`takePicture()`](https://jumio.github.io/mobile-sdk-ios/Jumio/Classes/JumioScanView.html#/s:5Jumio0A8ScanViewC11takePictureyyF) once it is clicked.

:::note
Please note that the variable `isShutterEnabled` does neither create nor display the actual shutter button!
:::

"Manual capturing" simply refers to the user being able to manually take a picture. "Fallback" refers to an alternative scan mode the SDK can resort to if possible, in case there is an issue during the original scanning process. The fallback scan mode might be manual capturing in some cases, but not all.

## Language Localization

Our SDK supports localization for different languages and cultures. All label texts and button titles can be changed and localized using the `Localizable-Jumio.strings` file. Just adapt the values to your required language, add it to your app or framework project and mark it as Localizable.

This way, when upgrading our SDK to a newer version your localization file won't be overwritten. Make sure, that the content of this localization file is up to date after an SDK update. If you're having issues with Localization, please refer to our [Known Issues](known_issues.md#language-localization-issues)

:::note
If using CocoaPods, the original file is located under `/Pods/Jumio/Localization`.
:::

Currently, the following languages are automatically supported for your convenience: [supported languages](../README_iOS.md#language-localization)

Runtime language changes _within_ the SDK or separate language support (meaning the SDK language differs from the overall device languages) is not possible.

### Accessibility

Our SDK supports accessibility features. Visually impaired users can enable **VoiceOver** or increase **text size** on their device. VoiceOver uses separate values in the localization file, which can be customized.

## Overview of Scanning Methods

#### Autocapture

Combines all previously existing scanning methods into one automatic, seamless experience.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={autocapture_01} alt="Autocapture Success" style={{ width: '30%', height: 'auto' }} />
  <img src={autocapture_02} alt="Autocapture Scanning" style={{ width: '30%', height: 'auto' }} />
</div>

#### Barcode

PDF417 barcode data extraction, for example from US and Canadian driver licenses.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={barcode_scanning_01} alt="Barcode Empty" style={{ width: '30%', height: 'auto' }} />
  <img src={barcode_scanning_02} alt="Barcode Document" style={{ width: '30%', height: 'auto' }} />
</div>

#### Manual Capture

Manual scanning (taking a picture) using the shutterbutton, fallback option in case user is having trouble.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={manual_capturing_01} alt="Manual Capture Empty" style={{ width: '30%', height: 'auto' }} />
  <img src={manual_capturing_02} alt="Manual Capture Document" style={{ width: '30%', height: 'auto' }} />
</div>

#### Enhanced Injection Detection

You may see additional detection screens during the ID Scan process. This is expected behavior and is part of Jumio's enhanced fraud protection measures.

<div style={{ display: 'flex', gap: '10px' }}>
  <img src={enhanced_injection_detection_01} alt="Enhanced Injection Detection" style={{ width: '30%', height: 'auto' }} />
  <img src={enhanced_injection_detection_02} alt="Enhanced Injection Detection" style={{ width: '30%', height: 'auto' }} />
</div>

## Glossary

A [quick guide to commonly used abbreviations](integration_glossary.md) throughout the documentation which may not be all that familiar.

## Simulator Support

We don't support the use of the Jumio SDK on simulator, please only run it on physical devices. When running Jumio SDK in Default UI, an empty ViewController will be presented. When running Jumio SDK in Custom UI, the SDK won't provide any functionality.

## Jumio Support

The Jumio development team is constantly striving to optimize the size of our frameworks while increasing functionality, to improve your KYC and to fight fraud. If you have any further questions, please reach out to our [support team](https://www.jumio.com/contact/support).

---

# Changelog

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/changelog

![Header Graphic](images/jumio_feature_graphic.jpg)

[Improvement]: https://img.shields.io/badge/Improvement-green 'Improvement shield'
[Change]: https://img.shields.io/badge/Change-blue 'Change shield'
[Fix]: https://img.shields.io/badge/Fix-success 'Fix shield'

# Change Log

All notable changes, such as SDK releases, updates and fixes, are documented in this file.
For detailed technical changes please refer to our [Transition Guide](transition_guide.md).

## Support Period

Current SDK version: __4.18.0__  
Please refer to our [SDK maintenance and support policy](maintenance_policy.md) for more information about Mobile SDK maintenance and support.

## SDK Version: 4.18.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Global Digital ID Acceptance

![Improvement](https://img.shields.io/badge/Improvement-green) Added controls for limiting and preventing Manual Capture (ID and Selfie)

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for localized default consent links

## SDK Version: 4.17.2

![Fix](https://img.shields.io/badge/Fix-success) Readded CFBundleShortVersionString to JumioLivenessClient.xcframework

## SDK Version: 4.17.1

![Fix](https://img.shields.io/badge/Fix-success) x86_64 simulator crash fix

## SDK Version: 4.17.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for the Selfie.Done workflow

![Improvement](https://img.shields.io/badge/Improvement-green) Redesigned loading screens

## SDK Version: 4.16.0

![Improvement](https://img.shields.io/badge/Improvement-green) Redesign of the ID Autocapture user experience

![Improvement](https://img.shields.io/badge/Improvement-green) Support for image upload for DocProof workflows

![Improvement](https://img.shields.io/badge/Improvement-green) Support for Liveness capture using back camera

![Improvement](https://img.shields.io/badge/Improvement-green) Added separate NFC package

## SDK Version: 4.15.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for NFC read-only scanning.

![Improvement](https://img.shields.io/badge/Improvement-green) Introduced a configurable max retry count for NFC scanning.

![Improvement](https://img.shields.io/badge/Improvement-green) Included NFC scanning result status in transaction details via the Retrieval API.

![Improvement](https://img.shields.io/badge/Improvement-green) Enhanced user experience for NFC scanning with automatic NFC chip location detection.

## SDK Version: 4.14.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added enhanced virtual camera injection detection [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Accessibility updates for compliance with WCAG 2.2 AA and EAA

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Digital Identity using eIDAS for selected countries [ID Verification]

## SDK Version: 4.13.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for NFC extraction of Chilean IDs

![Fix](https://img.shields.io/badge/Fix-success) Various bug fixes and improvements

## SDK Version: 4.12.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Jumio Liveness Premium with enhanced deepfake detection [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added support for Brazilian Digital Driver's License [ID Verification]

## SDK Version: 4.11.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Datadog from default podspec [ID Verification, Selfie Verification, Document Verification]

## SDK Version: 4.11.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added tilted image capture for frontside of ID documents. Enhanced checks of certain document security features [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added unsupported documents check to improve quality of extracted data and improve user experience [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added an Updated Authentication Service [Selfie Verification]

## SDK Version: 4.10.1

![Fix](https://img.shields.io/badge/Fix-success) Removed Datadog from default podspec [ID Verification, Selfie Verification, Document Verification]

## SDK Version: 4.10.0

![Improvement](https://img.shields.io/badge/Improvement-green) Support for 4k Image capture. Improved ML model input, enhanced image and fraud checks [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added flash capture for frontside of ID documents. Enhanced checks of certain document security features [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for Serbian language, for both Cyrillic and Latin [ID Verification, Selfie Verification, Document Verification]

## SDK Version: 4.9.1

![Fix](https://img.shields.io/badge/Fix-success) iOS 12 app startup crash fixed [ID Verification]

## SDK Version: 4.9.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added possibility to pre-load required ML models. For more information checkout the according section
in the [README](../README_iOS.md#ml-models) [ID Verification, Identity Verification]
![Improvement](https://img.shields.io/badge/Improvement-green) Automated document and country selection, powered by classifer ML model [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Major UI Redesign [ID Verification, Selfie Verification, Document Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved Liveness retry logic. Prepared for granular instant feedback, if configured accordingly [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 11.0.3 [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Default UI implementation moved to its own dynamic framework, see: [Transition Guide](transition_guide.md). [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Removed Device Risk module from SDK [Selfie Verification]

## SDK Version: 4.8.1

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 10.3.3 [Selfie Verification]

## SDK Version: 4.8.0

![Improvement](https://img.shields.io/badge/Improvement-green) Managing Liveness dependencies to help better conversion

## SDK Version: 4.7.1

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 10.3.3 [Selfie Verification]

## SDK Version: 4.7.0

![Improvement](https://img.shields.io/badge/Improvement-green) Datadog SDK version update to 2.0: Added possibility to have two Datadog instances at the same time. Added SPM and Carthage support for Datadog

![Change](https://img.shields.io/badge/Change-blue) Removed previous scanning functionalities, now all included in Autocatpure functionality [ID Verification]

![Change](https://img.shields.io/badge/Change-blue) Pod Jumio/DeviceRisk excluded from pod Jumio/All.

![Change](https://img.shields.io/badge/Change-blue) MRZ functionality moved to Jumio core.

![Change](https://img.shields.io/badge/Change-blue) Barcode functionality was moved to Jumio core.

## SDK Version: 4.6.2

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 10.3.3 [Selfie Verification]

## SDK Version: 4.6.1

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 10.3.1 [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added Apple Privacy Manifest

![Change](https://img.shields.io/badge/Change-blue) Pod Jumio/DeviceRisk was excluded from pod Jumio/All.

## SDK Version: 4.6.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added Jumio Liveness module to enhance the Liveness user experience and interface [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved Liveness customization options [Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) Dependency name for iProov liveness was changed, see: [Transition Guide](transition_guide.md). [Selfie Verification]

## SDK Version: 4.5.0

![Improvement](https://img.shields.io/badge/Improvement-green) Added possibility for users to verify their identity using [Digital Identity](../README_iOS.md#digital-identity) [ID Verification, Identity Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) iProov SDK version update to 10.1.3 [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved user consent handling in accordance with biometric data protection laws [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improvement Added Carthage as new option for dependency manager

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs [ID Verification]

<details>
<summary>More details</summary>

### User consent

User consent is now acquired for all users to ensure the accordance with biometric data protection laws. Please also refer to the [User Consent section](integration_faq.md#user-consent) in our FAQ.

</details>

## SDK Version: 4.4.0

![Improvement](https://img.shields.io/badge/Improvement-green) Fully redesigned ID Autocapture experience - seamless capturing, precise guidance and faster user journey [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Major iProov SDK version update to 10.1.0 - no more face scanning filter, improved UI and more customization options [Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Mandatory NFC scanning option [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Added iOS 11+ Simulator and M1 (Apple silicon) support

![Improvement](https://img.shields.io/badge/Improvement-green) Added Swift Package Manager (SPM) as new option for dependency manager

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, internal crashes

<details>
<summary>More details</summary>

### Autocapture

The new Autocapture experience allows users to capture multiple images within a single camera session. For example the user can be guided to first capture the front of a document, then flip the document and capture the back of a document.

Please also refer to the [Autocapture section](integration_faq.md#autocapture) in our FAQ.

### iOS Simulator

The Jumio SDK is now buildable with all Simulator iOS versions, but to really perform a scan you still need to use a physical device.

</details>

## SDK Version: 4.3.1

![Fix](https://img.shields.io/badge/Fix-success) Fixed camera focus issue with iPhone 14 Pro

## SDK Version: 4.3.0

![Improvement](https://img.shields.io/badge/Improvement-green) Alignment of previously existing scanning method and improved user experience through addition of Autocapture module [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) [Document Verification](../README_iOS.md#document-verification) functionality added
![Improvement](https://img.shields.io/badge/Improvement-green) Improved user guidance: Clear distinction between scanning frontside or backside of ID document [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Addition of optional Datadog diagnostics module for monitoring SDK behavior and performance, as well as more efficient troubleshooting

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 9.5.0 [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) UI bugs, internal crashes [Selfie Verification]

## SDK Version: 4.2.0

![Improvement](https://img.shields.io/badge/Improvement-green) Support for device fingerprint capability [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved NFC image extraction, it's now possible to extract selfie for similarity check [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Improved liveness customization: Centered Floating prompt for better user guidance during face scanning [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, internal crashes, security patches

## SDK Version: 4.1.2

![Fix](https://img.shields.io/badge/Fix-success) Fixed NFC library handling

## SDK Version: 4.1.1

![Improvement](https://img.shields.io/badge/Improvement-green) Improved customization options [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Support for ObjectiveC for DefaultUI [ID Verification, Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 9.3.2 [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs

## SDK Version: 4.1.0

![Improvement](https://img.shields.io/badge/Improvement-green) Improved, granular user feedback for improved user experience and workflow through addition of Instant Feedback [ID Verification, Selfie Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Addition of NFC functionality to improve data extraction for documents [ID Verification]

![Improvement](https://img.shields.io/badge/Improvement-green) Addition of iPad support [ID Verification, Selfie Verification]

![Change](https://img.shields.io/badge/Change-blue) iProov SDK version update to 9.2.0 [Selfie Verification]

![Fix](https://img.shields.io/badge/Fix-success) Bug fixes: UI bugs, security improvements, internal crashes

## SDK Version: 4.0.0

This is a complete rewrite of our SDK. The SDK was built with Custom UI as a basis and restructured to align Android and iOS to reduce overall complexity and integration effort.

![Improvement](https://img.shields.io/badge/Improvement-green) Improved security by switching to one-time authorization tokens for SDK initialization instead of relying on API token and secret

![Improvement](https://img.shields.io/badge/Improvement-green) Redesigned Default UI flow

![Improvement](https://img.shields.io/badge/Improvement-green) Slimline SDK configuration of only 2.8 MB size

![Improvement](https://img.shields.io/badge/Improvement-green) Improved data extraction via enhancing the SDK capabilities with server-side extraction capabilities

![Improvement](https://img.shields.io/badge/Improvement-green) Manual capture is now available as a fallback option for all other capture methods

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. [Check it out at here.](https://support.jumio.com).

---

# Maintenance Policy

https://documentation.jumio.ai/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/docs/maintenance_policy

![Header Graphic](images/jumio_feature_graphic.jpg)

# Maintenance and Support Policy

## Overview

This document outlines the maintenance policy for Jumio’s Software Development Kits (“SDKs”), including Mobile and Web SDK and their dependencies.
Our SDK releases are published publicly as indicated in our documentation as well as to package managers. Documentation and sample implementations are available as source code on GitHub ([Android](https://github.com/Jumio/mobile-sdk-android) and [iOS](https://github.com/Jumio/mobile-sdk-ios)).

We are consistently updating the Jumio SDKs in order to provide the best possible experience for you. Upgrading to the latest SDK version will not only ensure you benefit from various performance enhancements and bug fixes, but will also allow you to take advantage of new capabilities. All releases undergo comprehensive testing by our teams before being deployed.

If you are using a Mobile SDK, please ensure your apps have been released and your end-users have updated before the End-of-Support date. Jumio does not provide support after the End-of-Support date.

Customers should review the [Jumio Terms and Conditions](https://www.jumio.com/legal-information/privacy-notices/) for requirements related to the implementation of updates.

## Versioning

Jumio SDK release versions are in the form of X.Y.Z:

- X major version - very rarely updated
- Y minor version - normally updated once in a quarter
- Z patch version - updated on demand

Major versions of Jumio’s SDKs are released rarely, and only in case of substantial changes to support new features and patterns. Breaking changes can happen in Major and Minor versions. Applications need to be updated in order for them to work with the newest SDK version. Breaking changes are highlighted in our [Android](https://github.com/Jumio/mobile-sdk-android) and [iOS](https://github.com/Jumio/mobile-sdk-ios) implementation guides for each release.

Jumio will only provide patches or additional updates on the latest version regardless if it’s Major, Minor or Patch.

## SDK Version Lifecycle

The life-cycle for SDK versions consists of these phases, which are outlined below:

- **Developer Preview** (Phase 0) - During this phase, SDKs are not supported, must not be used in production environments, and are meant for early access and feedback purposes only. It is possible for future releases to introduce breaking changes. It can be alpha, beta, or release candidate.
- **General availability / Full support** (Phase 1) - During this phase, SDKs are fully supported. Jumio will provide active support on this version and will provide required bug fixes or security fixes within new / upcoming versions (major, minor, patch).
- **End-of-Support** (Phase 2) - Each SDK version reaches end of support 9 months after the release date. Issues that appear after the End-of-Support date will only be addressed in the upcoming SDK releases. Previously published releases will continue to be available via public package managers and the code will remain on GitHub. Use of an SDK that has reached End-of-Support is done at the business customers’ discretion. We recommend upgrading to the latest version.
- **End-of-Life** (Phase 3) - By default, our SDK will reach the end of life 24 months after the release date. The SDK may continue to work but Jumio will no longer provide support or updates. Customers will be notified at least 3 months prior to the end of life of a product should it be less than 24 months.

The following table is a visual representation of the SDK 4.x.x version life-cycle. SDK 3.x.x has reached its End-of-Life on December 31, 2023.

| Version |      Release      |  End of Support   |    End of Life    |
| :-----: | :---------------: | :---------------: | :---------------: |
| 4.18.0  |   10 July 2026    |   10 April 2027   |   10 July 2028    |
| 4.17.2  |    19 May 2026    | 16 December 2026  |   16 March 2028   |
| 4.17.1  |   30 April 2026   | 16 December 2026  |   16 March 2028   |
| 4.17.0  |   16 March 2026   | 16 December 2026  |   16 March 2028   |
| 4.16.0  | 10 February 2026  | 10 November 2026  | 10 February 2028  |
| 4.15.0  |  10 October 2025  |   10 July 2026    |  10 October 2027  |
| 4.14.0  | 03 September 2025 |   03 June 2026    | 03 September 2027 |
| 4.13.0  |   04 April 2025   |  04 January 2026  |   04 April 2027   |
| 4.12.0  | 05 December 2024  | 05 September 2025 | 05 December 2026  |
| 4.11.0  |  19 August 2024   |    19 May 2025    |  19 August 2026   |
| 4.10.0  |   05 June 2024    |   5 March 2025    |    5 June 2026    |
|  4.9.1  |   13 March 2024   | 21 November 2024  | 21 February 2026  |
|  4.9.0  | 21 February 2024  | 21 November 2024  | 21 February 2026  |
|  4.8.0  |  17 October 2023  |   17 July 2024    |  17 October 2025  |
|  4.7.0  | 27 September 2023 |   27 June 2024    | 27 September 2025 |
|  4.6.1  | 05 September 2023 |   05 March 2024   |   05 June 2025    |
|  4.6.0  |   05 June 2023    |   05 March 2024   |   05 June 2025    |
|  4.5.0  |   14 April 2023   |  14 January 2024  |   14 April 2025   |
|  4.4.0  | 21 December 2022  | 21 September 2023 | 21 December 2024  |
|  4.3.1  |  25 October 2022  |    30 May 2023    |  30 August 2024   |
|  4.3.0  |  30 August 2022   |    30 May 2023    |  30 August 2024   |
|  4.2.0  |    25 May 2022    | 25 February 2023  |    25 May 2024    |
|  4.1.2  |   19 April 2022   | 09 December 2022  |   09 March 2024   |
|  4.1.1  |   04 April 2022   | 09 December 2022  |   09 March 2024   |
|  4.1.0  |   09 March 2022   | 09 December 2022  |   09 March 2024   |
|  4.0.0  | 16 November 2021  |  16 August 2022   | 16 November 2023  |

## Upgrade & Maintenance Practices

- Follow Semantic Versioning and test updates in staging.
- Monitor documentation (https://github.com/Jumio/mobile-sdk-ios/releases) for changes and depreciation notices.
- Perform regression testing after upgrades.

## Troubleshooting

- Enable debug logging in dev mode only:
  -- NetverifyConfiguration().debugMode = true
- Share workflowExecutionId, app version, OS, device, timestamp, and screenshots with support.

---

# Cross-Platform References

https://documentation.jumio.ai/docs/developer-resources/SDKs/crossplatform/CrossPlatform_Intro

# Cross-Platform Integration Overview

Jumio supports multiple cross-platform mobile frameworks to help developers integrate identity verification into hybrid or multi-platform apps. This page outlines the current level of support for the following,

- [React Native](../crossplatform/mobile-react-master/README_React)
- [Apache Cordova](../crossplatform/mobile-cordova-master/README_Cordova)
- [Flutter](../crossplatform/mobile-flutter-master/README_Flutter)

---

# Plugin for React Native

https://documentation.jumio.ai/docs/developer-resources/SDKs/crossplatform/mobile-react-master/README_React

# Plugin for React Native

Official Jumio Mobile SDK plugin for React Native

This plugin is compatible with version 4.13.0 of the Jumio SDK.  
If you have questions, please reach out to your Account Manager or contact [Jumio Support](https://www.jumio.com/contact/support/).

## Compatibility

We only ensure compatibility with a minimum React Native version of 0.79.1

## Recent Release

:::important

- **Learn about the latest releases [here](https://github.com/Jumio/mobile-react/releases)**.
- **To know more about the setup, click [here](https://github.com/Jumio/mobile-react)**.
  :::

## Setup

Create React Native project and add the Jumio Mobile SDK module to it, **learn [more](https://github.com/Jumio/mobile-react).**

```sh
react-native init MyProject
cd MyProject
npm install --save https://github.com/Jumio/mobile-react.git#v4.13.0
cd ios && pod install
```

## Integration

### iOS

1. Add the "**NSCameraUsageDescription**"-key to your Info.plist file.
2. Your app's deployment target must be at least iOS 13.0

#### NFC

Check out the [NFC setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#nfc-setup).

#### Digital Identity

Check out the [Digital Identity setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#digital-identity-setup).

#### Device Risk

To include Jumio's Device Risk functionality, you need to add `pod Jumio/DeviceRisk` to your Podfile.

### Android

**AndroidManifest**  
Open your AndroidManifest.xml file and change `allowBackup` to false.

````
```xml
<application
...
android:allowBackup="false">
</application>
````

````

Make sure your compileSdkVersion and buildToolsVersion are high enough.

```groovy
android {
  compileSdkVersion 33
  buildToolsVersion "33.0.0"
  ...
}
````

**Enable MultiDex**  
Follow the Android developers guide: https://developer.android.com/studio/build/multidex.html

```groovy
android {
  ...
  defaultConfig {
    ...
    multiDexEnabled true
  }
}
```

**Upgrade Gradle build tools**  
The plugin requires at least version 8.0.0 of the Android build tools. This transitively requires and upgrade of the Gradle wrapper to version 8 and an update to Java 11.

Upgrade build tools version to 8.7.3 in android/build.gradle:

```groovy
buildscript {
  ...
  dependencies {
    ...
    classpath 'com.android.tools.build:gradle:8.7.3'
  }
}
```

If necessary, modify the Gradle Wrapper version in android/gradle.wrapper/gradle-wrapper.properties:

```
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
```

**Repository**  
Add the Jumio Mobile SDK repository:

```groovy
exclusiveContent {
  forRepository {
    maven {
      url 'https://repo.mobile.jumio.ai'
    }
  }
  filter {
    includeGroup "com.jumio.android"
    includeGroup "com.iproov.sdk"
  }
}
```

#### Proguard

For information on Android Proguard Rules concerning the Jumio SDK, please refer to our [Android guides](https://github.com/Jumio/mobile-sdk-android#proguard).

## Usage

1. Add **"NativeModules"** to the import of 'react-native'.

```javascript
import {
  ...
  NativeModules
} from 'react-native';
```

2. Create a variable of your iOS module:

```javascript
const {JumioMobileSDK} = NativeModules;
```

3. The SDKs can be initialized with the following calls.

```javascript
`JumioMobileSDK.initialize(<AUTHORIZATION_TOKEN>, <DATACENTER>);`;
```

Datacenter can either be **US**, **EU** or **SG**.
For more information about how to obtain an `AUTHORIZATION_TOKEN`, please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/authorization).

As soon as the SDK is initialized, the SDK is started by the following call.

```javascript
JumioMobileSDK.start();
```

Optionally, it is possible to check whether a device is rooted / jailbroken with the following method:

```javascript
const isRooted = await JumioMobileSDK.isRooted();
```

### Retrieving information

You can listen to events to retrieve the scanned data:

- `EventResult` for Jumio results.
- `EventError` for Jumio error.

First add `NativeEventEmitter` to the import from 'react-native' and listen to the events.

```javascript
import {
...
NativeEventEmitter
} from 'react-native';
```

The event receives a JSON object with all the data.
The example below shows how to retrieve the information of each emitter as a String:

```javascript
const emitterJumio = new NativeEventEmitter(JumioMobileSDK);
emitterJumio.addListener('EventResult', EventResult => console.warn('EventResult: ' + JSON.stringify(EventResult)));
emitterJumio.addListener('EventError', EventError => console.warn('EventError: ' + JSON.stringify(EventError)));
```

## Customization

### Android

JumioSDK Android appearance can be customized by overriding the custom theme `AppThemeCustomJumio`. A customization example of all values can be found in the [`styles.xml`](DemoApp/android/app/src/main/res/values/styles.xml) of the DemoApp.

### iOS

JumioSDK iOS appearance can be customized to your respective needs. You can customize each color based on the device's set appearance, for either Dark mode or Light mode, or you can set a single color for both appearances. Customization is optional and not required.

You can pass the following customization options to the [`setupCustomizations()`](DemoApp/index.js#L30) function:

| Customization key                               |
| :---------------------------------------------- |
| facePrimary                                     |
| faceSecondary                                   |
| faceOutline                                     |
| faceAnimationForeground                         |
| iProovFilterForegroundColor                     |
| iProovFilterBackgroundColor                     |
| iProovTitleTextColor                            |
| iProovCloseButtonTintColor                      |
| iProovSurroundColor                             |
| iProovPromptTextColor                           |
| iProovPromptBackgroundColor                     |
| genuinePresenceAssuranceReadyOvalStrokeColor    |
| genuinePresenceAssuranceNotReadyOvalStrokeColor |
| livenessAssuranceOvalStrokeColor                |
| livenessAssuranceCompletedOvalStrokeColor       |
| primaryButtonBackground                         |
| primaryButtonBackgroundPressed                  |
| primaryButtonBackgroundDisabled                 |
| primaryButtonForeground                         |
| primaryButtonForegroundPressed                  |
| primaryButtonForegroundDisabled                 |
| primaryButtonOutline                            |
| secondaryButtonBackground                       |
| secondaryButtonBackgroundPressed                |
| secondaryButtonBackgroundDisabled               |
| secondaryButtonForeground                       |
| secondaryButtonForegroundPressed                |
| secondaryButtonForegroundDisabled               |
| secondaryButtonOutline                          |
| bubbleBackground                                |
| bubbleForeground                                |
| bubbleBackgroundSelected                        |
| bubbleOutline                                   |
| loadingCirclePlain                              |
| loadingCircleGradientStart                      |
| loadingCircleGradientEnd                        |
| loadingErrorCircleGradientStart                 |
| loadingErrorCircleGradientEnd                   |
| loadingCircleIcon                               |
| scanOverlay                                     |
| scanOverlayBackground                           |
| nfcPassportCover                                |
| nfcPassportPageDark                             |
| nfcPassportPageLight                            |
| nfcPassportForeground                           |
| nfcPhoneCover                                   |
| scanViewTooltipForeground                       |
| scanViewTooltipBackground                       |
| scanViewForeground                              |
| scanViewDocumentShutter                         |
| scanViewFaceShutter                             |
| searchBubbleBackground                          |
| searchBubbleForeground                          |
| searchBubbleOutline                             |
| confirmationImageBackground                     |
| confirmationImageBackgroundBorder               |
| confirmationIndicatorActive                     |
| confirmationIndicatorDefault                    |
| confirmationImageBorder                         |
| background                                      |
| navigationIconColor                             |
| textForegroundColor                             |
| primaryColor                                    |
| selectionIconForeground                         |

All colors are provided with a HEX string in the following formats: `#ff00ff` or `#66ff00ff` if you want to set the alpha level.

**Customization example**

Example for setting color based on Dark or Light mode:

```
JumioMobileSDK.setupCustomizations({
    primaryColor: { light:"ffffff", dark:"000000" }
    primaryButtonBackground: { light:ffffff, dark:"000000" }
});
```

Example for setting same color for both Dark and Light mode:

```
JumioMobileSDK.setupCustomizations({
    primaryColor: "ffffff"
    primaryButtonBackground: "ffffff"
});
```

## Configuration

For more information about how to set specific SDK parameters (callbackUrl, userReference, country, ...), please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/).

## Callbacks

In oder to get information about result fields, Retrieval API, Delete API, global settings and more, please read our [page with server related information](https://jumio.github.io/kyx/integration-guide.html#callback).

## Result Objects

The JSON object with all the extracted data that is returned for the specific products is described in the following subchapters:

### EventResult

| Parameter               | Type     | Max. length | Description                                                                                                |
| :---------------------- | :------- | :---------- | :--------------------------------------------------------------------------------------------------------- |
| selectedCountry         | String   | 3           | [ISO 3166-1 alpha-3](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code as provided or selected |
| selectedDocumentType    | String   | 16          | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA                                                            |
| selectedDocumentSubType | String   |             | Sub type of the scanned ID                                                                                 |
| idNumber                | String   | 100         | Identification number of the document                                                                      |
| personalNumber          | String   |             | Personal number of the document                                                                            |
| issuingDate             | Date     |             | Date of issue                                                                                              |
| expiryDate              | Date     |             | Date of expiry                                                                                             |
| issuingCountry          | String   | 3           | Country of issue as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code  |
| lastName                | String   | 100         | Last name of the customer                                                                                  |
| firstName               | String   | 100         | First name of the customer                                                                                 |
| dob                     | Date     |             | Date of birth                                                                                              |
| gender                  | String   | 1           | m, f or x                                                                                                  |
| originatingCountry      | String   | 3           | Country of origin as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code |
| addressLine             | String   | 64          | Street name                                                                                                |
| city                    | String   | 64          | City                                                                                                       |
| subdivision             | String   | 3           | Last three characters of [ISO 3166-2:US](http://en.wikipedia.org/wiki/ISO_3166-2:US) state code            |
| postCode                | String   | 15          | Postal code                                                                                                |
| mrzData                 | MRZ-DATA |             | MRZ data, see table below                                                                                  |
| optionalData1           | String   | 50          | Optional field of MRZ line 1                                                                               |
| optionalData2           | String   | 50          | Optional field of MRZ line 2                                                                               |
| placeOfBirth            | String   | 255         | Place of Birth                                                                                             |

### MRZ-Data

| Parameter           | Type   | Max. length | Description                                                                    |
| :------------------ | :----- | :---------- | :----------------------------------------------------------------------------- |
| format              | String | 8           | MRP, TD1, TD2, CNIS, MRVA, MRVB or UNKNOWN                                     |
| line1               | String | 50          | MRZ line 1                                                                     |
| line2               | String | 50          | MRZ line 2                                                                     |
| line3               | String | 50          | MRZ line 3                                                                     |
| idNumberValid       | BOOL   |             | True if ID number check digit is valid, otherwise false                        |
| dobValid            | BOOL   |             | True if date of birth check digit is valid, otherwise false                    |
| expiryDateValid     | BOOL   |             | True if date of expiry check digit is valid or not available, otherwise false  |
| personalNumberValid | BOOL   |             | True if personal number check digit is valid or not available, otherwise false |
| compositeValid      | BOOL   |             | True if composite check digit is valid, otherwise false                        |

## Local Models for ID Verification and Liveness

Our SDK requires several machine learning models to work best. We recommend to download the files and add them to your project without changing their names (the same way you add Localization files). This will save two network requests on runtime to download these files.

### Preloading models

You can preload the ML models before initializing the Jumio SDK. To do so set the completion block with `JumioMobileSDK.setPreloaderFinishedBlock` and start the preloading with `JumioMobileSDK.preloadIfNeeded`.

### iOS

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You also need to copy those files to the "ios/Assets" folder for React to recognize them.

### Android

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You need to copy those files to the assets folder of your Android project (Path: "app/src/main/assets/").

## FAQ

### Face help animation breaks on Android

If face help animation looks as expected in debug builds, but breaks in release builds, please make sure to include the following rule in your [**Proguard** file](DemoApp/android/app/proguard-rules.pro):

```
`-keep class androidx.constraintlayout.motion.widget.** { *; }`
```

### iOS Simulator shows a white-screen, when the Jumio SDK is started

The Jumio SDK does not support the iOS Simulator. Please run the Jumio SDK only on physical devices.

### iOS Runs on Debug, Crashes on Release Build

This happens due to Xcode 13 introducing a new option to their **App Store Distribution Options**:

**"Manage Version and Build Number"** (see image below)

If checked, this option changes the version and build number of all content of your app to the overall application version, including third-party frameworks. **This option is enabled by default.** Please make sure to disable this option when archiving / exporting your application to the App Store. Otherwise, the Jumio SDK version check, which ensures all bundled frameworks are up to date, will fail.

![Xcode13 Issue](images/known_issues_xcode13.png)

Alternatively, it is also possible to set the key `manageAppVersionAndBuildNumber` in the **exportOptions.plist** to `false`:

```
`<key>manageAppVersionAndBuildNumber</key>`
`<false/>`
```

### Using iOS Dynamic Frameworks with React Native Sample App

Jumio SDK version 3.8.0 and newer use iProov dependencies that need need to be built as dynamic frameworks.
Since React Native supports only static libraries, a pre-install hook has been added to ensure that pods added as `dynamic_frameworks` are actually built as dynamic frameworks, while all other pods are built as static libraries.

```
pre_install do |installer|
  installer.pod_targets.each do |pod|
    puts "Overriding the static_framework? method for #{pod.name}"
    def pod.static_framework?;
      true
    end
    def pod.build_type;
      Pod::BuildType.static_library
    end
  end
end
```

Additionally, a post install hook needs to be added to the Podfile to ensure dependencies are build for distribution:

```
post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['iProov', 'DatadogRUM', 'DatadogCore', 'DatadogInternal'].include? target.name
        target.build_configurations.each do |config|
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
end
```

### iOS Crashes on Start with Xcode 15

If you are working with Xcode 15 and above, please make sure the following lines have been added to your `Podfile`:

```
post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['iProov', 'DatadogRUM', 'DatadogCore', 'DatadogInternal'].include? target.name
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
        end
      end
    end
end
```

Please refer to the iOS section of our [DemoApp guide](DemoApp/README.md#iOS) for additional details.

### iOS Build Fails for React 0.71.2

`use_frameworks!` needs to be included in the `Podfile` and properly executed in order for Jumio dynamic frameworks to install correctly.
Make sure [the necessary `pre_install` and `post_install` hooks](#using-ios-dynamic-frameworks-with-react-native-sample-app) have been included.
Also make sure that [Flipper](https://fbflipper.com/) is disabled for your project, since Flipper is not compatible with iOS dynamic frameworks at the moment.

Please also refer to the [Podfile](DemoApp/ios/Podfile) of our sample application for further details.

### iOS Localization

After installing Cocoapods, please localize your iOS application using the languages provided at the following path:  
`ios -> Pods -> Jumio -> Localization -> xx.lproj`

![Localization](images/RN_localization.gif)

Make sure your `Podfile` is up to date and that new pod versions are installed properly so your `Localizable` files include new strings.
For more information, please refer to our [Changelog](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/changelog.md) and [Transition Guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/transition_guide.md).

# Support

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com or https://support.jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. Check it out at: https://support.jumio.com.

---

# Plugin for Apache Cordova

https://documentation.jumio.ai/docs/developer-resources/SDKs/crossplatform/mobile-cordova-master/README_Cordova

# Plugin for Apache Cordova

Official Jumio Mobile SDK plugin for Apache Cordova

This plugin is compatible with version 4.13.0 of the Jumio SDK.
If you have questions, please reach out to your Account Manager or contact [Jumio Support](https://www.jumio.com/contact/support/).

## Compatibility

With this release, we only ensure compatibility with the latest Cordova versions and plugins.
At the time of this release, the following minimum versions are supported:

- Cordova: 12.0.0
- Cordova Android: 14.0.0
- Cordova iOS: 7.1.1

## Recent Release

:::important

- **Learn about the latest releases [here](https://github.com/Jumio/mobile-cordova/releases)**.
- **To know more about the setup, click [here](https://github.com/Jumio/mobile-react)**.
  :::

## Setup

Create Cordova project and add our plugin, **learn [more](https://github.com/Jumio/mobile-react)**.

```
cordova create MyProject com.my.project "MyProject"
cd MyProject
cordova platform add ios
cordova platform add android
cordova plugin add https://github.com/Jumio/mobile-cordova.git#v4.13.0
cd platforms/ios && pod install
```

## Integration

### iOS

Manual integration or dependency management via cocoapods possible, please see [the official documentation of the Jumio Mobile SDK for iOS](https://github.com/Jumio/mobile-sdk-ios/tree/master#basics)

#### NFC

Check out the [NFC setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#nfc-setup).

#### Digital Identity

Check out the [Digital Identity setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#digital-identity-setup).

#### Device Risk

To include Jumio's Device Risk functionality, you need to add `pod Jumio/DeviceRisk` to your Podfile.

### Android

Add required permissions for the products as described in chapter [Permissions](https://github.com/Jumio/mobile-sdk-android/blob/master/README.md#permissions)

To use the native Jumio Android component, your App needs to support AndroidX. This can be enabled by adding the following preference to your config.xml:

```xml
<preference name="AndroidXEnabled" value="true" />
```

**Upgrade Gradle build tools**  
The plugin requires at least version 8.0.0 of the Android build tools. This transitively requires an upgrade of the Gradle wrapper to version 8 and an update to Java 11.

If necessary, modify the Gradle Wrapper version in `android/gradle.wrapper/gradle-wrapper.properties`:

```groovy
...
distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
```

#### Proguard

For information on Android Proguard Rules concerning the Jumio SDK, please refer to our [Android Guides](https://github.com/Jumio/mobile-sdk-android#proguard).

For other build issues, refer to the The [FAQ section](#faq) at the bottom.

## Usage

1. To initialize the SDK, perform the following call.

```javascript
Jumio.initialize(<AUTHORIZATION_TOKEN>, <DATACENTER>);
```

Datacenter can either be **US**, **EU** or **SG**.

For more information about how to obtain an AUTHORIZATION_TOKEN, please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/authorization).

2. As soon as the SDK is initialized, the sdk is started by the following call.

```javascript
Jumio.start(successCallback, errorCallback);
```

## Customization

### Android

The JumioSDK colors can be customized by overriding the custom theme `AppThemeCustomJumio`. The styles-file for Android is automatically copied to your app by the rule in the `plugin.xml`. An example customization of all values that can be found in the [jumio-styles.xml of the plugin](src/android/res/values/jumio-styles.xml)

### iOS

JumioSDK iOS appearance can be customized to your respective needs. You can customize each color based on the device's set appearance, for either Dark mode or Light mode, or you can set a single color for both appearances. Customization is optional and not required.

You can pass the following customization options at [`Jumio.start`](demo/www/js/index.js#L40):

| Customization key                               |
| :---------------------------------------------- |
| facePrimary                                     |
| faceSecondary                                   |
| faceOutline                                     |
| faceAnimationForeground                         |
| iProovFilterForegroundColor                     |
| iProovFilterBackgroundColor                     |
| iProovTitleTextColor                            |
| iProovCloseButtonTintColor                      |
| iProovSurroundColor                             |
| iProovPromptTextColor                           |
| iProovPromptBackgroundColor                     |
| genuinePresenceAssuranceReadyOvalStrokeColor    |
| genuinePresenceAssuranceNotReadyOvalStrokeColor |
| livenessAssuranceOvalStrokeColor                |
| livenessAssuranceCompletedOvalStrokeColor       |
| primaryButtonBackground                         |
| primaryButtonBackgroundPressed                  |
| primaryButtonBackgroundDisabled                 |
| primaryButtonForeground                         |
| primaryButtonForegroundPressed                  |
| primaryButtonForegroundDisabled                 |
| primaryButtonOutline                            |
| secondaryButtonBackground                       |
| secondaryButtonBackgroundPressed                |
| secondaryButtonBackgroundDisabled               |
| secondaryButtonForeground                       |
| secondaryButtonForegroundPressed                |
| secondaryButtonForegroundDisabled               |
| secondaryButtonOutline                          |
| bubbleBackground                                |
| bubbleForeground                                |
| bubbleBackgroundSelected                        |
| bubbleOutline                                   |
| loadingCirclePlain                              |
| loadingCircleGradientStart                      |
| loadingCircleGradientEnd                        |
| loadingErrorCircleGradientStart                 |
| loadingErrorCircleGradientEnd                   |
| loadingCircleIcon                               |
| scanOverlay                                     |
| scanOverlayBackground                           |
| nfcPassportCover                                |
| nfcPassportPageDark                             |
| nfcPassportPageLight                            |
| nfcPassportForeground                           |
| nfcPhoneCover                                   |
| scanViewTooltipForeground                       |
| scanViewTooltipBackground                       |
| scanViewForeground                              |
| scanViewDocumentShutter                         |
| scanViewFaceShutter                             |
| searchBubbleBackground                          |
| searchBubbleForeground                          |
| searchBubbleOutline                             |
| confirmationImageBackground                     |
| confirmationImageBackgroundBorder               |
| confirmationIndicatorActive                     |
| confirmationIndicatorDefault                    |
| confirmationImageBorder                         |
| background                                      |
| navigationIconColor                             |
| textForegroundColor                             |
| primaryColor                                    |
| selectionIconForeground                         |

All colors are provided with a HEX string with the following formats: `#ff00ff` or `#66ff00ff` if you want to set the alpha level.

**Customization example**

Example for setting color based on Dark or Light mode

```
Jumio.start(successCallback, errorCallback, {
    primaryColor: { light:"ffffff", dark:"000000" }
    primaryButtonBackground: { light:ffffff, dark:"000000" }
});
```

Example for setting same color for both Dark and Light mode

```
Jumio.start(successCallback, errorCallback, {
    primaryColor: "ffffff"
    primaryButtonBackground: "ffffff"
});
```

## Configuration

For more information about how to set specific SDK parameters (callbackUrl, userReference, country, ...), please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/).

## Callback

To get information about callbacks, Netverify Retrieval API, Netverify Delete API and Global Netverify settings and more, please read our [page with server related information](https://documentation.jumio.ai/docs/developer-resources/callback).

## Result Objects

JumioSDK will return a JSONObject `documentData` with all extracted data in case of a successfully completed workflow and `error` in case of error. An error object always includes an error code and an error message.

### Result

| Parameter               | Type     | Max. length | Description                                                                                                |
| :---------------------- | :------- | :---------- | :--------------------------------------------------------------------------------------------------------- |
| selectedCountry         | String   | 3           | [ISO 3166-1 alpha-3](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code as provided or selected |
| selectedDocumentType    | String   | 16          | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA                                                            |
| selectedDocumentSubType | String   |             | Sub type of the scanned ID                                                                                 |
| idNumber                | String   | 100         | Identification number of the document                                                                      |
| personalNumber          | String   | 14          | Personal number of the document                                                                            |
| issuingDate             | Date     |             | Date of issue                                                                                              |
| expiryDate              | Date     |             | Date of expiry                                                                                             |
| issuingCountry          | String   | 3           | Country of issue as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code  |
| lastName                | String   | 100         | Last name of the customer                                                                                  |
| firstName               | String   | 100         | First name of the customer                                                                                 |
| dob                     | Date     |             | Date of birth                                                                                              |
| gender                  | String   | 1           | m, f or x                                                                                                  |
| originatingCountry      | String   | 3           | Country of origin as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code |
| addressLine             | String   | 64          | Street name                                                                                                |
| city                    | String   | 64          | City                                                                                                       |
| subdivision             | String   | 3           | Last three characters of [ISO 3166-2:US](http://en.wikipedia.org/wiki/ISO_3166-2:US) state code            |
| postCode                | String   | 15          | Postal code                                                                                                |
| mrzData                 | MRZ-DATA |             | MRZ data, see table below                                                                                  |
| optionalData1           | String   | 50          | Optional field of MRZ line 1                                                                               |
| optionalData2           | String   | 50          | Optional field of MRZ line 2                                                                               |
| placeOfBirth            | String   | 255         | Place of Birth                                                                                             |

_MRZ-Data_

| Parameter           | Type   | Max. length | Description                                                                    |
| :------------------ | :----- | :---------- | :----------------------------------------------------------------------------- |
| format              | String | 8           | MRP, TD1, TD2, CNIS, MRVA, MRVB or UNKNOWN                                     |
| line1               | String | 50          | MRZ line 1                                                                     |
| line2               | String | 50          | MRZ line 2                                                                     |
| line3               | String | 50          | MRZ line 3                                                                     |
| idNumberValid       | BOOL   |             | True if ID number check digit is valid, otherwise false                        |
| dobValid            | BOOL   |             | True if date of birth check digit is valid, otherwise false                    |
| expiryDateValid     | BOOL   |             | True if date of expiry check digit is valid or not available, otherwise false  |
| personalNumberValid | BOOL   |             | True if personal number check digit is valid or not available, otherwise false |
| compositeValid      | BOOL   |             | True if composite check digit is valid, otherwise false                        |

## Local Models for ID Verification and Liveness

Our SDK requires several machine learning models to work best. We recommend to download the files and add them to your project without changing their names (the same way you add Localization files). This will save two network requests on runtime to download these files.

### Preloading models

You can preload the ML models before initializing the Jumio SDK. To do so set the completion block with `JumioMobileSDK.setPreloaderFinishedBlock` and start the preloading with `JumioMobileSDK.preloadIfNeeded`.

### iOS

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You also need to copy those files to the "ios/Assets" folder for Cordova to recognize them.

### Android

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You need to copy those files to the assets folder of your Android project (Path: "app/src/main/assets/").

# FAQ

## Android Issues

This is a list of common **Android build issues** and how to resolve them:

- `AAPT: error: resource android:attr/lStar not found` is resolved [in this Stackoverflow post](https://stackoverflow.com/a/70492116/1297835)
- `Build-tool 32.0.0 is missing DX` (on Windows) - [in this Stackoverflow post](https://stackoverflow.com/a/68430992/1297835)
- Gradle plugin 4.X not supported, please install 5.X  
  --> Change the version in the `gradle-wrapper.properties` file

- Device-ready not fired after X seconds  
  --> The plugin definition in "YOURPROJECT/platforms/android/platform_www/plugins/cordova-plugin-jumio-mobilesdk/www" might be duplicated/corrupted due to the issue mentioned [in this Stackoverflow post](https://stackoverflow.com/questions/28017540/cordova-plugin-javascript-gets-corrupted-when-added-to-project/28264312#28264312). Please fix the duplicated `cordova.define()` call in these files as mentioned in the post.

## iOS Issues

### iOS Simulator Shows a White Screen when Jumio SDK Starts

The Jumio SDK does not support the iOS Simulator. Please run the Jumio SDK only on physical devices.

### iOS Runs on Debug, Crashes on Release Build

This happens due to Xcode 13 introducing a new option to their **App Store Distribution Options**:

**"Manage Version and Build Number"** (see image below)

If checked, this option changes the version and build number of all content of your app to the overall application version, including third-party frameworks. **This option is enabled by default.** Please make sure to disable this option when archiving / exporting your application to the App Store. Otherwise, the Jumio SDK version check, which ensures all bundled frameworks are up to date, will fail.

Alternatively, it is also possible to set the key `manageAppVersionAndBuildNumber` in the **exportOptions.plist** to `false`:

```
<key>manageAppVersionAndBuildNumber</key>
<false/>
```

### iOS Localization

After installing Cocoapods, please localize your iOS application using the languages provided at the following path:  
`ios -> Pods -> Jumio -> Localizations -> xx.lproj`

### Framework not found iProov.xcframework

If iOS application build is failing with `ld: framework not found iProov.xcframework` or `dyld: Symbol not found: ... Referenced from: /.../Frameworks/iProov.frameworks/iProov`, please make sure the necessary post install-hook has been included in your `Podfile`:

```
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
```

### Framework not found DatadogCore.xcframework

If iOS application build is failing with `ld: framework not found DatadogCore.xcframework` or `dyld: Symbol not found: ... Referenced from: /.../Frameworks/DatadogCore.frameworks/DatadogCore`, please make sure the necessary post install-hook has been included in your `Podfile`:

```
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
    end
  end
end
```

For more information, please refer to our [iOS guides](https://github.com/Jumio/mobile-sdk-ios#certified-liveness-vendor).

# Support

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com or https://support.jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. Check it out at: https://support.jumio.com.

---

# Plugin for Flutter

https://documentation.jumio.ai/docs/developer-resources/SDKs/crossplatform/mobile-flutter-master/README_Flutter

# Plugin for Flutter

Official Jumio Mobile SDK plugin for Flutter

This plugin is compatible with version 4.13.0 of the Jumio SDK.
If you have questions, please reach out to your Account Manager or contact [Jumio Support](https://www.jumio.com/contact/support/).

## Compatibility

Compatibility has been tested with a Flutter version of 3.29.3 and Dart 3.7.2

## Recent Release

:::important

- **Learn about the latest releases [here](https://github.com/Jumio/mobile-flutter/releases)**.
- **To know more about the setup, click [here](https://github.com/Jumio/mobile-flutter)**.
  :::

## Setup

Create Flutter project and add the Jumio Mobile SDK module to it.

```sh
flutter create MyProject
```

Add the Jumio Mobile SDK as a dependency to your `pubspec.yaml` file:

```yaml
dependencies:
  flutter:
    sdk: flutter

  jumio_mobile_sdk_flutter: ^4.13.0
```

And install the dependency:

```sh
cd MyProject
flutter pub get
cd ios && pod install
```

## Integration

### iOS

1. Add the "**NSCameraUsageDescription**"-key to your Info.plist file.
2. Your app's deployment target must be at least iOS 11.0

#### NFC

Check out the [NFC setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#nfc-setup).

#### Digital Identity

Check out the [Digital Identity setup guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#digital-identity-setup).

#### Device Risk

To include Jumio's Device Risk functionality, you need to add `pod Jumio/DeviceRisk` to your Podfile.

### Android

**AndroidManifest**  
Open your AndroidManifest.xml file and change `allowBackup` to false.

```xml
<application>
...
android:allowBackup="false">
</application>
...
```

Make sure your compileSdkVersion, minSdkVersion and buildToolsVersion are high enough.

```groovy
android {
  minSdkVersion 21
  compileSdkVersion 35
  buildToolsVersion "35.0.0"
  ...
}
```

**Enable MultiDex**  
Follow the Android developers guide [here](https://developer.android.com/studio/build/multidex.html)

```groovy
android {
  ...
  defaultConfig {
    ...
    multiDexEnabled true
  }
}
```

**Upgrade Gradle build tools**  
The plugin requires at least version 8.0.0 of the Android build tools. This transitively requires an upgrade of the Gradle wrapper to version 8 and an update to Java 11.

If necessary, upgrade your build tools version to 8.7.3 in `android/build.gradle`:

```groovy
buildscript {
  ...
  dependencies {
    ...
    classpath 'com.android.tools.build:gradle:8.7.3'
  }
}
```

If necessary, modify the Gradle Wrapper version in `android/gradle.wrapper/gradle-wrapper.properties`:

```groovy
...
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
```

#### Proguard

For information on Android Proguard Rules concerning the Jumio SDK, please refer to our [Android guides](https://github.com/Jumio/mobile-sdk-android#proguard).

To enable analytic feedback and internal diagnostics, please make sure to include the lines:

```
-keep class io.flutter.embedding.android.FlutterActivity
-keep class io.flutter.embedding.android.FlutterEngineProvider
```

to your Proguard Rules.

## Usage

1. Import "**jumiomobilesdk.dart**"

```dart
import 'package:jumio_mobile_sdk_flutter/jumio_mobile_sdk_flutter.dart';
```

2. The SDKs can be initialized with the following call:

```dart
Jumio.init("AUTHORIZATION_TOKEN", "DATACENTER");
```

Datacenter can either be **US**, **EU** or **SG**.  
For more information about how to obtain an `AUTHORIZATION_TOKEN`, please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/authorization).

3. As soon as the SDK is initialized, the SDK is started by the following call.

```dart
Jumio.start();
```

### Retrieving information

Scan results are returned from the startXXX() methods asynchronously. Await the returned values to get the results. Exceptions are thrown issues such as invalid credentials, missing API keys, permissions errors and such.

## Customization

### Android

JumioSDK Android appearance can be customized by overriding the custom theme `AppThemeCustomJumio`. An example customization of all values that can be found in the [styles.xml](example/android/app/src/main/res/values/styles.xml) of the DemoApp.

### iOS

JumioSDK iOS appearance can be customized to your respective needs. You can customize each color based on the device's set appearance, for either Dark mode or Light mode, or you can set a single color for both appearances. Customization is optional and not required.

You can pass the following customization options at [`Jumio.start`](example/lib/main.dart#L79):

| Customization key                               |
| :---------------------------------------------- |
| facePrimary                                     |
| faceSecondary                                   |
| faceOutline                                     |
| faceAnimationForeground                         |
| iProovFilterForegroundColor                     |
| iProovFilterBackgroundColor                     |
| iProovTitleTextColor                            |
| iProovCloseButtonTintColor                      |
| iProovSurroundColor                             |
| iProovPromptTextColor                           |
| iProovPromptBackgroundColor                     |
| genuinePresenceAssuranceReadyOvalStrokeColor    |
| genuinePresenceAssuranceNotReadyOvalStrokeColor |
| livenessAssuranceOvalStrokeColor                |
| livenessAssuranceCompletedOvalStrokeColor       |
| primaryButtonBackground                         |
| primaryButtonBackgroundPressed                  |
| primaryButtonBackgroundDisabled                 |
| primaryButtonForeground                         |
| primaryButtonForegroundPressed                  |
| primaryButtonForegroundDisabled                 |
| primaryButtonOutline                            |
| secondaryButtonBackground                       |
| secondaryButtonBackgroundPressed                |
| secondaryButtonBackgroundDisabled               |
| secondaryButtonForeground                       |
| secondaryButtonForegroundPressed                |
| secondaryButtonForegroundDisabled               |
| secondaryButtonOutline                          |
| bubbleBackground                                |
| bubbleForeground                                |
| bubbleBackgroundSelected                        |
| bubbleOutline                                   |
| loadingCirclePlain                              |
| loadingCircleGradientStart                      |
| loadingCircleGradientEnd                        |
| loadingErrorCircleGradientStart                 |
| loadingErrorCircleGradientEnd                   |
| loadingCircleIcon                               |
| scanOverlay                                     |
| scanOverlayBackground                           |
| nfcPassportCover                                |
| nfcPassportPageDark                             |
| nfcPassportPageLight                            |
| nfcPassportForeground                           |
| nfcPhoneCover                                   |
| scanViewTooltipForeground                       |
| scanViewTooltipBackground                       |
| scanViewForeground                              |
| scanViewDocumentShutter                         |
| scanViewFaceShutter                             |
| searchBubbleBackground                          |
| searchBubbleForeground                          |
| searchBubbleOutline                             |
| confirmationImageBackground                     |
| confirmationImageBackgroundBorder               |
| confirmationIndicatorActive                     |
| confirmationIndicatorDefault                    |
| confirmationImageBorder                         |
| background                                      |
| navigationIconColor                             |
| textForegroundColor                             |
| primaryColor                                    |
| selectionIconForeground                         |

All colors are provided with a HEX string with the following formats: `#ff00ff` or `#66ff00ff` if you want to set the alpha level.

**Customization example**

Example for setting color based on Dark or Light mode

```
Jumio.start({
    "primaryColor": { light:"ffffff", dark:"000000" }
    "primaryButtonBackground": { light:ffffff, dark:"000000" }
});
```

Example for setting same color for both Dark and Light mode

```
Jumio.start({
    "primaryColor": "ffffff"
    "primaryButtonBackground": "ffffff"
});
```

## Configuration

For more information about how to set specific SDK parameters (callbackUrl, userReference, country, ...), please refer to our [API Guide](https://documentation.jumio.ai/docs/developer-resources/API/).

## Callbacks

In oder to get information about result fields, Retrieval API, Delete API, global settings and more, please read our [page with server related information](https://documentation.jumio.ai/docs/developer-resources/callback).

## Result Objects

JumioSDK will return `EventResult` in case of a successfully completed workflow and `EventError` in case of error. `EventError` includes an error code and an error message.

### EventResult

| Parameter               | Type     | Max. length | Description                                                                                                |
| :---------------------- | :------- | :---------- | :--------------------------------------------------------------------------------------------------------- |
| selectedCountry         | String   | 3           | [ISO 3166-1 alpha-3](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code as provided or selected |
| selectedDocumentType    | String   | 16          | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA                                                            |
| selectedDocumentSubType | String   |             | Sub type of the scanned ID                                                                                 |
| idNumber                | String   | 100         | Identification number of the document                                                                      |
| personalNumber          | String   |             | Personal number of the document                                                                            |
| issuingDate             | Date     |             | Date of issue                                                                                              |
| expiryDate              | Date     |             | Date of expiry                                                                                             |
| issuingCountry          | String   | 3           | Country of issue as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code  |
| lastName                | String   | 100         | Last name of the customer                                                                                  |
| firstName               | String   | 100         | First name of the customer                                                                                 |
| dob                     | Date     |             | Date of birth                                                                                              |
| gender                  | String   | 1           | m, f or x                                                                                                  |
| originatingCountry      | String   | 3           | Country of origin as ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)) country code |
| addressLine             | String   | 64          | Street name                                                                                                |
| city                    | String   | 64          | City                                                                                                       |
| subdivision             | String   | 3           | Last three characters of [ISO 3166-2:US](http://en.wikipedia.org/wiki/ISO_3166-2:US) state code            |
| postCode                | String   | 15          | Postal code                                                                                                |
| mrzData                 | MRZ-DATA |             | MRZ data, see table below                                                                                  |
| optionalData1           | String   | 50          | Optional field of MRZ line 1                                                                               |
| optionalData2           | String   | 50          | Optional field of MRZ line 2                                                                               |
| placeOfBirth            | String   | 255         | Place of Birth                                                                                             |

### MRZ-Data

| Parameter           | Type   | Max. length | Description                                                                    |
| :------------------ | :----- | :---------- | :----------------------------------------------------------------------------- |
| format              | String | 8           | MRP, TD1, TD2, CNIS, MRVA, MRVB or UNKNOWN                                     |
| line1               | String | 50          | MRZ line 1                                                                     |
| line2               | String | 50          | MRZ line 2                                                                     |
| line3               | String | 50          | MRZ line 3                                                                     |
| idNumberValid       | BOOL   |             | True if ID number check digit is valid, otherwise false                        |
| dobValid            | BOOL   |             | True if date of birth check digit is valid, otherwise false                    |
| expiryDateValid     | BOOL   |             | True if date of expiry check digit is valid or not available, otherwise false  |
| personalNumberValid | BOOL   |             | True if personal number check digit is valid or not available, otherwise false |
| compositeValid      | BOOL   |             | True if composite check digit is valid, otherwise false                        |

## Local Models for ID Verification and Liveness

Our SDK requires several machine learning models to work best. We recommend to download the files and add them to your project without changing their names (the same way you add Localization files). This will save two network requests on runtime to download these files.

### Preloading models

You can preload the ML models before initializing the Jumio SDK. To do so set the completion block with `JumioMobileSDK.setPreloaderFinishedBlock` and start the preloading with `JumioMobileSDK.preloadIfNeeded`.

### iOS

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You also need to copy those files to the "ios/Assets" folder for Flutter to recognize them.

### Android

You can find the models in the [Bundling models in the app](https://github.com/Jumio/mobile-sdk-android/blob/master/docs/integration_guide.md#bundling-models-in-the-app) section of our integration guide.

You need to copy those files to the assets folder of your Android project (Path: "app/src/main/assets/").

## FAQ

### Face help animation breaks on Android

If face help animation looks as expected in debug builds, but breaks in release builds, please make sure to include the following rule in your [**Proguard** file](example/android/app/proguard-rules.pro):

```
-keep class androidx.constraintlayout.motion.widget.** { *; }
```

### iOS Simulator shows a white-screen, when the Jumio SDK is started

The Jumio SDK does not support the iOS Simulator. Please run the Jumio SDK only on physical devices.

### iOS Runs on Debug, Crashes on Release Build

This happens due to Xcode 13 introducing a new option to their **App Store Distribution Options**:

**"Manage Version and Build Number"** (see image below)

If checked, this option changes the version and build number of all content of your app to the overall application version, including third-party frameworks. **This option is enabled by default.** Please make sure to disable this option when archiving / exporting your application to the App Store. Otherwise, the Jumio SDK version check, which ensures all bundled frameworks are up to date, will fail.

![Xcode13 Issue](images/known_issues_xcode13.png)

Alternatively, it is also possible to set the key `manageAppVersionAndBuildNumber` in the **exportOptions.plist** to `false`:

```
<key>manageAppVersionAndBuildNumber</key>
<false/>
```

### App Crash at Launch for iOS

If iOS application crashes immediately after launch and without additional information, but works fine for Android, please make sure the following lines have been added to your `Podfile`:

```
post_install do |installer|
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
end
```

If you are working with Xcode 15 and above, please make sure the following lines have been added to your `Podfile`:

```
post_install do |installer|
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
    end
  end
end
```

Please refer to [iOS guide](https://github.com/Jumio/mobile-sdk-ios#via-cocoapods) for more details.

### iOS Localization

After installing Cocoapods, please localize your iOS application using the languages provided at the following path:  
`ios -> Pods -> Jumio -> Localization -> xx.lproj`

![Localization](images/Flutter_localization.gif)

Make sure your `podfile` is up to date and that new pod versions are installed properly so your `Localizable` files include new strings.
For more information, please refer to our [Changelog](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/changelog.md) and [Transition Guide](https://github.com/Jumio/mobile-sdk-ios/blob/master/docs/transition_guide.md).

### Empty Country List for Android Release Build

If country list is empty for the Android release build, please make sure your app has the proper internet permissions. Without a working network connection, countries won't load in and the list will stay empty.

If necessary, please add `android.permission.INTERNET` permission to your `AndroidManifest.xml` file.

The standard Flutter template will not include this tag automatically, but still allows Internet access during development to enable communication between Flutter tools and a running app. For more information, please refer to the [official Flutter documentation.](https://flutter.dev/docs/deployment/android#reviewing-the-app-manifest)

# Support

## Contact

If you have any questions regarding our implementation guide please contact Jumio Customer Service at support@jumio.com or https://support.jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. Check it out at: https://support.jumio.com.

## Licenses

The source code and software available on this website (“Software”) is provided by Jumio Corp. or its affiliated group companies (“Jumio”) "as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Jumio be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to procurement of substitute goods or services, loss of use, data, profits, or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this Software, even if advised of the possibility of such damage.

In any case, your use of this Software is subject to the terms and conditions that apply to your contractual relationship with Jumio. As regards Jumio’s privacy practices, please see our privacy notice available here: [Privacy Policy](https://www.jumio.com/legal-information/privacy-policy/).

The software contains third-party open source software. For more information, please see [Android licenses](https://github.com/Jumio/mobile-sdk-android/tree/master/licenses) and [iOS licenses](https://github.com/Jumio/mobile-sdk-ios/tree/master/licenses)

This software is based in part on the work of the Independent JPEG Group.

## Copyright

&copy; Jumio Corp. 268 Lambert Avenue, Palo Alto, CA 94306

---

# Web SDK

https://documentation.jumio.ai/docs/developer-resources/SDKs/web-sdk/introduction-web

# Getting Started with the Jumio Web SDK

The Jumio Web SDK lets you quickly integrate and customize a fully-functional implementation of the customer journeyClosed into your web and mobile applications. It provides a set of UI components that guide your end users through the verification process, including preparing and capturing the credentials required by the workflow specified in the account request. The components are implemented as custom html elements and named html templates that are managed by JavaScript resources packaged as [Ecmascript Modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules).

Adding the default integration to your application is as simple as adding a single `<jumio-sdk>` element to a page and passing it a couple of parameters:

```
<jumio-sdk dc="..." token="..."></jumio-sdk>
```

<ul>
<li> **dc** is the data center for your Jumio tenant. </li>
<li> **us** for the US data center</li>
<li> **eu** for the European data denter</li>
<li> **sgp** for the Singapore data center</li>
<li> **token** is the sdk.token value returned in the response from an account request. </li>
</ul>
See [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) and [Example: Default Integration](/docs/developer-resources/SDKs/web-sdk/introduction-web#example-default-integration)

:::tip

[Storybook Documentation](https://docs.web.jumio.ai/) provides detailed reference information, along with an interactive way to try out the default implementation.

:::

The following topics provide additional information and examples about **Web SDK**:

- [Installing the Package](#installing-the-web-sdk-package)

- [Slots](/docs/developer-resources/SDKs/web-sdk/slots) provides examples of high-level customizations including theme, logging, and browser navigation.

- [CSS Variables](/docs/developer-resources/SDKs/web-sdk/web-sdk-css) provides examples of customizing fonts and colors.

- [Templates](/docs/developer-resources/SDKs/web-sdk/web-sdk-templates) provides examples of using templates to customize the steps in the customer journey.

## Installing the Web SDK Package

The Web SDK is available as a NPM package. It is publicly available in the npm registry at [@jumio/websdk](https://www.npmjs.com/package/@jumio/websdk?activeTab=readme).

Install the package using this command:

```
npm i @jumio/websdk
```

The package includes a README.md file and an index.html file. The README.md contains additional information including how to launch a local server and access the index.html. The index.html is a minimal file that includes the `<jumio-sdk>` tag. You can try out the various slots and templates by adding them and seeing the results in a browser accessing the localhost server.

## Example: Default Integration

The following example shows:

- The index.html document that is included with the Web SDK package.

- A `<template id="setup">` element that provides the initial screen the end user accesses to start the transaction. In this simple example it just includes:

  - An `<h1>` element

  - A button that calls a JavaScript function

  - The JavaScript function that illustrates one way the SDK token might be acquired. This example assumes the existence of a server-side endpoint you have implemented that:

    - Obtains a Jumio API authorization token. See Authorization.

    - Initiates a transaction for a new or existing account. See Creating or Updating Accounts.

    - Returns the "sdk":"token" value from the account response, which is then used to set the jumioSDK token attribute.

```html title="/index.html"
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Jumio Sample App</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      html,
      body {
        height: 100%;
        padding: 12;
        margin: 12;
      }
    </style>

    <link rel="stylesheet" href="assets/style.css" />
    <script type="module" crossorigin src="./esm/index.mjs"></script>
  </head>
  <body>
    <jumio-sdk dc="us" token=""></jumio-sdk>
    <template id="setup">
      <h1>Start Verification</h1>
      <button onclick="start()">Fetch a token and proceed</button>
      <script>
        function start() {
          fetch('http://mydomain.com/webSdkToken')
            .then(response => response.text())
            .then(token => {
              const jumioSDK = document.querySelector('jumio-sdk');
              jumioSDK.setAttribute('token', token);
            });
        }
      </script>
    </template>
  </body>
</html>
; }
```

:::tip
Note that the "dc" attribute is hard coded. This is intentional, based on the assumption that your transactions will all be routed to a specific Jumio datacenter. If that is not the case you will need to create some logic to set the dc value dynamically.
:::

---

# Slots

https://documentation.jumio.ai/docs/developer-resources/SDKs/web-sdk/slots

# Slots

The `.<jumio-sdk>` element supports slots that you can use to customize the customer journeyClosed. Slots are custom html elements with a named "slot" attribute. These slot elements are embedded within the `<jumio-sdk>` tags, as shown in the examples below. Currently these slots are supported:

- Logging
- Navigation
- Theme

## Logging

Two custom elements are available for configuring the logging behavior of the Web SDK:

`<jumio-sdk-logger-console slot="logger" data-enabled="true"></jumio-sdk-logger-console>`

Adding and enabling the console logger will enable end-user events to be accessed from the browser console. This is often useful for debugging purposes. For example, the data-enabled attribute may be set to true when your application is deployed to a development or staging environment, and then set to false when deployed to production.

`<jumio-sdk-logger-datadog slot="logger" data-enabled="true" data-config='{"applicationId": "123"}'></jumio-sdk-logger-datadog>`

The DataDog logger is deployed by default so events are available to Jumio Support. If your organization has a DataDog application and you want events to be logged to your application instead of Jumio's, add this element and provide your own application Id as value for the data-config attribute. This element may also be used to disable DataDog logging altogether by setting the data-enabled attribute to false. Be aware that doing so will limit the ability of Jumio Support to assist with end-user issues.

Either or both may be embedded in the `<jumio-sdk>` element to enable the logging.

```
Example: Logger Slot
<jumio-sdk dc="..." token="...">
  <!--
  Enabling the console logger.
  This logger is disabled by default
  -->
  <jumio-sdk-logger-console slot="logger" data-enabled="true"></jumio-sdk-logger-console>

  <!--
  Enabling the datadog logger explicitly and overriding its configuration.
  This logger is enabled and pre-configured by default to log events to the Jumio application.
  -->
  <jumio-sdk-logger-datadog
    slot="logger"
    data-enabled="true"
    data-config='{"applicationId": "123"}'
  ></jumio-sdk-logger-datadog>
</jumio-sdk>
```

## Navigation

The Jumio SDK supports either:

- A browser-based navigation system leveraging the browser's History API (default).

```
<jumio-sdk dc="..." token="...">
  <!-- Configuring browser-based navigation -->
  <jumio-sdk-navigation-config-browser slot="navigation"></jumio-sdk-navigation-config-browser>
</jumio-sdk>
```

With this setup, Jumio SDK navigation is tightly integrated with the browser's history. Consequently, every transition between different steps in the application gets reflected in the browser's URL. This allows users to utilize the browser's forward and backward arrows for navigating between different states of the Jumio SDK.

- An in-memory navigation system.

```
<jumio-sdk dc="..." token="...">
  <!-- Configuring in-memory navigation -->
  <jumio-sdk-navigation-config-memory slot="navigation"></jumio-sdk-navigation-config-memory>
</jumio-sdk>
```

This configuration establishes an in-memory navigation system within the Jumio SDK. As the user transitions between different steps in the SDK, the navigation actions do not affect the browser's history.

## Theme

Jumio SDK allows customization of its visual aesthetic through theme configuration. You can specifically set the color scheme of the SDK to light, dark, or auto, thereby tailoring the Jumio SDK to seamlessly integrate into your application's user interface or the user's preferences. For more details on browser color preferences, refer to this MDN Web Docs guide.

- Automatic Mode (auto): The default theme configuration is to simply use the theme preferences in the browser or operating system.
- Light Mode (light): Setting the color scheme to light explicitly displays Jumio SDK in light colors, irrespective of the browser color scheme preferences.

```
<jumio-sdk dc="..." token="...">
  <!-- Setting the Light theme -->
  <x-ds-color-scheme-config slot="theme" data-color="light"></x-ds-color-scheme-config>
</jumio-sdk>
```

- Dark Mode (dark): Choosing dark as the color scheme will present Jumio SDK in dark colors, overriding the color preferences of the browser.

```
<jumio-sdk dc="..." token="...">
  <!-- Setting the Dark theme -->
  <x-ds-color-scheme-config slot="theme" data-color="dark"></x-ds-color-scheme-config>
</jumio-sdk>
```

---

# CSS Variables

https://documentation.jumio.ai/docs/developer-resources/SDKs/web-sdk/web-sdk-css

# CSS Variables

The Web SDK provides CSS variables you can override to customize the fonts and color palettes used used for the customer journey.

:::tip
Reference information on the CSS variables are available in the [Storybook Documentation](https://docs.web.jumio.ai/iframe.html?viewMode=docs&id=websdk-jumio-sdk--documentation#customizing-fonts-and-colors-with-jumio-web-sdk).
:::

If you do not explicitly set the CSS variables defaults will be used. For example, the default Start verification page looks like this:

<center>![](../web-sdk/WebSdkStartDefault.png)</center>

## Example: CSS Variable Overrides

You can change the fonts and color schemes by setting variable values. The following example will:

- Change the default font family to Garamond.
- Base the primary color palette on orange.
- Base the secondary color palette on blue.

```
:root {
  --jumio-sdk-font: 'Garamond', serif;

    --jumio-sdk-color-primary1: hsl(19, 100%, 90%);
    --jumio-sdk-color-primary2: hsl(19, 100%, 70%);
    --jumio-sdk-color-primary3: hsl(19, 100%, 60%);
    --jumio-sdk-color-primary4: hsl(19, 100%, 50%);
    --jumio-sdk-color-primary5: hsl(19, 100%, 40%);
    --jumio-sdk-color-primary6: hsl(19, 100%, 30%);
    --jumio-sdk-color-primary7: hsl(19, 100%, 10%);

    --jumio-sdk-color-secondary1: hsl(238, 100%, 97%);
    --jumio-sdk-color-secondary2: hsl(238, 100%, 95%);
    --jumio-sdk-color-secondary3: hsl(238, 100%, 90%);
    --jumio-sdk-color-secondary4: hsl(238, 100%, 81%);
    --jumio-sdk-color-secondary5: hsl(238, 100%, 65%);
    --jumio-sdk-color-secondary6: hsl(238, 100%, 50%);
    --jumio-sdk-color-secondary7: hsl(238, 100%, 40%);
    --jumio-sdk-color-secondary8: hsl(238, 100%, 28%);
    --jumio-sdk-color-secondary9: hsl(238, 100%, 24%);
    --jumio-sdk-color-secondary10: hsl(238, 100%, 20%);
    --jumio-sdk-color-secondary11: hsl(238, 100%, 16%);
    --jumio-sdk-color-secondary12: hsl(238, 100%, 14%);

}

```

The Start verification page will look like this:

<center>![](../web-sdk/WebSdkStartCssVars.png)</center>

---

# Templates

https://documentation.jumio.ai/docs/developer-resources/SDKs/web-sdk/web-sdk-templates

# Templates

:::info
The complete template reference is available in the [Storybook Documentation](https://docs.web.jumio.ai/iframe.html?viewMode=docs&id=websdk-jumio-sdk--documentation#customizing-fonts-and-colors-with-jumio-web-sdk).
:::

The Web SDK provides an out-of-the-box user experience that guides the end user through the process of uploading the
[credentials](./../references/glossaries#credential) required by the workflow they are using. The look and feel of the various steps in the journey can be customized using templates.

Following are some simple examples to show how it works.

The index.html file provides a fully functional out-of-the-box implementation once you have provided the dc and token attribute values (see Web SDK). An easy way to try out various templates is to launch a local server as described in the Installing the Web SDK Package README.md file and configure the templates in the index.html file.

Implement the out-of-the-box customer journey by adding the &lt;jumio-sdk&gt; tags in the body of the html page:

```
  <body>
    <jumio-sdk dc="us" token="ey...iUw"></jumio-sdk>
  </body>
```

If you run this on your localhost server and access index.html, you will see:

<center>![](../web-sdk/defaultSDKStart.png)</center>

You can customize the journey by adding whatever templates you want inside the &lt;body&gt; tags. To change the title from **"Let's get you verified**" to **"Click the button to proceed,"** simply add the start-title template in the body of the page:

```
  <body>
    <template id="start_title">
    <h1>Click the button to proceed.</h1>
    </template>

    <jumio-sdk dc="us" token="ey...iUw"></jumio-sdk>
  </body>
```

Refresh the page in your browser to see:

<center>![](./customStart1webSdk.png)</center>

---

# Web Client Reference

https://documentation.jumio.ai/docs/developer-resources/web-client/

# Web Client

Jumio provides a turnkey web client that you can provide to your end users to guide them through the customer journey. The URL to the web client is available from the `web:href` value of the response from the account creation or update call, as shown in the following example:

## Example Web Client URL

```
 {
   "timestamp": "2022-11-28T23:45:02.536Z",
   "account": {
     "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
   },
   "web": {
    "href":  "https://jumio-mfa.web.amer-1.jumio.ai/web/client?baseUrl=https%3A%2F%2Fweb-sdk.emea-1.jumio.ai%2Fwebsdk%2Fv4%2Fapi&authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOQQrCMBCF4auUrB3IJJMmdefSrTeYTCYg2BZiRUW8u9EbuH18PP6X0cdhM3uDkRKlhEjOBbMzLHIsfXdYYqqOwHKdgKL3wKIZMgVEjTa5NH75D9tMkiU7qCErEEuASUOG6K2WKDFh8R3fq_7D5aS165mXwtvanoPcrts6axvOy6Zt4cvQtGrTRfTLf985cHJWerdaBLLUu12cYBzH4KvnMCma9wfM2Wef_wAAAA.3O4SlXYeSJ39cEbgTpcliM2sxlC2F3eJGun5kG1R7OgkMwbhz-YMGQkh6pys11soT3-OQRX-yDqgwWtEL34T4w&locale=en-US" },
     ...
```

:::info
You need to define a subdomain in the Jumio Portal under Settings > Identity Verification > Application Settings > Domain Name in order to successfully generate a web.href.
Refer: [Application Settings](/docs/portals/settings/aboutIDVSettings#application-settings).
:::

### URL Handling for Web Client

- Always use the exact web.href returned from the account creation API.
- Do not construct verification URLs manually.
  Only redirect/embed web.href after explicit user action.
- Store and log the workflowExecutionId for debugging and support.
- Treat web.href like a secret — do not expose it to untrusted contexts.

### You can provide this URL to your customer in several ways:

- As a link on your web page that opens a new browser tab or window.
- As a link shared securely with the end user.
- In a native webview, refer [Embedding in a WebView](/docs/developer-resources/web-client/web-view-integration.md).
- Within an iFrame on a web page in your own application, refer [Embedding in an iFrame](/docs/developer-resources/web-client/embed-iFrame).

### What is presented to the end-user in the web client depends on the following:

- The workflow that was specified in the account creation or update API call. Different workflows require different credentials. The web client will guide the user to capture and upload the credentials that are required for the workflow.
- The Identity Verification Settings that have been configured in the Jumio Portal, checkout [About the Identity Verification Settings](/docs/portals/settings/managingUserandTenant#about-the-identity-verification-settings).
- It is also possible to override some of the Identity Verification Settings on a per-transaction basis. (Checkout Overriding the Default Settings as given below) .

### When the customer journey is complete,

- End-user is redirected to either the successUrl or the errorUrl (defined in the Settings or the Account request).
- Information about the transaction is appended to the URL.
- Checkout [Acquisition Status and Error Codes](/docs/developer-resources/web-client/#acquisition-status-and-error-codes).

See [Supported Environments](/docs/developer-resources/web-client/supported-environments) for details on supported browsers and operating systems.

## Overriding the Default Settings

You can override some of the default configuration settings for individual transactions by including optional web-specific parameters in the request to create or update an account. Include a Web object in the Account request body, as described in [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).

**web Object Example**

```
"overrideSettings": {
  "crossDeviceOption": "QR_ONLY",
  "crossDeviceOnly":"true"
},

```

These override, on a per-transaction basis, the cross-device option and the cross-device-only setting.

## Redirect Pages

Use `web.successUrl` and `web.errorUrl` to specify how the end user will be redirected by the browser at the end of the web acquisition user journey.

If these parameters are not provided, and the values are not present in the Jumio Platform settings, the end user will be shown a success or error page instead.

## Languages

Use `web.locale` to render the content of the client in the specified language.

The values are hyphenated combinations of [ISO 639-1:2002alpha-2](https://en.wikipedia.org/wiki/ISO_639-1) language code plus [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country (where applicable), as shown in the following table:

:::important

| Value | Locale      |
| ----- | ----------- |
| sq    | Albanian    |
| ar    | Arabic      |
| az    | Azerbaijani |
| bn    | Bengali     |

**Expand the list below,**

<details>
<summary>**Supported Languages**</summary>
| Value    | Locale                     |
| -------- | -------------------------- |
| sq       | Albanian                   |
| ar       | Arabic                     |
| az       | Azerbaijani                |
| bn       | Bengali                    |
| bn-IN    | Bengali (India)            |
| bg       | Bulgarian                  |
| ms       | Burmese                    |
| my-MM    | Burmese (Myanmar)          |
| ca       | Catalan                    |
| ceb      | Cebuano                    |
| ceb-PH   | Cebuano (Philippines)      |
| zh       | Chinese (default)          |
| zh-CN    | Simplified Chinese         |
| zh\_CN   | Simplified Chinese         |
| zh-HK    | Traditional Chinese        |
| zh\_HK   | Traditional Chinese        |
| hr       | Croatian                   |
| cs       | Czech                      |
| da       | Danish                     |
| nl       | Dutch                      |
| en       | American English (default) |
| en-GB    | English (United Kingdom)   |
| en\_GB   | English (United Kingdom)   |
| et       | Estonian                   |
| fi       | Finnish                    |
| fil-PH   | Filipino (Philippines)     |
| fi       | Filipino                   |
| fr       | French                     |
| fr-CA    | French (Canada)            |
| ka-GE    | Georgian                   |
| ka\_GE   | Georgian                   |
| de       | German                     |
| el       | Greek                      |
| iw       | Hebrew                     |
| hi       | Hindi                      |
| hi-IN    | Hindi (India)              |
| hu       | Hungarian                  |
| is       | Icelandic                  |
| id       | Indonesian                 |
| ga       | Irish                      |
| it       | Italian                    |
| ja       | Japanese                   |
| jv       | Javanese                   |
| jv-ID    | Javanese (Indonesia)       |
| kk       | Kazakh                     |
| km       | Khmer                      |
| ko       | Korean                     |
| lv       | Latvian                    |
| lt       | Lithuanian                 |
| ms       | Malay                      |
| no       | Norwegian                  |
| pl       | Polish                     |
| pt       | Portuguese                 |
| pt-BR    | Brazilian Portuguese       |
| pt\_BR   | Brazilian Portuguese       |
| ro       | Romanian                   |
| ru       | Russian                    |
| sr       | Serbian (default)          |
| sr\_Latn | Serbian (Latin)            |
| sr-Latn  | Serbian (Latin)            |
| sr-Cyrl  | Serbian (Cyrillic)         |
| sr\_Cyrl | Serbian (Cyrillic)         |
| sk       | Slovak                     |
| sl       | Slovenian                  |
| es       | Spanish                    |
| es\_MX   | Mexican Spanish            |
| es-MX    | Mexican Spanish            |
| sv       | Swedish                    |
| sw       | Swahili                    |
| th       | Thai                       |
| tr       | Turkish                    |
| ur       | Urdu                       |
| uz       | Uzbek                      |
| uk       | Ukrainian                  |
| vi       | Vietnamese                 |

</details>

:::

## Acquisition Status and Error Codes

At the end of the web acquisition customer journey, the following query parameters are appended by the web client to the success or error URL before the end-user is redirected by the browser.

Required items appear in bold type.

| Name                                                                 | Description                                                                  |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **accountId**                                                        | UUID of the account                                                          |
| **workflowExecutionId**                                              | UUID of the workflow                                                         |
| **acquisitionStatus**                                                | Possible values <ul><li>SUCCESS</li><li> ERROR</li></ul>                     |
| **customerInternalReference**                                        | Customer internal reference for a request to link it in the customer backend |
| errorCode (deprecated; will no longer be sent starting **15/12/25**) | Possible value <ul><li><strong>9100</strong> – Server error</li></ul>        |
| publicErrorCode (available starting **15/9/25**)                     | Refer to the table below                                                     |

:::note
Predefined list of **errorCode** and **publicErrorCodes**, only appended to errorUrl when `acquisitionStatus` is ERROR.
:::

### publicErrorCodes

| Code Pattern | Message                                                            | Description                                                  |
| ------------ | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| A[xx][yyyy]  | We have encountered a network communication problem                | Retry possible, user decided to cancel                       |
| B[xx][yyyy]  | Authentication failed                                              | Secure connection could not be established, retry impossible |
| C[xx]0401    | Authentication failed                                              | API credentials invalid, retry impossible                    |
| H[xx]0000    | The camera is currently not available                              | Camera cannot be initialized, retry impossible               |
| J[xx]0000    | Transaction already finished                                       | User did not complete SDK journey within session lifetime    |
| M[xx]0000    | Transaction cannot be completed                                    | User did not complete the transaction.                       |
| N[xx]0000    | Scanning not available at this time, please contact the app vendor | Required images are missing to finalize the acquisition      |

## Token Usage & Security

- Always generate SDK tokens and access tokens server-side.
- Never hard-code tokens in the frontend or share API secrets in the browser.
- Tokens are single-use and time-limited — do not reuse them.
- Ensure all communication is over HTTPS.

---

# Embedding in WebView

https://documentation.jumio.ai/docs/developer-resources/web-client/web-view-integration

# Embedding in WebView

**Example**
https://github.com/Jumio/mobile-webview

The Web Client can be embedded in a WebView in your native mobile application.

## UI/UX Considerations

- Start verification only after the user initiates action.
- Show branded loading screens during token generation.
- Inform users about steps before starting verification.
- Provide retry and fallback paths.

## Android WebView

You can embed the Web Client in a native Android WebView.

### Permissions and Settings

#### Permission in the AndroidManifest

Make sure that all required permissions are granted by adding them to the [AndroidManifest.xml](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
   android:maxSdkVersion="32" />
```

##### General

- android.permission.INTERNET - Remote resources access.
- android.permission.CAMERA - Camera capture.

The permissions for the upload functionality depend on the target API level - see the official [Android Developer Documentation](https://developer.android.com/training/data-storage#permissions) for further information.

##### Upto API Level 32

- android.permission.READ_EXTERNAL_STORAGE

##### From API Level 33 Onwards

- android.permission.READ_MEDIA_AUDIO
- android.permission.READ_MEDIA_VIDEO
- android.permission.READ_MEDIA_IMAGES
- android.permission.MODIFY_AUDIO_SETTINGS
- android.permission.RECORD_AUDIO

#### Request Permissions at Runtime

In addition to defining the permissions in the Manifest, you also need to request them during runtime before the webview is started. A full implementation can be found in the sample apps [MainActivity.kt](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/java/com/jumio/nvw4/MainActivity.kt).

#### Prerequisites

In our sample, we use ActivityCompats OnRequestPermissionResultCallback. More information about requesting runtime permissions can be found in the official [Android Developer Documentation](https://developer.android.com/training/permissions/requesting).

##### Permissions to Be Requested

```kotlin
val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
   arrayOf(
      Manifest.permission.CAMERA,
      Manifest.permission.READ_MEDIA_AUDIO,
      Manifest.permission.READ_MEDIA_IMAGES,
      Manifest.permission.READ_MEDIA_VIDEO,
      Manifest.permission.MODIFY_AUDIO_SETTINGS,
      Manifest.permission.RECORD_AUDIO,
   )
} else {
   arrayOf(
      Manifest.permission.CAMERA,
      Manifest.permission.READ_EXTERNAL_STORAGE,
   )
}
```

##### Identify Permissions Not Granted

```kotlin
val missingPermissions = permissions.filter { permission ->
	ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED
}.toTypedArray()
```

##### Request All Missing Permissions

```kotlin
if (missingPermissions.isNotEmpty()) {
	ActivityCompat.requestPermissions(this, missingPermissions, PERMISSION_REQUEST_CODE)
} else {
	showWebView(url)
}
```

##### Implement OnRequestPermissionResultCallback

Check for the request code that you set while requesting the permissions, and see if all permissions are granted. If not, handle the denied permissions accordingly.

```kotlin
override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
	super.onRequestPermissionsResult(requestCode, permissions, grantResults)

	if (requestCode == PERMISSION_REQUEST_CODE) {
		val deniedPermissions = permissions.filterIndexed { index, _ ->
			grantResults[index] != PackageManager.PERMISSION_GRANTED
		}

		if (deniedPermissions.isNotEmpty()) {
			handleDeniedPermissions(deniedPermissions)
		} else {
			showWebView(requestedUrl)
		}
	}
}

```

#### Configure the WebView

##### Apply settings

The following settings are required for the native WebView for Android. A full implementation can be found in the sample apps [WebViewFragment.kt](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/java/com/jumio/nvw4/fragments/WebViewFragment.kt).

```kotlin
binding.webview.apply {
	settings.apply {
		allowFileAccess = true
		allowContentAccess = true
		domStorageEnabled = true
		javaScriptEnabled = true
		@Suppress("DEPRECATION")
		allowUniversalAccessFromFileURLs = true
		javaScriptCanOpenWindowsAutomatically = true
		mediaPlaybackRequiresUserGesture = false
	}
}
```

- **Enable `javaScriptEnabled`** – Allows the WebView to execute JavaScript.
- **Allow `allowFileAccess`** – Enables file access within WebView.
- **Allow `allowFileAccessFromFileUrls`** – Determines whether JavaScript running in the context of a `file://` URL can access content from other `file://` URLs.
- **Allow `allowUniversalAccessFromFileUrls`** – Determines whether JavaScript running in the context of a `file://` URL can access content from any origin.
- **Allow `allowContentAccess`** – Enables content URL access within WebView.
- **Allow `javaScriptCanOpenWindowsAutomatically`** – Lets JavaScript open windows automatically.
- **Enable `domStorageEnabled`** – Enables the DOM storage API.
- **Do not allow `mediaPlaybackRequiresUserGesture`** – Specifies whether the WebView requires a user gesture to play media.

##### Handle permission request

Grant the webviews android.webkit.resource.VIDEO_CAPTURE permission request once it is received. Check if the Camera permission is granted - if not, handle accordingly.

```kotlin

binding.webview.webChromeClient = object : WebChromeClientFullScreen() {
	// Grant permissions for camera
	override fun onPermissionRequest(request: PermissionRequest) {
		val activity = activity ?: return
		activity.runOnUiThread {
			if (request.resources.contains("android.webkit.resource.VIDEO_CAPTURE")) {
				if (ContextCompat.checkSelfPermission(
						requireActivity(),
						Manifest.permission.CAMERA
					) == PackageManager.PERMISSION_GRANTED
				) {
					request.grant(request.resources)
				} else {
					// Handle not granted permission
				}
			}
		}
	}
}

```

### Embedding the Required Script

**PostMessage communication**
You can handle messages from the Web Client using the same method as described in Optional iFrame Logging.

You will need to register a postMessage handler and put the relevant code sections in the PostMessageHandler class as in the example below.

```
kotlin
binding.webview.addJavascriptInterface(PostMessageHandler(), "__NVW_WEBVIEW_HANDLER__")

```

```kotlin
    class PostMessageHandler {
        @JavascriptInterface
        fun postMessage(json: String?, transferList: String?): Boolean {
            /*
                There we're handling messages from the client, it's the same as for iFrame logging;
            */
            Log.d(TAG, "postMessage triggered, json: " + json.toString())
            return true
        }
    }
```

### Use of iProov

Be aware that if iProov is included in your workflow it is necessary to extend the `WebChromeClient` class to implement a custom view, in order to handle certain iProov full screen requirements.

See [WebviewFragment.kt](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/java/com/jumio/nvw4/fragments/WebViewFragment.kt), specifically WebChromeClientFullScreen inner class.

### Sample App

Check out our [Sample App for the Native Android WebView](https://github.com/Jumio/mobile-webview/tree/master/android).

### Sample code

- [AndroidManifest.xml](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/AndroidManifest.xml) example

- [build.gradle](https://github.com/Jumio/mobile-webview/blob/master/android/build.gradle) example

- [WebviewFragment.kt](https://github.com/Jumio/mobile-webview/blob/master/android/app/src/main/java/com/jumio/nvw4/fragments/WebViewFragment.kt) example

## iOS WebView

Jumio supports two types of WebView for iOS,

- Safari WebView
- Native iOS WebView

### Permissions and Settings

#### Camera Permissions

To enable camera access within the WebView (e.g., for capturing a photo of a user's ID, Liveness or Document), your iOS app must request the camera permission from the user.
Please ensure that you add the following entry to your app's Info.plist file:

```
<key>NSCameraUsageDescription</key>
<string>This will allow ${PRODUCT_NAME} to take photos of your credentials.</string>
```

#### Location Permissions

To enable location-based functionality within the WebView (e.g., for determining the user's region and showing the correct list of supported IDs), your iOS app must request the appropriate permission from the user.
Please add the following entries to your app’s Info.plist file:

```
<key>NSLocationWhenInUseUsageDescription</key>
<string>This will allow ${PRODUCT_NAME} to use your current location when app is in foreground.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This will allow ${PRODUCT_NAME} to use your current location when app is in background.</string>
```

:::note
Jumio only uses location when app is in foreground hence we recommend including **_NSLocationWhenInUseUsageDescription_** key for requesting location access. If your app requires location access even when the app is in background, you should also include **_NSLocationAlwaysUsageDescription_**.
:::

### Safari WebView

This section describes how to embed Web Client in a Safari View Controller (SFSafariViewController).

#### Sample App

Check out our [Sample App for the iOS Safari WebView](https://github.com/Jumio/mobile-webview/tree/master/ios/SafariViewController-Pilot).

#### Sample Code

- [ViewController.swift](https://github.com/Jumio/mobile-webview/blob/master/ios/SafariViewController-Pilot/SafariViewController-Pilot/ViewController.swift) example

### Native iOS WebView

This section describes how to embed the Web Client in a native iOS WebView (WKWebView).

#### Embedding the Required Script

PostMessage communication. You can handle messages from the Web Client using the same method as described in Optional iFrame Logging.

You will need to register a userContentController:

```swift
       webView.configuration.userContentController.add(self, name: "__NVW_WEBVIEW_HANDLER__")
```

```swift
extension ViewController: WKScriptMessageHandler {
   func userContentController(_ userController: WKUserContentController, didReceive message: WKScriptMessage) {
       if message.name == "__NVW_WEBVIEW_HANDLER__", let messageBody = message.body as? String {
           // do something here with message
           // print is only an example
           print(messageBody)
       }
   }
}
```

#### Sample App

Check out our [Sample App for the Native iOS WebView](https://github.com/Jumio/mobile-webview/tree/master/ios/WebView-Pilot).

:::info
Please also enable inline Playback for the WebView in the Storyboard/UI builder.
:::

#### Sample Code

[ViewController.swift](https://github.com/Jumio/mobile-webview/blob/master/ios/WebView-Pilot/WebView-Pilot/ViewController.swift) Example

---

# Embedding in iFrame

https://documentation.jumio.ai/docs/developer-resources/web-client/embed-iFrame

# Embedding in iFrame

If you want to embed the Web Client on your web page, place the iFrame tag in your HTML code where you want the client to appear. Use `web.href` as the value of the iFrame `src `attribute.

:::info
Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
:::

## allow Attributes

The following `allow` attributes must be included to enable the camera for image capture in supported browsers:

- camera
- autoplay
- fullscreen
- clipboard-read
- clipboard-write
- accelerometer
- gyroscope
- magnetometer

### Example

```
<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="70%" height="80%" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

## Width and Height

We recommend adhering to the responsive breaking points in the following table:

| Size class | Width    | Height   |
| ---------- | -------- | -------- |
| Large      | ≥ 900 px | ≥ 710 px |
| Medium     | 640 px   | 660 px   |
| Small      | 560 px   | 600 px   |
| X-Small    | ≤ 480 px | ≤ 535 px |

When specifying the width and height of your iFrame, you may prefer to use percentage values so that the iFrame behaves responsively on your page.

### Absolute Sizing Example

```
<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="930" height="750" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

### Responsive Sizing Example

```
<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="70%" height="80%" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

### Recommended Approach for Error Handling (Optional iFrame Logging​)

When the Web Client is embedded in an iFrame it will communicate with the containing page using the JavaScript `window.postMessage()` method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g. by directing to a new page once the success event is received).

Events include data that allows the containing page to identify which transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the `message` event on the global window object and reacting to it as needed. The data passed by the Web Client in this notification is represented as JSON in the `data` string property of the listener method’s `event` argument. Parsing this JSON string results in an object with the properties described below.

:::warning
If success or error redirect URLs are configured, the final event will not be delivered because the redirection occurs before the event is sent.  
We recommend choosing **either event listeners** or **redirect URLs**, but not both.
:::

:::note
All data is encoded with UTF-8. This functionality is not available for instances of the Web Client running in a standalone window or tab.
:::

#### Error Handling & Retry Logic

- Redirect to a fallback page on errors.
- Control retries server-side — always generate fresh tokens.
- Log workflowExecutionId, session start, and error codes.

### `event.data` object

Required items appear in bold type.

| Property                      | Type        | Description                                                                                                                                                                    |
| ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **accountId**                 | string      | UUID of the account                                                                                                                                                            |
| **authorizationToken**        | string      | Authorization token, valid for a specified duration                                                                                                                            |
| **workflowExecutionId**       | string      | UUID of the workflow                                                                                                                                                           |
| **customerInternalReference** | string      | Internal reference for a request to link it in the customer backend. It must not contain Personally Identifiable Information (PII) or sensitive data such as e-mail addresses. |
| **eventType**                 | integer     | Type of event that has occurred. Possible values: `510` (application state-change)                                                                                             |
| **dateTime**                  | string      | UTC timestamp of the event in the browser Format: _YYYY-MM-DDThh:mm:ss.SSSZ_                                                                                                   |
| **payload**                   | JSON object | Information specific to the event generated (refer the table below)                                                                                                            |

### `event.data.payload` object

Required items appear in bold type.

| Name      | Type        | Description                                                                                                                                                                                                                     |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **value** | string      | Possible values: <ul><li>**loaded** (Web Client loaded in the user’s browser).</li><li>**success** (Images were accepted for verification). </li><li>**error** (Verification could not be completed due to an error).</li></ul> |
| metainfo  | JSON object | Additional meta-information for error events. (see event.data.payload.metainfo object)                                                                                                                                          |

#### Example payload info object

```
{
  "authorizationToken": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMy2rDQAyF4Vcxs65gLtJcuusy27yBrJEgkDgwcWlD6LvX9htkd_j5OC-nv1-r-3ShUKKQUiglZPfhWOTUt26Vva_BAGNEQKUAdV9NAyH6HKPizg8shbL0lsFySoCdDRq1BqIBzWT2rfoN_5i-w-WstukbL53X-3hO8v1Y7zcd02VZdSx8nYaaDl1Ed358k0ZUowqaegfkmIDnSlDYvFHWgml2f_8yL0I9_wAAAA.E-C7qQu_RgRUuUlw93VWDkzgPGb94ZeAleyZ6RR4MSX6Dmu3m3YqSEIlCQEYzXFtjH1K5uyUsfI65G5y_JF06g",
  "eventType": 510,
  "dateTime": "2025-05-27T07:02:23.747Z",
  "payload": {
    "value": "error",
    "metainfo": {
      "mode": "original",
      "code": 9822,
      "codeExternal": 9822,
      "publicErrorCode": "H000000"
    }
  },
  "workflowExecutionId": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "transactionReference": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "jumioIdScanReference": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "accountId": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "customerInternalReference": "mandatory customer internal reference"
}

```

### `event.data.payload.metainfo` object

Required items appear in bold type.

| Property | Type    | Description                                                                                       |
| -------- | ------- | ------------------------------------------------------------------------------------------------- |
| code     | integer | Only present if payload.value=error Only present if `payload.value=error`. Check the table below. |

#### publicErrorCodes

| Code Pattern | Message                                                            | Description                                                  |
| ------------ | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| A[xx][yyyy]  | We have encountered a network communication problem                | Retry possible, user decided to cancel                       |
| B[xx][yyyy]  | Authentication failed                                              | Secure connection could not be established, retry impossible |
| C[xx]0401    | Authentication failed                                              | API credentials invalid, retry impossible                    |
| H[xx]0000    | The camera is currently not available                              | Camera cannot be initialized, retry impossible               |
| J[xx]0000    | Transaction already finished                                       | User did not complete SDK journey within session lifetime    |
| M[xx]0000    | Transaction cannot be completed                                    | User did not complete the transaction.                       |
| N[xx]0000    | Scanning not available at this time, please contact the app vendor | Required images are missing to finalize the acquisition      |

### Example meta info object

```
{
"value": "error",
  "metainfo": {
    "mode": "original",
    "code": 9801,
    "codeExternal": 9801,
    "publicErrorCode": "M010451",
    "retriable": false
  }
}

```

:::note
The "retriable" field indicates whether an error is recoverable.
:::

## Example iFrame Logging Code

```
window.addEventListener("message", (event) => {
  const mandatoryKeys = ['authorizationToken', 'eventType', 'payload'];
  const data = window.JSON.parse(event.data);
  if (mandatoryKeys.every((key) => key in event.data)) {
    console.log('ID Verification Web was loaded in an iframe.');
    console.log('auth-token:', data.authorizationToken);
    console.log('event-type:', data.eventType);
    console.log('date-time:', data.dateTime);
    console.log('workflow-execution-id:', data.workflowExecutionId);
    console.log('account-id:', data.accountId);
    console.log('customer-internal-reference:', data.customerInternalReference);
    console.log('value:', data.payload.value);
    console.log('metainfo:', data.payload.metainfo);
  }
});
```

## iFrame Security

- Configure Content Security Policy (CSP) to allow only \*.jumio.ai in frames.
- Restrict which origins can embed the iFrame.
- Use postMessage API for receiving status updates.
- Consider full-page modals for mobile responsiveness.

---

# Supported Environments

https://documentation.jumio.ai/docs/developer-resources/web-client/supported-environments

# Supported Environments

Jumio offers guaranteed support for the Web Client on the following browsers and the latest major version of each operating system.

## Desktop

| Browser         | Major version       | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
| --------------- | ------------------- | ---------------- | --------------------- | ----------------------- | ------------------------------- |
| Google Chrome   | current +1 previous | Windows + Mac    | Yes                   | Yes                     | Yes                             |
| Mozilla Firefox | current +1 previous | Windows + Mac    | Yes                   | Yes                     | Yes                             |
| Apple Safari    | current             | Mac              | Yes                   | Yes                     | Yes                             |
| Microsoft Edge  | current             | Windows          | Yes                   | Yes                     | Yes                             |

## Mobile

| Browser          | Major version | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
| ---------------- | ------------- | ---------------- | --------------------- | ----------------------- | ------------------------------- |
| Google Chrome    | current       | Android          | Yes                   | Yes                     | Yes                             |
| Samsung Internet | current       | Android          | Yes                   | Yes                     | Yes                             |
| Apple Safari     | current       | iOS              | Yes                   | Yes                     | Yes (\*)                        |

(\*) Fullscreen functionality during capture only supported for iPads. iPhone process works, but fullscreen is limited and capture may be less accurate.

## Native WebView

| Operating system        | Major version       | Supports image upload | Supports camera capture | Supports biometric face capture |
| ----------------------- | ------------------- | --------------------- | ----------------------- | ------------------------------- |
| Native Android WebView  | current +1 previous | Yes                   | Yes                     | Yes                             |
| Native iOS WebView (\*) | current +1 previous | Yes                   | Yes                     | Yes                             |
| iOS Safari WebView      | current +1 previous | Yes                   | Yes                     | Yes                             |

(\*) If you are using a native WebView for iOS you will need to enable image upload to allow the end user to finish the user journey.

---

# Jumio Portal

https://documentation.jumio.ai/docs/portals/welcome_to_the_jumio_portal

# Welcome to the Jumio Portal

The Jumio Portal supports multiple roles and functions for configuring and managing identity transactions. What you have access to when you sign in depends on your role in your organization. For example, if you are an administrator, you will have access to the Settings section of the portal, where you can manage users and account settings, but you might not have access to the Rules Management section. And if you are an analyst, you might have access to the rules and analytics, but not the settings.

:::info
For access to a feature that isn't visible when you sign in, please reach out to your Administrator. They can help ensure you have the necessary permissions to access all available features.
:::

---

# Jumio Watch

https://documentation.jumio.ai/docs/portals/jumioWatch

## Overview

Jumio Watch is an ability for Jumio to alert Customers proactively when new risk knowledge is obtained from Jumio's Identity Graph, through connections and behavior, which now classifies a previously approved transaction as a Fraud risk.

### Use Cases

- **New Risk:** Genuine user turning risky later, especially First Party Frauds
- **Undetected Risk:** If Jumio did not detect a risk with the user in the past

### Key Benefits

- Take proactive measures to protect against existing users who have turned risky in your ecosystem
- Stop fraud loss, even if the bad actor made it through onboarding

Alerts under Jumio Watch will be triggered only against those transactions with ID Verification that were successfully verified, either with status “Passed” or “Warning”.

Jumio Watch triggers an alert for such transactions, if
- an incoming connected ID Verification transaction gets rejected by Jumio's system with a fraud risk reason or
- an already processed "Passed" or "Warning" ID Verification transaction is marked with a fraud risk status by Jumio's audits

As a customer, you will be alerted once a day via email and can proactively monitor and manage alerts in the Jumio Customer Portal.

## How to Enable Jumio Watch for your Tenant

Contact [Jumio Support](https://support.jumio.com/s/) or your Jumio Account Manager.

## Configuring User Access to Alerts

Administrators of your Jumio Portal accounts can customize which existing Jumio Portal users receive the Daily Alert Summary over email and access to Alert View on Jumio Portal.

Follow these steps to manage alert preferences:

**Step 1:** Log in to the Jumio Portal and navigate to **Settings > Identity Verification > Alerts**.
![](./images/Step1.png)

**Step 2:** Review the list of users currently associated with the tenant.
![](./images/Step2.png)

**Step 3:** **Toggle** the "Email Alerts" or "UI Alerts" options next to each user to enable or disable specific notification types.
![](./images/Step3.png)

## Receiving Daily Alert Summary Over Email

Your Jumio Portal users can be configured to receive the Daily Alert Summary over email addresses configured within the Jumio Portal. New users interested in receiving these alerts will need to have their account created on the Jumio Portal for your tenant.

There will be one Daily Alert Summary email per tenant for the allowed users.

![](./images/Step4.png)

The daily alert email shows:

| **Field**                 | **Description**                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| **New Alerts**            | Count of new alerts generated for the first time on a transaction                             |
| **Repeat Alerts**         | Count of alerts that were previously generated and have reoccurred due to a new risk incident |
| **High Risk Connections** | The total number of high-risk transactions connected to alerted transactions                  |

:::tip
An increase in the sum of High Risk Connections and Repeated Alerts since the last Daily Alert Summary indicates a raised risk for transactions.
:::
Users need to log in to their accounts on the Jumio Portal to access Alert Details. They will find the alerts listed under the Alert Management view.

## Alert Management on Portal

To view and manage Jumio Watch alerts directly from the Alert Management menu, click any alert in the list view to open its dedicated details page for a deeper look.

![](./images/AlertManagement.png)

### Available Actions

**1. Mute/Unmute:** Muting an alert prevents any further alerts of the same Alert Category and Risk Reason from being generated for the transaction. This allows you to manage future alerts if your investigations lead to an outcome that no further alerts of a similar type are necessary for this transaction.
![](./images/AlertMuteUnmute.png)

**2. Update Status:** To manage your work queue, mark an Alert as **“Closed”** once it has been reviewed and the investigation is closed. This will allow you to focus on Alerts that are still open. You can also toggle alerts between **Open** and **Closed**, as required. Closed alerts are excluded from all future reporting.

Alerts open for more than 30 days will automatically transition to **Expired** status.

![](./images/AlertClosed.png)

### Alert Details

The Alert Detail view provides the following information to users:

![](./images/AlertDetails.png)

| **Field**                   | **Description**                                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Transaction ID              | The unique ID of the alerted transaction                                                                               |
| Customer Internal Reference | The internal transaction reference provided when the transaction was processed                                         |
| User Reference              | The internal user account reference provided when the transaction was processed                                        |
| Jumio Account ID            | Unique user ID assigned by Jumio for each new user                                                                     |
| Current Transaction Status  | The original outcome of the transaction                                                                                |
| Alert Category              | Indicates the alert type; currently always shown as “Risk”                                                             |
| Alert Date                  | Date and time when the alert record was created                                                                        |
| First Alerted               | Date and time when the alert was first triggered for the same Alert Category and Risk Reason combination               |
| Last Alerted                | Date and time when the alert was most recently triggered for the same Alert Category and Risk Reason combination       |
| Alert Reason                | The risk reason behind the alert (e.g., a manipulated document linked to the transaction)                              |
| Alert Count                 | Number of times the alert was triggered for the same Alert Category and Risk Reason combination                        |
| Risk Connections            | Count of unique risky connected transactions contributing to the alert                                                 |
| Alert Status                | Current status of the alert (managed via the Alerts Management view)                                                   |
| Muted                       | If set to “Yes,” the transaction will not trigger alerts again for the same Alert Category and Risk Reason combination |

### Alert Information on Transaction Details Page

An overview of alerts for transactions can be viewed in the Transaction Summary View.

![](./images/AlertInfo.png)

The Alert Information section shows:

| **Field**            | **Description**                                                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Count of Alerts      | Number of alert records created for the selected transaction                                                                                                                                            |
| Alert Date           | Date when the alert was generated                                                                                                                                                                       |
| Risk Connections     | Count of connected risky transactions that contributed to the alert                                                                                                                                     |
| Alert Status         | Current status of the alerts (managed through the Alerts Management view)                                                                                                                               |
| Muted/Unmuted Status | Provides an option to mute all alerts for the transaction (not specific to Alert Category and Risk Reason) via the Alerts Management view. If set to “Muted”, the transaction will not be alerted again |

:::tip
A transaction with multiple alerts and an increasing number of risk connections indicates a raised risk for the transaction.
:::

#### Available Action

**Mute Transaction** - It provides an option to mute all alerts for the transaction and not for a specific Alert Category and Risk Reason, which is available through Alerts Management View. If “Muted”, then this transaction will not be alerted again.

![](./images/AlertInfoAvailableAction.png)

### Operational Recommendations for using Jumio Watch

#### Using the Daily Alert Emails

- In the configuration menu, specify users for whom receiving such email alerts ties in with their daily work (e.g., review of risky transactions).
- The sum of High Risk Connections and Repeated Alerts since the last Daily Alert Summary indicates a raised risk for transactions - those might indicate an emerging or already increasing large fraud event.

#### Using Alert Management in the Customer Portal

- In the configuration menu, specify users who you expect to investigate alerts and take action upon. The Alert Management view serves as a daily worklist in order to go through all open alerts, understand the reason for the alert, investigate, and take action on the user's account or transaction as per your organizational processes and policies.
- Take note that open alerts will be automatically updated whenever the same transaction receives another alert trigger for the same reason. Once an alert has been set to “closed”, no further updates will be processed under that same alert. Users should close an alert once they have taken the appropriate action as outlined by your internal policies & procedures.
- Alternatively, users can “mute” an alert. Such an alert will still receive updates, but you will not be alerted again via the daily alert summary. This can be helpful if users want to keep track of additional updates on the same alert, e.g., in order to see how often the same alert reason still keeps on showing. Please take note that an alert notification for the same transaction may still happen if a new alert is triggered for another risk reason.

#### Using Alert Information in the Transaction Details Page

- Users can use this view in order to understand and monitor alerts for a single transaction, e.g., how often it was alerted. To stop receiving alert notifications for a transaction entirely, users can set the transaction to “mute”.

---

# User Profile

https://documentation.jumio.ai/docs/portals/Multi-factor_Authentication/access_your_user_profile

# Login and Manage your User Profile

## Access Your User Profile

Your user profile displays information about your user account, such as your email address and the tenants and groups to which you belong.

### Option A: Access your User Profile

**Step 1:** Click your user icon in the menu bar and select **Profile**.  
![Click Profile](../images/click_profile_20240208.png)

### Option B: Access User Profile with Multiple Tenants

If your user profile is associated with multiple tenants, you can [switch between tenants](/docs/portals/Multi-factor_Authentication/multi-factor_auth#switch-tenants) from your user profile menu. Open your user profile, select the tenant you want to work with, and the portal updates your session to reflect the selected tenant. Your access, data, and available features are displayed based on the tenant you choose.

## Log in to the Portal

Your login experience may vary based on whether multi-factor authentication (MFA) is enabled for your organization and how many tenants are linked to your portal account. For more details, see [Multi-Factor Authentication](/docs/portals/Multi-factor_Authentication/multi-factor_auth) and [About Customers, Tenants, Users, and Groups](/docs/portals/settings/managingUserandTenant#about-customers-tenants-users-and-groups).

### **Step 1:** From the login page, enter your email address and click **Continue**.

![Login Step 1](../images/mfa_login_1.png)

### **Step 2:** Enter your password and click **Continue**.

If your organization has not enabled multi-factor authentication and your account belongs to a single tenant, the portal logs you in at this point and displays your dashboard.  
 ![Login Step 2](../images/mfa_login_2.png)

### **Step 3:** Verify Your Identity Using Multi-Factor Authentication

If your organization has enabled multi-factor authentication, the login page asks you to verify your identity. To do so, take the following steps:  
:::note
Make sure you have **[set up multi-factor authentication](/docs/portals/Multi-factor_Authentication/multi-factor_auth#set-up-multi-factor-authentication)** before taking steps A and B below.
:::

A. Open the authenticator app on your mobile device and obtain the code displayed for your Jumio account.

B. Enter the code in the field provided on the Jumio login page and click **Continue**. If your user profile belongs to a single tenant, the portal logs you in and displays your dashboard.

    ![Login Step 3](../images/mfa_login_3.png)

### **Step 4:** For User profile with Multiple Tenants

- If your user profile is associated with multiple tenants, the portal displays an additional sign-in page.
- Select a tenant from the list and click **Get your company login link**.
- Once authenticated, the portal logs you in and displays your dashboard.
  ![Select Tenant](../images/select_tenant_2_20240209.png)

---

# Multi-Factor Authentication (MFA)

https://documentation.jumio.ai/docs/portals/Multi-factor_Authentication/multi-factor_auth

# Multi-Factor Authentication

:::warning
If your organization has disabled Multi-Factor Authentication, you can ignore the information in this topic.
:::

The Jumio Portal provides Multi-Factor Authentication to ensure the safety of your data.

- [How Multi-Factor Authentication Works ?](#how-does-the-multi-factor-authentication-work)
- [Set-up Multi-Factor Authentication](#set-up-multi-factor-authentication)
- [Switch Tenants](#switch-tenants)

## How does the Multi-Factor Authentication Work?

Multi-Factor Authentication (MFA) adds an extra layer of security to your Jumio Portal login. After entering your email address and password (the first factor), you are required to provide a one-time verification code generated by an authenticator app on your mobile device (the second factor).

Jumio supports a variety of authenticator apps, including **Duo Mobile, Google Authenticator, Authenticator App by 2Stable, Authy, and LastPass Authenticator**.

When you sign in to the portal for the first time, you'll be prompted to [set up MFA](#setup-multi-factor-authentication) by scanning a QR code displayed on the screen using your authenticator app. Once scanned, the app registers your Jumio account and generates a one-time code. You must enter this code to complete the [login process](../Multi-factor_Authentication/access_your_user_profile#log-in-to-the-portal).

For all subsequent logins, you'll need to open your authenticator app and enter the current one-time code to access the portal.

For more information, checkout this Wikipedia article on [Multi-Factor Authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication).

## Setup Multi-Factor Authentication

Take the following steps to set up Multi-Factor Authentication and log in to the Jumio Portal for the first time.

**Step 1:** Click the link included in your welcome email from Jumio. You will be directed to the "Change Your Password" page.

![Change Password](../images/mfa_change_password.png)

**Step 2:** Follow the on-screen instructions to set your password, then click **Reset Password**. A confirmation page will appear.

![Password Changed](../images/mfa_password_changed.png)

**Step 3:** Click **Back** to Jumio Portal. You will be redirected to the portal login page.

**Step 4:** Enter your email address, then click **Continue**.

**Step 5:** Enter your password, then click **Continue**. The Jumio QR code will appear in your web browser.  
 ![QR Code](../images/mfa_qa_code.png)

**Step 6:** Open the Authenticator App on your mobile device.

**Step 7:** In the Authenticator App, select the option for creating a new account by scanning a QR code. For example, in Duo Mobile you would tap the **Add** icon on the home page and then select **Use QR code**.

**Step 8:** Using your mobile device's camera, scan the Jumio QR code displayed in your browser. Your Authenticator App displays a code.

**Step 9:** Enter the code in the field provided under the QR code and click **Continue**.

**Step 10:** If your user profile belongs to multiple tenants, the portal displays an additional sign-in page. If this is the case, select a tenant from the provided list and click **Get your company login link**. The Portal logs you in and displays your dashboard.

![Select Tenant](../images/select_tenant_2_20240209.png)

## Switch Tenants

If your user account belongs to multiple tenants, you can switch to a different tenant by taking the following steps.

1. Click your user icon in the menu bar and select **Profile**. Your user profile displays.
   ![Click Profile](../images/click_profile_20240208.png)
2. Click the **Tenant** list and select a different tenant.  
   ![Select Tenant](../images/select_tenant_20240209.png)

3. Click **Switch**. The portal switches to the other account and refreshes the page.

---

# Dashboard

https://documentation.jumio.ai/docs/portals/dashboard/about_the_dashboard

# Overview of the Dashboard

The Dashboard comprises a number of [widgets](/docs/portals/dashboard/widgets) that provide a global understanding of transactions and related data in the portal. Each widget focuses on a particular area of interest, such as transactions processed for each document or product type, the number of new customers your organization has processed through Jumio, or a breakdown of transactions processed in each country.

![Dashboard](../images/20231204_dashboard.png)

:::tip
Dashboard data reflects only the workflows that completed processing and resulted in a decision. If a decision is not made regarding a transaction (for example, if the workflow timed out), it will not be included in any of the Dashboard widgets.
:::

You can filter the data shown in the widgets by [selecting a time frame](/docs/portals/dashboard/configuration_options_for_your_dashboard#select-widgets-to-display-on-the-dashboard) from the dashboard. The selected time frame will be applied to all widgets.

:::tip
Because the Dashboard only starts collecting data at the time of its deployment, it will not be able to provide historical data from before that time.
:::

The widgets are interactive, allowing you to select an option that offers a different view of the information or hover over a map or graph to see more specific data. For example, the default view of the _Global Risk Analysis_ widget is a color-coded map you can hover over to view the traffic trend for a particular country's total transactions.

![Global Risk Analysis](../images/dashboard_gra_20230515.png)

If you select **Reject Rate**, the data displayed on hover changes to a breakdown of the number of transactions assigned a risk score of _Approved_, _Warning_, or _Rejected_.

![Reject Rate](../images/dashboard_gra_20230515_2.png)

Furthermore, you can change the map view to a list of countries by selecting **List**. Capabilities similar to these are found in the other widgets.

![List View](../images/dashboard_gra_20230515_3.png)

---

# Dashboard Configuration

https://documentation.jumio.ai/docs/portals/dashboard/configuration_options_for_your_dashboard

# Customize Your Dashboard Configuration

The following configuration options are available for your Dashboard,

## 1. Set the Dashboard Time Frame

By default, the Dashboard shows data for the previous day. You can select a different time frame in either of the following ways:

**Option 1:** Click the date range and select start and end dates from the calendar dropdown menu.

![Calendar](../images/20231204_dashboard_calendar.png)

**Option 2:** Click one of the time-frame options in the upper-right corner of the Dashboard.

![Time Frames](../images/20241204_dashboard_timeframes.png)

## 2. Rearrange Widgets on the Dashboard

You can rearrange the widgets on the Dashboard by clicking and dragging.

**Step 1:** Hover the pointer over the top edge of the widget until it changes to a four-headed arrow.  
 ![Move Pointer](../images/pointer_move.png)

**Step 2:** Click and hold down the mouse button.

**Step 3:** Drag the widget to a new location.  
 ![Move Widget](../images/20231206_move_widget.png)

**Step 4:** Release the mouse button. The widget drops into its new location, and the other widgets reorder accordingly.

## 3. Select Widgets to Display on the Dashboard

Take the following steps to add or remove widgets from the Dashboard.

**Step 1:** From the Dashboard, click **Edit Widgets**. The Edit Widgets page appears, displaying two widget categories: **General and Identity/KYC**

![](../images/20231206_edit_widgets.png)

**Step 2:** To expand a category of widgets click the arrow to the right of the category name. A dropdown list of that category's widgets displays.

![](../images/dashboard_edit_widgets_expanded.png)

**Step 3:** Take any of the following actions:

- To add a widget to the Dashboard, select its check box.
- To remove a widget from the Dashboard, clear its check box.
- To add all of a category's widgets to the Dashboard, select the check box next to the category name.
- To remove all of a category's widgets from the Dashboard, clear the check box next to the category name.

**Step 4:** Click **Apply**.

:::tip
To view a preview of a widget, click in the white space to the right of its name.
:::

---

# Widgets

https://documentation.jumio.ai/docs/portals/dashboard/widgets

# Explore Widgets

The Dashboard provides the following widgets. You can [choose to hide or display these as needed](/docs/portals/dashboard/configuration_options_for_your_dashboard#3-select-widgets-to-display-on-the-dashboard).

### 1. New Customers

The New Customers widget shows the number of new customers gained during the [selected time frame](/docs/portals/dashboard/configuration_options_for_your_dashboard) and the average gained per day, week, or month. A line graph maps the number of new customers over time.

New customers are broken down according to the following statuses:

- **Passed**: The customer’s initial transactionClosed was approved based on the score assigned by the workflow.
- **Rejected**: The customer’s initial transaction was rejected based on the score assigned by the workflow.
- **Warning**: The customer’s initial transaction was assigned a score by the workflow that flagged it for review.

:::tip
Jumio identifies a new customer when we receive a transaction from your organization that does not fall under an existing account.
:::

Hover over the graph to see the total number of new customers, along with their statuses (Passed, Rejected, Warning).

![New Customers](../images/new_customer_widget.png)

### 2. Channel Source

The Channel Source widget is a donut chart that reveals the percentage of transactionsClosed created during the [selected time frame](/docs/portals/dashboard/configuration_options_for_your_dashboard) through each integration channel your company uses to interface with Jumio. These channels could include any of the following:

1. **API**: Transactions created through Jumio's REST application programming interface (APIClosed). For more information see [REST APIs](/docs/developer-resources/API/).
2. **Mixed**: Transactions involving multiple channels. For example, if someone initiates a transaction using the Jumio Web client and then completes the transaction through the API, it would fall under the **_Mixed category_**.
3. **SDK**: Transactions created through mobile applications via the Jumio Software Development Kit (SDKClosed). For more information see [Mobile SDKs](/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile).
4. **Web**: Transactions created through the Jumio Web clientClosed. For more information see [Web Client](/docs/developer-resources/web-client/).

Hover over the graph to see the percentage of transactions by each channel.

![Channel Source](../images/channel_source.png)

### 3. KYC Transactions

The KYC Transactions widget displays the following data:

- **Total**: Number of KYC transactionsClosed your company has processed with Jumio during the [selected time frame](./configuration_options_for_your_dashboard) along with the percentage change over the same time frame of the previous year.

- **Average per day/week/mont**h: Average number of transactions processed per day, week, or month, along with the percentage change in this average over the same time frame of the previous year.

The bar graph shows the average number of KYC transactions per day, week, or month. Each bar is color-coded to show the breakdown of transactions by risk score or status. Use the Risk Score and Status buttons to toggle between the two categories.

At the bottom of the graph are the number of transactions for the selected time frame broken down by Risk Score or Status.

![KYC Transactions](../images/KYC_Transaction.png)

### 4. Transactions Per Product

The Transactions per Product widget shows the following data:

- **Total**: Total number of transactions, processed during the [specified time frame](./configuration_options_for_your_dashboard) along with the percentage change over the same time frame of the previous year.
- **Avg per day/week/month**: Average number of transactions processed per day, week, or month, depending on the selected time frame, along with the percentage change over the same time frame of the previous year.

The line graph shows the total number of transactions over time for each Jumio product purchased by your organization. At the bottom of the graph are the number of transactions for the selected time frame broken down by product.

Hover your pointer over the graph to view the numbers broken down for a single day, week, or month.

![Transactions Per Product](../images/Transaction_per_product.png)

### 5. Transactions Per Document Type

The Transactions per Document Type widget shows the following data:

- **Total**: Total number of transactions, processed during the [selected time frame](./configuration_options_for_your_dashboard) that included some type of document, along with the percentage change over the same time period of the previous year.
- **Avg per day/week/month**: Average number of transactions processed per day, week, or month, that included some type of document, along with the percentage change over the same time period of the previous year.

The line graph is color-coded to show the number of transactions over time involving each type of document. At the bottom of the graph are the number of transactions for the selected time frame broken down by document type.

Hover your pointer over the graph to view the numbers broken down by a single day, week, or month.

![Transactions Per Document Type](../images/per_Doc_type.png)

### 6. Capability Usage

The Capability Usage widget is a color-coded line graph showing the top five capabilities by volume of transactions during the [selected time frame](./configuration_options_for_your_dashboard). Capabilities not in the top five are grouped into the **Other** category.  
Hover your pointer over the graph to view the number of transactions for each capability in a particular time period.

![Capability Usage](../images/capability.png)

### 7. Global Risk Analysis

The Global Risk Analysis widget is an interactive map showing the following data for the [selected time frame](./configuration_options_for_your_dashboard),

![](../images/map1.png)

- **Traffic Trend**: The percentage change in the number of transactions processed through Jumio over the same time frame from the previous year.
- **Reject Rate**: Percentage change in the number of transactions rejected over the same time frame from the previous year.
- **Approval Rate**: Percentage of transactions from all countries that were approved.

Click the Traffic Trend or Reject Rate data field to show related data on the map.

With Traffic Trend selected, hover your pointer over the map to view a country’s total transactions for the current and previous periods (the same time frame from the previous year) as well as the trend, or percentage change between the two.

**Hover** over the map to see country-specific data. You can **switch between Traffic Trend** and **Reject Rate views**.

![](../images/globalAnalysis.png)

---

# Explorer

https://documentation.jumio.ai/docs/portals/explorer/explorer-overview

# Explorer

The Explorer portal allows you to view and interact with transactions.

![](../images/20231208_explorer.png)

---

# Create and View the Transaction

https://documentation.jumio.ai/docs/portals/explorer/viewing-transaction-details

# Create and View the Transaction

## Create a Transaction

Take the following steps to create a transaction manually within the Jumio portal.

**Step 1:** From the Transactions tab of the Explorer, click **Create Transaction**.

![Create Transaction Button](../images/create_transaction.png)

**Step 2:** On the Create a Transaction window, specify the workflow in either of the following ways:

:::tip
If you select the Document Verification workflow, the **Document Type** and **Document Country** fields under Advanced Settings are also required.
:::

**Option 1:** Select an option from the **Workflow** list,

![Select Workflow](../images/create_trans_select_wf_20240322_2.png)

**Option 2:** Enter a value in the **Workflow Key** field.

![Workflow Key](../images/create_trans_workflow_key_20240322.png)

**Step 3:** Select a value from the **Locale** list and enter values in the **User Reference** and **Customer Reference** fields. These fields are required. For descriptions of these, see [General Parameters](#general-parameters).

**Step 4:** Complete the remaining data fields at the top of the page as desired. For descriptions of the fields, see [General Parameters](#general-parameters).  
 ![Complete Data Fields](../images/20240320_create_transaction.png)

**Step 5:** To specify which rulesets will be used by the transaction to assign scores and decision labels, expand the Rules Management section of the page and enter the appropriate ruleset IDs. See [Rules Management](#rules-management) for descriptions of these fields.  
 ![Rules Management](../images/create_trans_rules_mgmt_20240320.png)

**Step 6:** To configure advanced settings, expand the Advanced Settings section of the page. See [Advanced Settings](#advanced-settings) for descriptions of these fields.  
 ![Advanced Settings](../images/create_trans_adv_settings_20240320.png)

**Step 7:** Click **Create**.

**Step 8:** If you are creating a workflow that allows for the submission of prepared data, the Customer Input (Prepared Data) section appears. For descriptions of these fields, see [Customer Input (Prepared Data)](#customer-input-prepared-data). Enter prepared data in either of the following ways:

- Enter the data in the fields provided on the **Individual Fields** tab and click **Submit**.  
  ![Individual Fields](../images/new_trans_prep_data_20240322.png)
- Select the **Entire JSON** tab, enter the data as a JSON object, and click **Submit**.  
  ![Entire JSON](../images/create_trans_prep_data_json_20240322.png)

**Step 9:** To test the workflow in your browser, click **Test**. The customer journey start page will display, allowing you to test the steps that your end user will be required to take during verification.

:::note
The **Test** button works only if you have selected one of the three workflows shown in the **Workflow** list. It will not work if you have entered a workflow key instead.
:::

![Test Button](../images/create_trans_test_20240325.png)

**Step 10:** The Jumio Portal creates the transaction and displays its transaction ID. If the workflow was configured to generate a URL for the transaction, the URL will display as well and will be automatically copied to your clipboard.  
 ![Transaction Created](../images/create_trans_success_20240320.png)

### Parameters of a Transaction

Following are descriptions of the parameters available when you are creating a transaction from the portal.

#### General Parameters

| Parameter          | Description                                                                                                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Workflow           | Select the workflow that will process the transaction. Options are as follows:<br /> - Standalone ID<br /> - Standalone ID and Identity Verification<br /> - Document Verification<br />Alternatively, you can enter a workflow key (see below). |
| Workflow Key       | You can enter a workflow key in this field instead of selecting one from the **Workflow** list.                                                                                                                                                  |
| Locale             | Select the default language that will be displayed in the web client for the end user.                                                                                                                                                           |
| User Reference     | Enter an ID you will use during searches and reporting to identify the end user who will scan their ID and selfie to perform this verification, such as a user’s internal customer ID.                                                           |
| Customer Reference | Enter an ID you will use during searches and reporting to identify this specific verification transaction.                                                                                                                                       |
| Reporting Criteria | Enter any additional data you want to use to track the verifications. This data will show up in callbacks and retrievals but not in the Jumio reports.                                                                                           |
| Token Lifetime     | Enter the time in minutes until the redirect link expires. The default value is 30 minutes.                                                                                                                                                      |

#### Rules Management

| Parameter                              | Description                                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| Ruleset ID for Decision Label          | Enter the UUID number of the ruleset to be used to assign decision labels to the transaction. |
| Ruleset ID for Risk Scoring            | Enter the UUID number of the ruleset to be used to assign risk scores to the transaction.     |
| Ruleset ID for Additional Risk Scoring | Enter the UUID number of the ruleset to be used for additional risk scoring.                  |

#### Advanced Settings

| Parameter                      | Description                                                                                                                                                                                         |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document Type                  | The type of document being verified (e.g., CC, PB, etc.). For a list of document types, see [Supported Documents](https://documentation.jumio.ai/docs/references/credentials/#supported-documents). |
| Document Country               | The country of the document being verified.                                                                                                                                                         |
| Watchlist Screening            | The watchlist screening search profile to be used in the request body. See [Watchlist Screening](https://documentation.jumio.ai/docs/references/capabilities/watchlist) for more information.       |
| Document Credential Extraction | Select _True_ or _False_ to indicate whether or not document credentials are to be extracted.                                                                                                       |

#### Customer Input (Prepared Data)

:::note
Customer Input parameters are available only when the selected workflow is configured to accept prepared data.
:::

This section allows you to submit prepared data for use by the workflow executing the transaction. Prepared data is used to upload values for data fields required by a capability or risk signal in a workflow, but not extracted from another credential such as an ID or document.

You can enter the prepared data either as values on the **Individual Fields** tab or as a JSON object on the **Entire JSON** tab.

See [Prepared Data](https://documentation.jumio.ai/docs/references/credentials/#data) for more information, including descriptions of individual fields and an example of a JSON object used to upload prepared data.

## View Transaction Details

To open a transaction, click the following icon to the right of the transaction name: ![](../images/explorer_open_trans_icon.png)

The transaction detail page displays the following information:

- Header information that includes the transaction ID, status, and detected date
- Summary details
- Service details

For example, the following screen capture shows a transaction with:

- Summary details including WARNING for the overall decision, and a risk score of 70.
- Services:

  - Global Identity Check
  - ID and Identity Verification
  - Device Risk Verification
  - Phone Verification
  - Email Verification

![](../images/20231207_trans_details.png)

Details for each service are presented in separate sections under the summary. The details are specific to each type of service, which may contain subsections for each capability executed by the service.

### View a Transaction's Triggered Rules

1.  Open the transaction

    :::tip
    Quickly locate the transaction by using the search or filter functions.
    :::

2.  Click the **Rules Triggered** link displayed in the upper-right corner of the _Transaction Summary_ section.  
    ![](../images/20231207_rules_triggered_link.png)  
    The Rules Triggered dialog displays.  
    ![](../images/20231207_triggered_rules.png)

3.  To open a triggered rule's ruleset, click the rule.

4.  To close the dialog, click **Close**.

### Transaction Event Log

#### About the Transaction Event Log

The event log shows the API calls that were made and the values that were returned during the processing of a transaction. The log provides the following information for each event:

|           | Description                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------- |
| Timestamp | The date and time in UTC at which the event occurred.                                          |
| Category  | Category number of the event.                                                                  |
| Label     | The label that the Jumio service or capability applied to the event at the time of processing. |
| Payload   | The payload of the JSON message that contained the event.                                      |

#### View a Transaction's Event Log

You can access the [transaction event log](About the Transaction Event Log.htm) from the transaction detail page.

1.  From the **Transactions** tab of the Explorer, locate the transaction whose event log you wish to view.

2.  Open the transaction by clicking the below icon to the right of the Transaction ID.  
    ![](../images/explorer_open_trans_icon.png)
    ![](../images/open_trans.png)

3.  Click the menu icon in the upper-right corner of the page and select **View Event Log**.  
    ![](../images/20231207_view_event_log.png)  
    The transaction event log displays.  
    ![](../images/20231207_event_log.png)

4.  To close the event log, click the **X** at the top of the page.  
    ![](../images/20231207_close_event_log.png)

## Transaction Feedback

After Jumio processes a transaction, you can review the decision and provide feedback if you believe it needs clarification or correction. This allows you to flag case where:

- If you believe a decision requires clarification or correction, you can assign a feedback status to the transaction and a reason for the feedback.

Providing feedback essentially tags the transaction to highlight the difference between the Jumio-assigned status and the status your organization believes is correct.

:::tip
Refer to [this](https://documentation.jumio.ai/docs/developer-resources/bestPractices/provide-feedback) section to know more about providing feedback.
:::

### How Feedback Affects Future Transactions?

When feedback is provided for transactions that include an [ID document](https://documentation.jumio.ai/docs/references/credentials/#id), it influences future evaluations for:

- Your tenant, and
- Any other tenants within the same Jumio customer account.

Feedback applies when future transactions match the same ID, based on:

- issuingCountry
- ID type
- documentNumber
- firstName
- lastName
- dateOfBirth

### Feedback Outcomes

If the feedback status was:

- _NOT_FRAUD_: Subsequent transactions with a valid ID with matching data will be approved (applies to the [Data Checks](https://documentation.jumio.ai/docs/references/capabilities/data-checks) capability).
- _FRAUD_: Subsequent transactions with a matching ID will be rejected, and the decision details label will be _CUSTOMER_FEEDBACK_.

You can assign both a [feedback status](#provide-feedback-on-a-transaction) and a [feedback reason](#feedback-reasons) directly in the UI.  
You can also submit feedback using [Jumio Feedback API](https://documentation.jumio.ai/docs/developer-resources/bestPractices/provide-feedback#feedback-request-body-example).

### Reject Reasons

| V3/KYX Decision Detail Label   | NEW KYX Decision Reason Label       |
| ------------------------------ | ----------------------------------- |
| CUSTOMER_FEEDBACK              | LOOKUPS_HIGH_RISK_CUSTOMER_FEEDBACK |
| MISMATCHING_DATA_REPEATED_FACE | LOOKUPS_HIGH_RISK_FACE              |
| MANIPULATED DOCUMENT           | LOOKUPS_HIGH_RISK_SAME_DATA         |

### View Feedback in Explorer

For a quick view of feedback in the Explorer, the following columns are available for you to add to the list of transactions:

- Feedback Status
- Feedback Reason
- Feedback Provided At  
  ![Feedback Columns](../images/feedback_columns_20240325.png)

### Provide Feedback on a Transaction

Take the following steps to provide feedback on a transaction.

:::note
You may assign a feedback status to a transaction more than once, but only the most recent status will be retained.
:::

1. From the transaction detail page, click the **Feedback Status** list and select one of the following options:

   - _Not Available_: Feedback is not provided. Select this option if you have already submitted a feedback status but then decided to remove it.
   - _Fraudulent_: The transaction is an instance of fraud.
   - _Not Fraudulent_: The transaction is not an instance of fraud.  
     ![Feedback Status](../images/feedback_select_status_20240325.png)

2. Select a feedback reason. For descriptions of these options, see [Feedback Reasons](#feedback-reasons).  
   ![Feedback Reason](../images/feedback_select_reason_20240325.png)

3. Click **Submit**.

**Learn more about providing feedback [here](https://documentation.jumio.ai/docs/developer-resources/bestPractices/provide-feedback).**

### Feedback Reasons

Following are descriptions of the reasons available for selection when you are [providing feedback on a transaction](#provide-feedback-on-a-transaction).

| Reason                 | Description                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Not Available          | No reason provided. Select this option if you have already submitted a feedback reason but wish to remove it.            |
| Account Takeover       | Unauthorized access to a user's account, often through hacking or stolen credentials.                                    |
| Company Policy         | Risks associated with non-compliance or violation of internal company policies and procedures.                           |
| First Party Fraud      | Deceptive activities where a legitimate account holder intentionally engages in fraud.                                   |
| Government Regulations | Risks arising from failure to comply with laws and regulations set by government authorities.                            |
| Identity Fraud         | Unauthorized use of someone's personal information to commit fraudulent activities.                                      |
| Insider Fraud          | Fraudulent activities carried out by individuals within an organization, exploiting internal access.                     |
| Money Laundering       | Concealing the origins of illegally obtained money, often involving complex financial transactions.                      |
| Payment Fraud          | Unauthorized or fraudulent transactions involving the use of payment methods.                                            |
| Phishing               | Fraudulent attempts to obtain sensitive information, such as usernames and passwords, by posing as a trustworthy entity. |
| Synthetic ID Fraud     | Creation of fictitious identities using a combination of real and fake information for fraudulent purposes.              |
| Third Party Fraud      | Fraudulent activities initiated by external entities not directly associated with the organization.                      |

## Download a Transaction as a PDF

From the [transaction detail page](#view-transaction-details), you can download a PDF version of the transaction.

1. From the **Transactions** tab of the Explorer, locate the transaction you wish to download.

2. Open the transaction by clicking the following icon to the right of the Transaction ID:  
   ![Open Transaction](../images/explorer_open_trans_icon.png)  
   ![Open Transaction Screenshot](../images/open_trans.png)

3. Click the menu icon in the upper-right corner of the page and select **Download**.  
   ![Download Transaction](../images/download_trans.png)  
   The portal saves a PDF version of the transaction to your **Downloads** folder.

---

# Work with the Transactions Table

https://documentation.jumio.ai/docs/portals/explorer/work_with_transaction_table

# Work with the Transactions Table

![](../images/20231208_explorer.png)

### Columns Available in the Explorer

The following data fields are available to display as columns in the Transactions table of the Explorer. You can [show or hide these columns as desired](Show or Hide Columns in the Explorer.htm).

| Column                      | Description                                                                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                        | Name of the end user involved in the transaction.                                                                                                                          |
| Transaction ID              | Unique identifier for the transaction.                                                                                                                                     |
| Date                        | Timestamp for the transaction.                                                                                                                                             |
| Status                      | Decision type assigned to the transaction to indicate the overall level of fraud risk.                                                                                     |
| Risk                        | Risk score assigned to the transaction by the workflow.                                                                                                                    |
| Customer Internal Reference | Identifier used during searches and reporting to identify this specific transaction.                                                                                       |
| Account ID                  | Unique identifier that is used to associate a set of credentials and transactions with a customer.                                                                         |
| Workflow Key                | Unique identifier for the Jumio workflow that processed the transaction.                                                                                                   |
| User Reference              | Identifier used during searches and reporting to identify the end user who scanned their ID and selfie to perform the verification, such as a user’s internal customer ID. |
| Wiped Out At                | Timestamp for when the personally identifiable information (PII) was deleted for the transaction.                                                                          |
| Feedback Status             | Feedback status assigned to the transaction by a user in the Jumio Portal.                                                                                                 |
| Feedback Reason             | Feedback reason selected by a user of the Jumio Portal.                                                                                                                    |
| Feedback Provided At        | Time stamp for assignment of feedback.                                                                                                                                     |
| Merchant GUID               | Unique identifier for the tenant under which the transaction was processed.                                                                                                |

### Filtering Data in the Explorer

#### Apply a Data Filter in the Explorer

1.  Add a new filter expression by taking one of the following steps:

    - Click **Add a filter**.  
      ![](../images/20241205_explorer_filter1.png)

    - Click the ellipsis icon in a column header and select **Filter**.  
      ![](../images/20241205_explorer_column_menu.png)

2.  Select a field. You can skip this step if you added the filter expression from a column header in step 1, as the field will already be selected based on the chosen column.  
    ![](../images/20241205_explorer_filter_field.png)

3.  If necessary, select an operator.  
    ![](../images/20231205_explorer_filter_operator.png)

    | ℹ️&nbsp;&nbsp; **Tip:** In most cases the appropriate operator will be selected automatically.
    |:----------|

4.  Enter or select a value.  
    ![](../images/20231205_explorer_filter_value.png)

    The page refreshes to show the transactions that meet the filter criteria.

5.  To add another expression, take the following steps:

    1.  Click **+**.  
        ![](../images/20231205_explorer_filter_+.png)

        The application adds a second expression which is ANDed to the first.

    2.  Select a field and operator and enter a value.  
        ![](../images/20231205_explorer_filter_second_exp.png)

    3.  Repeat steps a and b to add additional expressions.

    | ℹ️&nbsp;&nbsp; **Tip:** To remove an expression, click the **X** to the right of it.
    |:----------|

#### Remove a Filter

To remove a filter, click the **X** to the right of the filter expression. This will delete the expression and refresh the page to show the data without the filter applied.

![](../images/20231205_explorer_filter_X.png)

### Sort the Data in the Explorer

1.  From the transactions table, click the **Sort** button.  
    Two list boxes display.  
    ![](../images/20231204_dashboard_sort_button.png)

2.  From the first list, select the sort column.

3.  From the second list, select the sort order, either _Ascending_ or _Descending_.

4.  To close the list, click the **Sort** button again.

### Show or Hide Columns in the Explorer

You can choose which columns appear in the transactions table. For a list of all available columns, see Columns Available in the Explorer.

1.  From the transactions table, click the **Columns** button.

![](../images/20241204_explorer_columns.png)

Available columns display in a list. Columns that currently appear in the table are indicated by a green check mark.

2.  Show or hide columns as follows:

    - To add a column to the table, click it. A green check mark will appear next to it.

    - To hide a column, remove its check mark by clicking it.

    ℹ️&nbsp;&nbsp; :::tip
    You cannot hide the _Name_ column.:::

### Resize Columns in the Explorer

In some cases you may want to resize the columns in the Explorer to make it easier to view the data that is most important to you.

1.  From the transactions table, hover the pointer over the right edge of a column header until the pointer turns into a double-headed arrow.  
     ![](../images/20231205_explorer_resize_col.png)

2.  Click and drag the pointer to the left to make the column more narrow or to the right to make it wider. For example, in the following screen capture, we have widened the _Account ID_ column to reveal its full contents.  
     ![](../images/20231205_explorer_resize_col_account_id.png)

3.  Repeat steps 1 and 2 to resize other columns as needed.

### Freeze or Unfreeze the Name Column

You can freeze the _Name_ column in the Explorer so that it remains visible when you scroll left or right.

1.  From the transactions table, click the ellipsis icon to the right of the _Name_ column header and select the **Freeze** toggle.  
    ![](../images/20231205_explorer_freeze.png)

2.  To unfreeze the column, select the **Freeze** toggle again.

---

# Report

https://documentation.jumio.ai/docs/portals/report/reports-overview

# Reports

## Overview of the Reports

The Reports provide tools for users to [create](create_a_report) and [download](download_a_report) custom reports.

## Create a Report

1. From the Reports page, click **Create Report**.  
   ![Create Report](./images/20231205_create_report.png)

2. Complete the fields in the _Report Details_ section as follows:

   - **Report Name**: Enter a descriptive name.
   - **Available Fields**: Select one or more fields to include in the report.
   - **Date**: Select this toggle to include the current date on the report.
   - **Time**: Select this toggle to include the current time on the report.  
     ![Report Details](./images/20231205_create_report_details.png)

3. In the _Report Filters_ section, select the criteria that will be used to filter the report. You must specify at least one filter.

4. Click **Create Report**. The application generates the report and displays it on the Reports page. The report will show a status of _In Progress_ until it is completed, at which point the status will change to _Success_.

## Download a Report

Take the following steps to download a report.

1. From the Reports page, locate the report you wish to download.

2. Click the menu icon at the end of the report's row and select **Download**.  
   ![Download Report](./images/20231205_create_report_download.png)
3. The application saves the report in your **Downloads** folder.

## Delete a Report

:::caution
You cannot undo the deletion of a report. Make sure you do not need the report before deleting it.
:::

1. From the [Reports page](overview_of_the_reports_page), locate the report you wish to delete.

2. Click the menu icon at the end of the report's row and select **Delete**.  
   ![Delete Report](./images/20231205_delete_report.png)

3. Click **Confirm** in the confirmation dialog and the selected report will be deleted.

---

# Enhanced Reporting on Jumio Portal User Guide

https://documentation.jumio.ai/docs/portals/report/advancedReport

# Overview - Advanced Reporting

This document provides a detailed specification of the Enhanced Reporting feature, recently launched on the Jumio Portal for customers in the APAC region.

The Enhanced Reporting system is a complete overhaul of our reporting infrastructure, designed to solve the core challenges of manual redundancy, lack of automation, and non-adaptive interfaces. This revamped system provides a more efficient, automated, and customizable experience for managing transaction data.

## Key Challenges and Solution

The new system addresses three primary pain points identified in legacy reporting:

- Manual Redundancy: Users no longer need to repeatedly recreate the same reports or manually select fields and filters for every execution.
- Lack of Automation: The revamp introduces scheduled report generation and delivery, removing the need for manual intervention.
- Non-Adaptive Interface: Unlike the legacy system that showed all available fields regardless of relevance, the new interface adapts to customer-specific settings.

## Core Features

The Enhanced Reporting suite includes several powerful new tools:

- Beta Launch in APAC: Exclusively available to customers in the APAC region as of February 3rd.
- Report Templates: Allows users to save, manage, and reuse specific configurations to ensure consistency.
- Scheduled Reports: Users can set reports to run at predefined frequencies.
- Contextual Filters: Filters for third-party checks only appear if that specific integration is enabled for your tenant.
- PII Data Control: A new role-level permission allows administrators to enable or disable the viewing and downloading of Personally Identifiable Information (PII).

## Getting Started

To access the new features, log in to your portal and look for the new "Reporting" option added to the Left Navigation Menu.

The new Reporting menu features three sub-sections: Reports, Scheduled Reports, and Templates.
![](./images/1.png)

### Creating and Managing Templates

Templates are designed to save time by capturing your preferred report settings.

**Step 1**: Navigate to the Templates section.
![](./images/2.png)

**Step 2**: Click “Create New Template”.
![](./images/3.png)

**Step 3**: Provide a template name.

**Step 4**: Select your desired fields and filters.
![](./images/4.png)

**Step 5**: Save the configuration for future use.
![](./images/5.png)

**Step 6**: Preview existing templates to view the list of fields and filters.
![](./images/6.png)

![](./images/7.png)

### Scheduling a Report

To eliminate manual creation for recurring needs:

**Step 1**: Open the Scheduled Reports page.
![](./images/scheduleReport.png)

**Step 2**: Click “Schedule Report.”
![](./images/8.png)

**Step 3**: Enter the report name.

**Step 4**: Select a saved Template.

**Step 5**: Set the Frequency for automatic generation.
![](./images/9.png)

**Step 6**: You can manage your scheduled reports using the Edit, Delete, and Enable/Disable options found within the page.
![](./images/10.png)

### Create Report

To create a new report:

**Step 1**: Navigate to the Reports page from the left navigation menu.
![](./images/11.png)

**Step 2**: Click the Create Report button.
![](./images/createReport.png)

**Step 3**: Enter a descriptive Report Name.

**Step 4**: Select a Template (optional): Choosing an existing template will automatically populate the predefined fields and filters.
![](./images/selectTemplate.png)

**Step 5**: Define your desired Date Range.
![](./images/dateRange.png)

**Step 6**: Click Create Report to generate the file.

:::tip
You can simultaneously save your settings for future use by selecting the Create Template and Report option.
:::

### Performance Benchmarks

The new system offers a 75% improvement in report generation speed:

| Metric                            | Legacy Reporting | Enhanced Reporting |
| --------------------------------- | ---------------- | ------------------ |
| Time to create report (~10m txns) | ~8 hours         | ~2 hours           |

:::note
There is currently a maximum cap of 5 million transactions per report in the enhanced system.
:::

### Important Considerations

System Separation: Reports created in the new Enhanced Reporting system are not visible in Legacy Reporting, and vice versa. This ensures a clean transition between systems.

---

# Workflow Designer

https://documentation.jumio.ai/docs/portals/workflowDesigner/WorkflowDesigner_intro

# Introduction to Workflow Designer

The Jumio Workflow Designer empowers organizations to create, manage, and optimize end-to-end verification workflows tailored to their unique business requirements. These workflows help ensure compliance with regulatory standards while enabling risk evaluation for every customer interaction. A workflow in Jumio represents a configurable process that orchestrates the execution of various services, risk signals, and decision points in a seamless manner.

## Jumio Workflow

A Jumio workflow is a structured sequence of connected steps, where each step represents a modular service, risk signal, or decision logic. Together, these steps define how identity data is collected, verified, and evaluated throughout the user verification journey. The workflow executes these steps in a predefined order to achieve specific outcomes, such as onboarding a user, approving an action, or flagging a transaction for further review.
Each workflow step can involve:

<ul>
<li>**Service Primitives:** Core Jumio capabilities like ID document verification, face match, or AML screening.</li>

<li>**Risk Signals:** Signals derived from AI models or external sources to assess fraud risk (e.g., IP reputation, email risk, device fingerprint).</li>

<li>**Decision Logic:** Conditional routing using If/Else conditions or custom expressions to adapt flow based on real-time input.</li>
</ul>

### Types of Jumio Workflow

In Jumio, there are two types of workflows you can create, depending on your business needs and level of customization required:

#### 1. Global Workflows

These are pre-configured, reusable workflows provided by Jumio. They are designed to support common industry use cases and offer a quick way to get started. Global Workflows can be used out of the box or serve as templates that you can customize to fit your verification processes.

#### 2. Custom Workflows

These workflows are tailored specifically to your organization’s requirements. With the help of your Jumio Solutions Engineer (SE), you can build workflows that combine multiple services, risk signals, and decision logic to address specific regulatory, compliance, or risk management goals.

### Key Benefits

**No-code Design:** Intuitive drag-and-drop builder for configuring and managing workflows.

**Rapid Integration:** Easily connect multiple primitives into a single orchestrated process.

**Scalability**: Design workflows to handle millions of verifications with consistent results.

**Transparency:** Visualize and test workflows before deployment, ensuring accuracy and efficiency.

### Example Use Case

A standard **ID + Selfie** workflow may include,

1. ID Document Acquisition
2. Selfie Capture
3. Face Match Verification
4. Risk Signal Checks
5. Decision Logic and Outcome

Each of these is implemented as a modular primitive and can be customized, rearranged, or extended to meet your business logic requirements.

For further reference:

- **Integrating Jumio Services:** [Learn](https://documentation.jumio.ai/docs/developer-resources/API/Integration_Intro) how workflows are used within broader transaction flows.
- **ID + Selfie Verification Workflow:** Detailed [example](https://documentation.jumio.ai/docs/quickStart/ID_SelfieVerification) of a common standard workflow.

---

# Step-by-Step Guide

https://documentation.jumio.ai/docs/portals/workflowDesigner/StepsInvolved

import Img1 from './images/01.png';
import Img2 from './images/02.png';

# Getting Started

The Jumio Workflow Designer is a no-code, visual tool for building and managing identity verification workflows tailored to your compliance and risk requirements. This section covers how to access, create, publish, and run your first workflow.

## Step-by-Step Guide

## 1. Access the Workflow Designer

To access the Workflow Designer,

**Step 1:** Log in to your Jumio Portal using your organization’s credentials.

**Step 2:** From the top left navigation bar, select Workflow Designer.

**Step 3:** Choose between the Global Workflows or Custom Workflows tab depending on your requirements.

:::info
Access to the Workflow Designer may be permission-based. If you don't see the option, contact your Jumio administrator or Solutions Engineer.
:::

<img src={Img1} style={{width: '300px', border: '1px solid #ccc', display: 'block', margin: '0 auto'}} />

## 2. Create a New Workflow

To create a workflow,

**Step 1:** Select the workflow type

- **_Global Workflow:_** Use or customize Jumio’s pre-configured workflows.
- **_Custom Workflow:_** Start from scratch to meet specific business needs.
  <img src={Img2} style={{width: '400px', border: '1px solid #ccc', display: 'block', margin: '0 auto'}} />

**Step 2:** Click the Create Workflow button, then select Create New Workflow.

**Step 3:** Once the workflow is created, provide a name to identify it.

**Step 4:** Now, your first workflow has been successfully created, and a unique workflow key has been generated.

### 2.1 Upload a Workflow

The **Workflow Designer** allows you to upload workflows in **JSON format**, making it easy to create new workflows from existing configurations. This feature is especially useful for **reusing, sharing, or modifying workflow** across environments or teams.

When you **upload a workflow**, the system automatically creates a new workflow and assigns it the next available workflow key in the sequence. The uploaded workflow behaves exactly like any workflow created directly within the Workflow Designer; you can **review its configuration, test it, and edit and publish** it when ready.

**Step 1:** Download an Existing Workflow

To begin, download the workflow configuration you want to reuse:

- Open any existing workflow in the Workflow Designer.
- From the right-side menu, click **Download**.
- The workflow will be downloaded to your device as a **JSON file**.
  ![](images/07.png)

**Step 2:** Open the Workflow Designer

- Navigate to the Workflow Designer in the Portal.
- Click Create Workflow.
- In addition to creating a workflow from scratch, a new option, **Upload Workflow**, will be available.
  ![](images/08.png)

**Step 3:** Upload the Workflow File

- Select **Upload Workflow**.
- Drag and drop the downloaded JSON file into the upload window, or use the Browse option to select it from your system.
- Click **Upload** to proceed.
  ![](images/09.png)

**Step 4:** Review and Finalize

- A new workflow will be created using the uploaded configuration.
- Review the workflow settings to ensure they meet your requirements.
- You can edit the workflow, run tests, or publish it as needed.
  ![](images/10.png)

This process enables faster workflow creation while maintaining full flexibility to customize and validate workflows before they are used in production.

## 3. Navigate the Interface

The Workflow Designer interface consists of,

**1. Canvas:** The main area where you drag and drop primitives (building blocks) to build your workflow.

**2. Component Panel:** A sidebar containing all available primitives such as acquisition steps, verification services, risk checks, decision logic, and endpoints.

**3. Properties Panel:** Displays for each node, allowing you to review basic or advanced configurations and make edits as needed.

**4. Canvas Control Toolbar:** Allows you to zoom in/out, center the workflow, lock/unlock the canvas.

**5. Action Bar:** Located at the top or corner of the interface, the Action Bar contains primary workflow actions such as Save and Publish.

- **a. Save:** Stores the current draft without making it live.
- **b. Publish:** Finalizes and activates the workflow for use in production.
  ![](images/Navigation3.png)

## 4. Understand the Workflow Structure

- **Acquisition Primitives:** The entry point that defines how a user submits their information (e.g., scans an ID, uses an API).
- **Primitives:** The individual checks performed within the workflow, such as "verify ID," "capture selfie," or "check device risk."
- **Decision Points:** Branching logic (If/Else) that changes the workflow's path based on the results of the primitives.
- **Risk Calculation Point:** A step that aggregates the results from all checks to generate a single, overall risk score for the entire transaction.
- **Terminal Node:** Indicates the end point of the workflow where the verification process concludes.

### 4.1. Properties Panel of Workflow Primitives

#### 1. Acquisition Stage

The **Acquisition Stage** setting defines where a workflow fits within the user's overall verification journey. It supports two modes:

- **Initial:** Marks the start of a user's identity verification process. Used when collecting identity data for the first time, e.g., during onboarding with ID and selfie capture.
- **Intermediate:** Used in multi-phase journeys where prior verification has occurred. Ideal for follow-up steps like requesting additional documents (e.g., proof of address).

By configuring this setting, you can design seamless, multi-step verification workflows that align with your customer lifecycle, ensuring flexibility, reducing user friction, and maintaining compliance.

#### 2. Acquisition Type

The **_Acquisition Type_** setting defines how user credentials are collected in a workflow either by capturing **new inputs** or by **reusing existing verified data** from a prior transaction.

- **Acquire New**: Prompts the user to submit fresh credentials (e.g., ID and selfie). Ideal for first-time verifications or onboarding flows.

- **Use Existing**: Reuses credentials from a previous successful transaction. Useful for returning users in multi-step journeys. e.g., re-authenticating with a selfie while referencing an already verified ID. **For details, check out [this](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/using-existing-credential) section**.

- **Reusable Identity**: Reuses a pre-verified ID (if the user has already been verified successfully before and is trusted), or Continues with a fresh ID scan (if no pre-verified qualified ID is found or risk is detected). For more details, refer to [selfie.DONE](https://documentation.jumio.ai/docs/quickStart/selfieDone).

By choosing the appropriate acquisition type, you can reduce user friction, streamline verification flows, and maintain strong security standards.

#### 3. Select Capabilities

The Select Capabilities setting allows you to define the specific verification checks to be performed on an end user’s identity document (ID) within the ID_IV (Identity Verification) primitive. This ensures each workflow is tailored to your security, compliance, and business requirements.

<details>

<summary>**Expand the list below for available Capabilities**</summary>

| Capability         | Description                                                                                                                                                                                                            | Dependencies / Prerequisites                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Usability**      | Image Quality Assurance – Ensures ID/document images are clear (not blurry, no glare) for accurate processing. Document Identification – Determines document country/type (auto-detected or provided by API/end-user). | None                                                                  |
| **Extraction**     | Data Capture – Extracts key data using OCR, barcode scan, or MRZ reading.                                                                                                                                              | Requires **Usability** checks to pass first.                          |
| **Image Checks**   | Fraud Detection – Forensic analysis to detect digital tampering, physical alteration, or fake/sample IDs.                                                                                                              | Requires **Usability** and **Extraction** to pass.                    |
| **Data Checks**    | Data Integrity Verification – Validates MRZ checksum, expiration dates, and consistency of extracted data.                                                                                                             | Requires **Usability**, **Extraction**, and **Image Checks** to pass. |
| **Liveness**       | Presence Verification – Confirms a real person is present using selfie analysis to block spoofing attempts (screens, prints, masks).                                                                                   | Selfie must first pass **Usability**.                                 |
| **Similarity**     | Face Matching – Compares the ID face with selfie to confirm identity of the user.                                                                                                                                      | Both ID and selfie images must pass **Usability**.                    |
| **Authentication** | Returning User Verification – Matches a new selfie/facemap against a previously stored facemap.                                                                                                                        | Requires an existing facemap and selfie passing **Liveness**.         |

</details>

#### 4. Channels

The Channels setting in Jumio Workflow Designer determines how end users submit their credentials and interact with the verification flow. This configuration ensures the workflow aligns with your platform, whether it's web, mobile app, or backend-driven integration. Jumio supports three primary channels,

| **Type** | **What it is**                                                                                                                                            | **When to use**                                                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **API**  | Direct backend integration using REST APIs to submit images and data captured via your own interface.                                                     | Ideal for fully custom workflows where you manage the UI, capture, and consent. Best suited for advanced, backend-controlled use cases. |
| **Web**  | A hosted, ready-to-use Web Client that guides users through the verification process with camera access and real-time feedback.                           | Best for fast, low-effort web integration. Jumio manages the UI, captures experience, and updates, so no maintenance is required.       |
| **SDK**  | Native SDKs for iOS and Android, along with a customizable Web SDK. These offer features like autocapture, liveness detection, and full branding support. | Web SDK is recommended for web apps that require self-hosted, customized UI journeys.                                                   |

#### 5. Parts

The Parts setting defines which sides of an ID document users must capture.

- **Front Only:** Use for single-sided documents like passports or national IDs. Simplifies the capture process.
- **Front and Back:** Required for two-sided IDs like driver’s licenses. Ensures complete data extraction and fraud checks.

#### 6. Parts (Data Acquisition)

- **Device Risk:** Collects device signals like IP, OS, and location to assess fraud risk. Useful for onboarding and transaction protection.
- **Prepared Data:** Accepts user data (e.g., email, phone) via API for verification without document capture. Ideal for standalone checks.

#### 7. Label

Use Labels to identify multiple credentials in the same workflow uniquely. This is essential when collecting more than one document from a user (e.g., both passport and national ID). Labels help clearly distinguish each credential in API responses and verification results. In single-ID workflows, labels are optional.

## 5. Credential References

The documents, scanned images, or data that are evaluated by a Jumio workflow are called Credentials. Each Jumio capability specifies the Credential(s) it can evaluate. The required credentials for each capability that is invoked by a workflow must be uploaded to the end-user accountClosed prior to initiating the workflow.

Supported credential types include,

- ID
- Selfie
- Facemap
- Document
- Data

:::tip
For detailed information about each credential type, refer to this **[page](https://documentation.jumio.ai/docs/references/credentials/)**.
:::

## 6. Save and Publish the Workflow

- Save the workflow at any stage without impacting live transactions. While in this state, the workflow status remains **Draft**.
- When you're ready to make the workflow active, publish it. Upon publishing, the workflow status updates to **Published**, making it available for use in transactions.
- Jumio supports **version control**, allowing you to track changes or duplicate versions.

## 7. Launch the Workflow

After publishing your workflow follow the steps below,

### 7.1. Navigate to the Transactions Page

**Step 1:** Go to the **Transactions** tab in the **Explorer** section of the Jumio Portal.

**Step 2:** Click on **Create Transaction**.
![](images/04.png)

### 7.2. Select the Workflow

**Step 1:** You can specify the workflow in one of the following ways:

- **From the Workflow List:** Select a workflow from the available list.
  :::note
  If you select the "Document Verification" workflow, you'll also need to fill in the **Document Type** and **Document Country** fields under **Advanced Settings**.
  :::
- **By Workflow Key:** Enter the unique **Workflow Key** associated with a previously published workflow.

### 7.3. Enter Required Details

**Step 1:** Fill in the following mandatory fields such as **Locale, User Reference, Customer Reference**.

**Step 2:** For details on these fields, refer to the General Parameters section.

**Step 3:** You can also fill in **additional optional fields** as needed.
![](images/05.png)

### 7.4. Add Ruleset Configuration(Optional)

If applicable, you can define which Rulesets should be used for this transaction:

**Step 1:** Expand the Rules Management section.

**Step 2:** Enter the appropriate Ruleset IDs to control how scores and decision labels are assigned.

### 7.5. Configure Advanced Settings(Optional)

**Step 1:** Expand the Advanced Settings section to specify additional parameters such as document handling, expiration settings, or compliance options.

**Step 2:** See Advanced Settings for field descriptions.

### 7.6. Create the Transaction

**Step 1:** Click **Create** to initiate the Transaction.

### 7.7. Enter the Data(Conditional)

- If the selected workflow allows **support data submission**, the **Customer Input** (Data) section will appear.
- You can provide data in two ways,

  - **Individual Fields Tab:** Manually enter data into the available fields and click Submit.
  - **Entire JSON Tab:** Paste your full input as a JSON object and click Submit.

- For field definitions, refer to [Customer Input (Data)](https://documentation.jumio.ai/docs/references/credentials/#supported-fields).

### 7.8. Test the Workflow (Optional)

**Step 1:** Click the **Test button** to simulate the customer journey directly in your browser. This allows you to experience the steps an end user would go through during verification.
:::warning
The Test feature is only available if you selected a workflow from the list. It does not work when entering a workflow key manually.
:::

### 7.9. View Transaction Details

After the transaction is created,

**Step 1:** A unique **Transaction ID** is displayed.

**Step 2:** If the workflow is configured to generate a **customer-facing URL**, it will be displayed and automatically copied to your clipboard.

## 8.Workflow Listing

​​The Workflow Listing screen provides a centralized view of all workflows created in your Jumio account, whether Global or Custom. From this screen, you can search, filter, and manage workflows efficiently, including accessing specific versions, reviewing statuses, and initiating edits.
![](images/06.png)

| Column       | Description                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow Key | A unique identifier automatically assigned to each workflow as per the use case.                                                                                                                                                                                                                                                                                                                  |
| Name         | The custom or default name assigned to the workflow, used for easy identification and organization.                                                                                                                                                                                                                                                                                               |
| Version      | Displays the current version number of the workflow (e.g., Version 1.0, Version 2.0). The latest version is shown by default in the listing. You can view and access previous versions by clicking the version label in the same row.                                                                                                                                                             |
| Created Date | Date and time when the workflow was initially created.                                                                                                                                                                                                                                                                                                                                            |
| Updated Date | Date and time of the most recent update made to the workflow.                                                                                                                                                                                                                                                                                                                                     |
| Status       | Displays whether the workflow is in Draft (editable) or Published (active).                                                                                                                                                                                                                                                                                                                       |
| Created By   | Email address of the user who originally created the workflow.                                                                                                                                                                                                                                                                                                                                    |
| Updated By   | Email address of the user who last modified the workflow.                                                                                                                                                                                                                                                                                                                                         |
| Action       | Accessible via the three-dot icon in each workflow row, provides options to manage individual workflows. The available actions include:<ul><li><strong>Edit Workflow:</strong> Open the workflow in the designer for editing.</li><li><strong>Upload:</strong> Replace or update the workflow using a JSON file.</li><li><strong>Download:</strong> Export the workflow as a JSON file.</li></ul> |

## 9.Capabilities References

Jumio transactions execute workflows that pass a set of credentials associated with an end-user account to a sequence of capabilities. Each capability evaluates one or more types of credentials and renders a decision about each credential or credential part that it evaluates, along with supporting details about the decision.

For each capability there is information about,

- Dependencies on other capabilities.
- Prerequisites for using the capability (if any)
- Supported credential types.
- The textual labels that may be returned to support the decision.
- Other data that is returned (if any)

:::tip
For additional information refer to detailed, [Capabilities](https://documentation.jumio.ai/docs/references/capabilities/).
:::

---

# Settings

https://documentation.jumio.ai/docs/portals/settings/managingUserandTenant

# Overview of Settings

If your user account belongs to a group with **Administrator** privileges, you can access the **Settings** section of the Jumio Portal to:

- [Manage users](/docs/portals/settings/managingUserRuleGroup) within your tenant.

- [Manage the groups](/docs/portals/settings/managingUserRuleGroup#managing-groups) your users belong to.

- View or modify the [Identity Verification configurations](/docs/portals/settings/managingUserandTenant#about-the-identity-verification-settings) that govern how your applications integrate with Jumio services.

- Review the [audit log](/docs/portals/settings/auditLog) to track activity in the Jumio Portal.

## About Customers, Tenants, Users, and Groups

Access to Jumio Portal is controlled through customers, tenants, users, and groups. A customer is a parent organization that owns one or more tenants. Each tenant has their own set of configuration options for the Portal and integrations. A user belongs to a customer, and may have access to one or more of the tenants belonging to the customer. A group represents a set of permissions, and a user may be assigned to one or more groups.

When a new customer joins Jumio, a new user is created with admin privileges, and a default tenant is created for the customer.

If a user belongs to multiple tenants, they will have the option to select a tenant at login. While logged in, a user can switch tenants from their user profile.

**For details on how to manage users, groups, and roles, see the [related section](/docs/portals/settings/managingUserRuleGroup)**.

## About the Identity Verification Settings

The Identity Verification settings control many aspects of your integrations with Jumio services and integration channels. Typically, these settings are determined by you and a Jumio Solution Engineer, and the initial settings are entered by Jumio administrators as part of the customer onboarding process. You can view the settings in the Portal. In some cases you can directly edit the settings in the Portal page. For other settings you need to contact Jumio Support to request changes.

- [Application Settings](/docs/portals/settings/aboutIDVSettings#application-settings) specify technical aspects of how your applications interacts with the Jumio APIs.
- [Customize Client](/docs/portals/settings/IDVSettings#customize-client) allows you to control the branding and other aspects of the user interface (UI) that is presented to your end users by the Jumio Web Client and SDKs.
- [API Credentials](/docs/portals/settings/IDVSettings#api-credentials) provides access to the credentials your integrations require to access the Jumio APIs.
- [App Showcase](/docs/portals/settings/IDVSettings#app-showcase) provides a QR code you can scan to initiate a transaction with the Jumio Showcase application.
- [Data Settings](/docs/portals/settings/IDVSettings#data-settings)control what data is extracted and stored and how long it is retained.
- [Watchlist Screening](/docs/portals/settings/IDVSettings#watchlist-screening) provides credentials and other settings for using the Watchlist Screening capability.
- [Document Verification](/docs/portals/settings/IDVSettings#document-verification) specifies the types of documents other than government-issued IDs that you accept.
- [Accepted IDs](/docs/portals/settings/IDVSettings#accepted-ids) allows you to choose the countries and ID types you want to accept.
- [Supported IDs](/docs/portals/settings/IDVSettings#supported-ids) provides a list of all the IDs supported by Jumio.

---

# Manage Users, Groups and Roles

https://documentation.jumio.ai/docs/portals/settings/managingUserRuleGroup

# Manage Users, Groups and Roles

## Managing Users

### Create a User

1. From the Users page, click Create User.
   ![Create User](../images/20231206_create_user.png)
2. Enter the user's email address.
3. Click the **Group** field and select one or more groups to which the user should be assigned. <br />A second row of fields appears.
4. Repeat steps 2 and 3 to add additional users.
5. Click **Invite**.<br />
   The portal sends an email to each new user with a link allowing them to register and set their password.

### Edit a User's Group Assignments

A user's group assignments determine the user's permissions in the portal (see Managing Groups). Take the following steps to change these assignments.

1. From the Users page, click the user's **Groups** field. A dropdown list of groups displays.
   ![User](../images/20231206_user_group.png)
2. Make changes as follows:

- To remove a user from a group, clear the group's check box.
- To add a user to a group, select the group's check box.

### Download a List of Users

To download a list of users as a CSV file, click the download icon in the upper-right corner of the Users page. The portal will save the file to your Downloads folder.
![Download](../images/20231206_download_list.png)

## Managing Groups

The Groups page lists the predefined groups that determine which portal features users can access. Each group is assigned one or more roles, each of which has a unique set of permissions. When you add a user to a group, the user is granted the permissions available to the group's roles.
![Managing Groups](../images/settings_groups_page.png)

### Groups and Roles

The following table lists the groups available in the Jumio Portal as well as the roles assigned to each. For a list of permissions available to each role, see Permissions Available to Roles.

| Group                | Roles                      |
| -------------------- | -------------------------- |
| Admin                | KYX Admin                  |
| KYX Admin            | KYX Admin                  |
| Sub Admin            | Sub Admin                  |
| Risk Admin           | Risk Manager<br/>Sub Admin |
| Risk Manager         | Risk Manager               |
| Risk Analyst         | Risk Analyst               |
| Risk Analyst Limited | Risk Analyst Limited       |
| Initiator            | Initiator                  |
| Accountant           | Accountant                 |

### Permissions Available to Roles

Following are key permissions available to each role on various pages of the portal.

#### Quick Role Overview

Use the descriptions below to match roles with the responsibilities of your team members. For full permission details, see the table below.

<details>
  <summary><strong>Admin / KYX Admin</strong></summary>
  <p><strong>Permissions:</strong> Full access to create, view, and delete transactions, dashboards, reports, and settings.</p>
  <p><em>Typical Users:</em> Power users, team leads, technology staff.</p>
</details>

<details>
  <summary><strong>Risk Admin</strong></summary>
  <p><strong>Permissions:</strong> Similar to Admin but cannot delete transactions. Can manage users and settings.</p>
  <p><em>Typical Users:</em> Risk managers, tech admins.</p>
</details>

<details>
  <summary><strong>Risk Manager</strong></summary>
  <p><strong>Permissions:</strong> Similar to Risk Admin with a functional focus on oversight. Use this role to differentiate responsibilities.</p>
  <p><em>Typical Users:</em> Operations or compliance leads.</p>
</details>

<details>
  <summary><strong>Risk Analyst</strong></summary>
  <p><strong>Permissions:</strong> Can create and view transactions, and access dashboards. Cannot delete or access all settings.</p>
  <p><em>Typical Users:</em> Identity verification analysts.</p>
</details>

<details>
  <summary><strong>Risk Analyst Limited</strong></summary>
  <p><strong>Permissions:</strong> Same as Risk Analyst, but with no access to personally identifiable information (PII) such as ID documents or selfies.</p>
  <p><em>Typical Users:</em> External service providers, support staff.</p>
</details>

#### Dashboard

| Feature            | ADMIN | KYX <br />ADMIN | SUB  <br />ADMIN | RISK  <br />ADMIN | RISK  <br />MANAGER | RISK  <br />ANALYST | RISK  <br />ANALYST <br />LIMITED | INITIATOR<br/>\* | ACCOUNTANT |
| ------------------ | ----- | --------------- | ---------------- | ----------------- | ------------------- | ------------------- | --------------------------------- | ---------------- | ---------- |
| View the Dashboard | ✅    | ✅              | ✅               | ✅                | ✅                  | ✅                  | ✅                                | ✅               | ✅         |

#### Transactions

| Feature                  | ADMIN | KYX <br />ADMIN | SUB  <br />ADMIN | RISK  <br />ADMIN | RISK  <br />MANAGER | RISK  <br />ANALYST | RISK  <br />ANALYST <br />LIMITED | INITIATOR<br/>\* | ACCOUNTANT |
| ------------------------ | ----- | --------------- | ---------------- | ----------------- | ------------------- | ------------------- | --------------------------------- | ---------------- | ---------- |
| View transactions        | ✅    | ✅              |                  | ✅                | ✅                  | ✅                  | ✅                                | ✅               | ✅         |
| View transaction details | ✅    | ✅              |                  | ✅                | ✅                  | ✅                  | ✅                                | ✅               |            |
| Delete transaction       | ✅    | ✅              |                  |                   |                     |                     |                                   |                  |            |
| Create transaction       | ✅    | ✅              |                  | ✅                | ✅                  | ✅                  | ✅                                | ✅               |            |

#### Reports

| Feature             | ADMIN | KYX <br />ADMIN | SUB <br />ADMIN | RISK <br />ADMIN | RISK <br />MANAGER | RISK <br />ANALYST | RISK ANALYST <br />LIMITED | INITIATOR<br/>\* | ACCOUNTANT |
| ------------------- | ----- | --------------- | --------------- | ---------------- | ------------------ | ------------------ | -------------------------- | ---------------- | ---------- |
| View reports        | ✅    | ✅              |                 | ✅               | ✅                 | ✅                 | ✅                         | ✅               | ✅         |
| Create report       | ✅    | ✅              |                 | ✅               | ✅                 | ✅                 | ✅                         |                  | ✅         |
| Download CSV report | ✅    | ✅              |                 | ✅               | ✅                 | ✅                 |                            |                  |            |
| Delete CSV report   | ✅    | ✅              |                 | ✅               | ✅                 | ✅                 |                            |                  | ✅         |

#### Settings

| Feature                       | ADMIN | KYX | ADMIN SUB | ADMIN RISK | RISK MANAGER | ANALYST RISK ANALYST | LIMITED INITIATOR\* | ACCOUNTANT |
| ----------------------------- | :---: | :-: | :-------: | :--------: | :----------: | :------------------: | :-----------------: | :--------: |
| View application settings     |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |          ✅          |         ✅          |     ✅     |
| Edit application settings     |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |     ✅     |
| View customize client         |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |     ✅     |
| Edit customize client         |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |            |
| View API token and secret     |  ✅   | ✅  |    ✅     |     ✅     |              |                      |                     |            |
| Generate API token and secret |  ✅   | ✅  |    ✅     |     ✅     |              |                      |                     |            |
| View data settings            |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |          ✅          |         ✅          |     ✅     |
| Edit data settings            |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |            |
| View multi documents          |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |          ✅          |         ✅          |     ✅     |
| Edit multi documents          |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |            |
| View accepted IDs             |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |          ✅          |         ✅          |     ✅     |
| Edit accepted IDs             |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |            |
| View Supported IDs            |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |          ✅          |         ✅          |     ✅     |
| Download supported IDs        |  ✅   | ✅  |    ✅     |     ✅     |      ✅      |                      |                     |            |

\* The Initiator role is visible only to certain Jumio customers.

---

# Application Settings

https://documentation.jumio.ai/docs/portals/settings/aboutIDVSettings

# Application Settings

### Default Locale

Select a language from the dropdown list to set your display language.

:::note
If no language is selected, English (EN) will be displayed.
:::

Choose from the following languages:

:::important

**Languages**

- Albanian
- Arabic
- Armenian

**Expand the list below,**

<details>
<summary>**List of Languages**</summary>
- Albanian
- Arabic
- Armenian
- Azerbaijani
- Bengali
- Bengali(India)
- Burmese
- Burmese (Myanmar)
- Catalan
- Cebuano
- Cebuano (Philippines)
- Chinese (China)
- Chinese (Hong Kong SAR China)
- Croatian
- Czech
- Danish
- Dutch
- English
- English (United Kingdom)
- Estonian
- Filipino
- Filipino (Philippines)
- Finnish
- French
- French (Canada)
- Georgian
- German
- Greek
- Hebrew
- Hindi
- Hindi (India)
- Hungarian
- Icelandic
- Indonesian
- Irish
- Italian
- Japanese
- Javanese
- Javanese (Indonesia)
- Kazakh
- Khmer
- Korean
- Latvian
- Lithuanian
- Malay
- Norwegian
- Polish
- Portuguese
- Portuguese (Brazil)
- Romanian
- Russian
- Serbian (cyrillic)
- Serbian (latin)
- Slovak
- Slovenian
- Spanish
- Spanish (Mexico)
- Swahili
- Swedish
- Thai
- Turkish
- Ukrainian
- Urdu
- Uzbek
- Vietnamese
</details>

:::

### Domain Name (prefix)

As an option, you can define a domain name that will appear as a prefix to the Jumio domain in the URL of the ID Verification page presented to your end users.

For example, if you enter `mycompany` as the value, and your integration is in the US data center, the URL domain that your end users will see will be:

`https://mycompany.web.amer-1.jumio.ai`

The domain name prefix needs to meet the following guidelines:

- Allowed characters are letters a-z, numbers 0-9, and the dash symbol “-”
- Must not start or end with the dash symbol “-”
- A maximum of 63 characters is allowed

### Authorization Token Lifetime

Specify the duration of time for which the authorization token will remain valid.

:::info
The authorization token gets returned from the Account API.
:::

Enter the value in minutes (minimum 5, maximum 86400).

:::note
The default value for the Authorization Token Lifetime is 30 minutes.
:::

### Callback, Error, and Success URLs

Configure your redirect implementation by providing URLs as discussed below:

- **Callback URL:** Define a Callback URL to automatically receive the status of each transaction.
- **Success URL:** Define a Success URL to redirect the user after images are accepted for processing. If no Success URL is specified in either the Portal or the Account API request, the Jumio default success page will be displayed. Any custom images you have specified will also be displayed (see Customize Client).
- **Redirect URL:** Define a Redirect URL to redirect the user when the verification process ends with an error or a failure. If no URL is specified in either the Portal or the Account API request, the Jumio default error page will be displayed. Any custom images you have specified will also be displayed (see Customize Client).

#### URL Requirements

- HTTPS using the TLS Protocol (most recent version recommended)
- Valid URL using ASCII characters or IDNA Punycode

#### URL Restrictions

- IP addresses, ports, certain query parameters and fragment identifiers are not allowed.
- Personally identifiable information (PII) is not allowed in any form.
- Jumio appends the following parameters to your Success or Error URL to redirect your user at the conclusion of the user journey. These parameters cannot be used as part of your Success or Error URL:

  | Name                      | Description                                                                                                                                                          |
  | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | transactionStatus         | • SUCCESS for successful submissions.<br />• ERROR for errors and failures after 3 attempts.                                                                         |
  | customerInternalReference | Your internal reference for the transaction.<br />Values MUST NOT contain Personally Identifiable Information (PII) or other sensitive data such as email addresses. |
  | transactionReference      | Jumio reference number for the transaction.                                                                                                                          |
  | errorCode                 | Displayed when transactionStatus is ERROR.                                                                                                                           |

### Capture Method

Specify how your user can submit their ID or document for verification. Choose from:

- Webcam and image upload
- Webcam only
- Image upload only

:::tip
Selecting "Webcam only" means some mobile browsers will not be supported.
:::

### Footer Display Mode

Please contact Jumio Support to inquire about changing footer settings.

### Allow Cross Device Journey

Select this checkbox to allow users to switch to Mobile Journey for image capture, if they are experiencing issues with their webcam or they don’t have a copy of their ID saved on their device. The cross device option will only be visible to users if Camera Capture has also been enabled for the verification.

The Cross Device Journey works in three ways:

- Users can choose the **Continue on Mobile** option to complete the transaction on their mobile device.
- Users can enter their email address to receive the link that will take them to the mobile browser screen to complete the transaction.
- Users can scan the QR code from their phone to receive the link that will take them to the mobile browser screen to complete the transaction.

:::tip
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

---

# Other Settings

https://documentation.jumio.ai/docs/portals/settings/IDVSettings

# Other Settings

## Customize Client

### Redirect Images

Add a **Customer Header Logo** for each locale to brand your ID Verification page.

Add a **Success image** and **Error image** for each locale. This image will be displayed on the Jumio default success and error pages if a unique Success URL and Error URL is not specified. See Application Settings.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

Criteria for images:

- All images must be formatted as JPG or PNG
- All images must not exceed 10 MB.

:::note
This applies to the Web UI only.
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

## API Credentials

:::caution
Using the credentials under the **API Users** tab is **DEPRECATED**. While using these credentials for basic authentication with the Jumio REST APIs will continue to work, you are strongly encouraged to use OAuth2 bearer tokens for authentication.
:::

### OAuth2 Clients

Generate Client ID and Client Secret pairs that you use to obtain an OAuth2 bearer token. The token can then be used to authenticate calls to the Jumio REST APIs. See Authorization for information on obtaining and using the bearer token.

You can:

- Create a new Client ID/Client Secret pair by clicking **Generate new API token**.
- Select the permissions that will be specified in the bearer token generated for the Client ID/Client Secret pair. The permissions can be to initiate a transaction, retrieve & delete transaction details, or both.
- Deactivate a Client ID/Client Secret pair.

:::tip
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

## App Showcase

The **Jumio Showcase** app is available in the app store for your device. If you have installed the app you can open **Setup** to scan the QR code on the Settings > Identity Verification > App Showcase page open. Scanning the QR code associates the app with your Jumio account. You can then initiate transactions and complete the customer journey on your device. You can then see the completed transactions in the Portal **Explorer** page. You can choose one of the standard services displayed on the app, or choose **Workflow Launcher** to initiate a transaction using a custom workflow.

## Data Settings

The Data Settings page has two sections:

- Extracted Fields
- Data Retention

### Extracted Fields

Address Extraction and Identity Verification are optional features. Contact your Jumio Manager or Executive to approve these features.

#### Mandatory Fields

If enabled, mandatory fields will be returned in the Workflow Details for all Jumio supported IDs. Use the mandatory fields to determine what data points you’d like the system to extract from the images. By default, these settings come enabled for your account.

#### Optional Fields

If enabled, optional fields will be returned in the Workflow Details under certain conditions. Use the optional fields to determine which data points you’d like the system to extract from the images. By default, these settings come enabled for your account.

### Data Retention

Since deleted transactions are irreversible and cannot be retrieved, Data Retention settings can only be changed by our internal team. Contact Support or your Jumio Account Manager/Solution Engineer if you need to change these settings.

When transactions age out of the specified data retention period, images and extracted data will be removed from the transaction record. Metadata including the timestamp, transaction references (both yours and Jumio's), country metadata, document metadata, and the result of the verification are never deleted. Metatdata for deleted transactions is not available from the API or in the Portal, but may be provided in reports available from Jumio Support.

:::info
Please contact [Jumio Support](https://support.jumio.com/s/) to make changes to your data retention period; the minimum retention is 1 day, and the maximum is the end of the contract.
:::

:::warning

- Deleting data is irreversible. Deleted transactions cannot be reviewed for quality or troubleshooting purposes.
- Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
  :::

## Watchlist Screening

The Watchlist Screening capability provides PEPs/Sanctions screening through an integration with ComplyAdvantage. To use it you must have an existing Comply Advantage account. Contact your Jumio Account Manager to discuss setting up a ComplyAdvantage account. Once ComplyAdvantage creates your account, you'll receive a verification email, with a link that will grant you access to your ComplyAdvantage Jumio portal.

The ComplyAdvantage Jumio portal will allow you to update new users, manage API keys and manage your watchlist. See ComplyAdvantage Portal Configuration.

Once you have configured your ComplyAdvantage account you provide configuration details in the Jumio Portal by going to **Settings > Identity Verification > Watchlist Screening**.

:::info
If you are migrating to the Jumio Platform from an earlier Jumio version, contact [Jumio Support](https://support.jumio.com/s/) to change your ComplyAdvantage user access. It is important to note that the old ComplyAdvantage API key will be deactivated during migration, so the new user must create a new API key from the ComplyAdvantage portal and update it in the Jumio Portal under Settings.
:::

### Watchlist Screening Jumio Portal Configuration

Configure the following values:

- **API Key**
  Enter the **Key** value of an active API Key in the ComplyAdvantage portal.
- **Default Search Profile**
  Enter the **Profile ID** of the ComplyAdvantage Search Profile that your Jumio Portal transactions will use by default. You can override this value in individual Jumio Platform account requests (see Watchlist Screening capability).
- **Default Fuzziness**
  Choose the level of fuzziness you want to apply to the searches. See [What is Fuzziness](https://complyadvantage.helpsite.com/articles/49921-what-is-fuzziness).
- **Search enabled for approved IDs**
  If enabled, this setting will make it so all transactions that are approved will be screened. Rejected documents will never be screened.

:::note
The **Use Netverify Tags** setting is no longer used.
:::

### ComplyAdvantage Portal Configuration

The ComplyAdvantage Jumio portal will allow you to update new users, manage API keys and manage your watchlist.

#### Creating API Keys

API keys are used to allow access to ComplyAdvantage's APIs and to run searches. You can create as many as you want from the ComplyAdvantage portal and they can be deleted at any time by an admin user.

- Once you've logged into ComplyAdvantage's portal you will have a menu on the left side.
- Under **API**, select **API Keys**
- From this page, you will be able to manage all of the API keys that are associated with your ComplyAdvantage account.
- To create a new API key, enter a **New Key Label** and click **Create**.

#### Creating a search profile

You need to create a search profile that defined a collection of the various lists that you want to search against. You can choose which list you want to include in a profile based on your business. Examples could be based on geography or risk levels. There is no limit to the number of lists you can create.

- Under **Settings** select **Search Profiles**. You can manage all of your search profiles from this page.
- To create a new profile, click **Create new profile**. See [What are search profiles?](https://complyadvantage.helpsite.com/articles/49920-what-are-search-profiles) in the ComplyAdvantage documentation.

## Document Verification

The Document Verification page has two main sections that show the Document types you can extract data from. You can toggle between these sections using the tabs:

- Supported Documents
- Custom Documents

### Supported Documents

Jumio supports over 25 types of documents as shown in the Supported Documents tab.

### Custom Documents

You can create custom documents from the Custom Documents tab. These documents will be in addition to the supported documents. You can also enable and/or disable these documents as desired.

:::info

- Custom document names and codes must be unique. Do not use keywords CUSTOM or OTHER, and do not duplicate the supported names and codes.
- Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
  :::

## Accepted IDs

The Accepted IDs page has two main sections. You can toggle between these sections using the tabs:

- Per Region Configuration)
- Per Country Configuration

### Per Region Configuration

The Per Region Configuration tab lists the ID types that Jumio supports on a regional level.

Use the Copy to **"Per country configuration"** button to apply changes made at the regional level to the relevant countries.

:::tip
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

### Per Country Configuration

The Per Country Configuration gives detailed information about the types of IDs that are accepted on the country level.

You can create a custom configuration by selecting the countries and the ID types you would like to support. Use the filters and the actions on the documents to define your desired set. All the Jumio-supported IDs are enabled for your account by default.

Save your changes in order for them to be applied.

You can download the complete list of countries and their ID configurations in CSV format using the **Download CSV** button.

Check the **Automatically accept newly supported IDs by Jumio** button if you would like to stay current with supported IDs as they become available in Jumio.

Use the Search bar to quickly find countries by name.

:::tip
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

## Supported IDs

Supported IDs lists the ID types that Jumio supports and gives detailed information about whether the back side of the ID is mandatory.

You can download the complete list of countries and their ID configurations in CSV format using the **Download CSV** button.

:::tip
Click Save and enter your Jumio Portal password to save the changes. Otherwise, your changes will be reverted.
:::

---

# Audit Log

https://documentation.jumio.ai/docs/portals/settings/auditLog

# Audit Log

## About the Audit Log

The Audit Log is a list of actions taken by users in the Jumio Portal. For each logged event, the portal captures information such as the user's email address and IP address, a timestamp, and the JSON message involved in the execution of the action. The log allows you to [filter events by date](#change-the-time-frame-for-the-audit-log) and also by [certain data fields](#filter-the-audit-log).

The Audit Log can display portal activity going back to September 1, 2023. Events that occurred before that date are not available.

Additionally, the log displays activity that occurred only under the tenant you are currently logged into.

## Access the Audit Log

1.  From the portal menu, select **Settings**.

    ![Settings](../images/settings_icon_20240417.png)

    The Settings menu slides out from the left.

2.  Select **Audit Log**

    ![Audit logs](../images/audit_trail_option_20240417.png)

    The log displays.

It may take a few moments for the audit log to load, especially if you select a longer time frame from the **Date** filter.

## Columns in the Audit Log

For each event the following information is provided in the log:

| Column          | Description                                                                                                                                                                                                                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Action          | Action taken by the user.                                                                                                                                                                                                                                                                                                            |
| Description     | User-friendly description of the action.                                                                                                                                                                                                                                                                                             |
| Result          | Result of the action—either success or failure.                                                                                                                                                                                                                                                                                      |
| User            | Email address of the user who took the action.                                                                                                                                                                                                                                                                                       |
| IP Address      | The user's IP address.                                                                                                                                                                                                                                                                                                               |
| Date            | The date and time (UTC) of the action.                                                                                                                                                                                                                                                                                               |
| Additional Info | When available, specific data related to the request appears in this column as a JSON expression. In case of changes to portal settings, this data could include before and after values.<br/>To expand this data for easier viewing, click the expand icon ![](../images/expand_icon_20240418.png) on the right side of the column. |

## Change the Time Frame for the Audit Log

By default the Audit Log displays the current day's activity when you first open it. You can change the time frame by selecting a different option from the **Date** filter.

![Date](../images/audit_log_date_20240417.png)

## Filter the Audit Log

Take the following steps to filter the audit log by action, user email, IP address, or result.

1.  From the Audit Log page, click **Filter**.

    ![Filter](../images/audit_trail_option_20240417.png)

    A dropdown list of fields displays.

2.  Enter search text in one or more fields.
    The Audit Log filters as you enter criteria.
3.  To clear a filter, click the **X** to the right of the field.
    To clear all filters, select **X Clear all filters**.

---

# SSO Integration

https://documentation.jumio.ai/docs/portals/settings/SSO_Integration/ssoIntegration

# Introduction to SSO Integration with Okta and Azure

Single Sign-On (SSO) is a secure authentication method that enables users to access multiple applications using a single set of login credentials. Instead of managing separate logins for each application, users authenticate once through a centralized identity provider (IdP), streamlining access, improving user experience, and strengthening security through centralized control.

## Why Use SSO?

- Users authenticate once and gain access to all authorized applications without repeated logins.
- Administrators can manage access policies, user provisioning, and de-provisioning from a single platform.
- Centralized authentication enables stronger enforcement of security policies like MFA (Multi-Factor Authentication), conditional access, and user activity monitoring.

## Types

- [SSO Integration with Okta](/docs/portals/settings/SSO_Integration/okta) as an Identity Provider.
- [SSO Integration with Azure](/docs/portals/settings/SSO_Integration/Azure) Active Directory (Azure AD) as an Identity Provider.

---

# Integrate with Okta

https://documentation.jumio.ai/docs/portals/settings/SSO_Integration/okta

# Jumio Portal - Single Sign-On Setup Guide with Okta

This document outlines the step-by-step process and key use cases for integrating SSO into the Jumio Portal using Okta.

**Single Sign-On (SSO)** is a technology that allows users to access multiple applications with a single set of login credentials. Instead of logging in separately to each SaaS application, users authenticate once through a unified login page, streamlining access and improving the user experience.

## Prerequisites for SSO Integration with Okta

Customers using Okta as their Identity Provider (IDP) can enable Single Sign-On (SSO) for the Jumio Portal.
To configure the IDP setup:

- You must log in to the Jumio Portal with a role that belongs to one of the following groups: ADMIN, KYX_ADMIN, or SUB_ADMIN.
- The Tenant ID is required for the configuration. It can be:
  -- Retrieved during the IDP connection setup at the tenant level, or
  -- Provided by the Jumio Support team upon request.

## List of Steps

#### **Step 1:** Login to Jumio Portal.

#### **Step 2:** Go to Settings and select "IDP Management Page".

![](SSO_Okta/Step2.png)

#### **Step 3:** Click “Create Connection”.

:::note

- **Label:** User-Defined Label for IDP Identification
  This label is used to identify the Identity Provider (IDP). For example, if an organization uses Okta as its IDP, you can set the label as "Okta".
  If the organization has multiple Okta IDPs and plans to integrate both, you can distinguish them with labels like "Okta1" and "Okta2".
- **Provider:** For Identity Providers (IDPs) using the SAML protocol, set the value to samlp.
  :::

![](SSO_Okta/Step3.png)

#### **Step 4:** Login to Okta as Admin

![](SSO_Okta/Step4.png)

#### **Step 5:** Navigate to Applications and choose "Applications" from the drop-down, click "Create App Integration" button.

![](SSO_Okta/Step5.png)

#### **Step 6:** You will see that the **Create App Integration** window is open.

![](SSO_Okta/Step6.png)

#### **Step 7:** Select the protocol as SAML 2.0 and, click **Next**.

![](SSO_Okta/Step7.png)

#### **Step 8:** Provide an app Name as per your convenience.

Upload the app logo (optional)

![](SSO_Okta/Step8.png)

#### **Step 9:** Copy the SSO URL and Audience URI from the Jumio Portal, and paste them into the corresponding fields on the SAML settings page.

Specify the Name ID format similar to EmailAddress.

![](SSO_Okta/Step9.png)

#### **Step 10:** Copy the “emailaddress” into OKTA SAML settings Attribute Statements “Name”

Set the Value dropdown to “user.email” (needs to be manually typed in)

![](SSO_Okta/Step10.png)

:::info
The **Jumiogroups** attribute is mandatory for user provisioning. Without its correct configuration, users cannot be assigned to a specific tenant or group.
:::

#### **Step 11:** Copy the “jumiogroups” Attribute State URLs from the Portal User Pool page and paste them into the Name field under Group Attribute Statements.

For the filter value, use a "Starts with" condition based on the initial characters of the Tenant ID. The Tenant ID can either be:
Retrieved during the IDP connection setup (see Step 21), or
Provided by the Jumio Support team.

![](SSO_Okta/Step11.png)

#### **Step 12:** Select “This is an internal app that we have created”.

![](SSO_Okta/Step12.png)

#### **Step 13:** Navigate to application configuration tab: Sign On

![](SSO_Okta/Step13.png)

#### **Step 14:** Scroll down and click View SAML setup Instructions

![](SSO_Okta/Step14.png)

#### **Step 15:** You should be able to see Identity provider Single Sign-On URL and Certificate

![](SSO_Okta/Step15.png)

#### **Step 16:** Go to the Jumio Portal and copy/paste the following parameters from your Okta setup (as described in the previous step):

Identity Provider Single Sign-On URL → Paste into the Sign-In URL field

X.509 Certificate → Paste into the Certificate field

Email Domain → Enter the domain name used in your users’ email addresses

For example: If employee email addresses are like john@airbnb.com, the email domain will be airbnb.com

![](SSO_Okta/Step16.png)

#### **Step 17:** Click Submit

![](SSO_Okta/Step17.png)

#### **Step 18:** You will see that an icon pending will be displayed against the Email Domain.

![](SSO_Okta/Step18.png)

#### **Step 19:** After clicking “Update”, you will see a message next to the email domain indicating a DNS challenge.

You’ll need to add the provided string as a DNS record for the corresponding email domain.
This DNS challenge is used to verify that your organization owns the specified domain.

For example, based on the screenshot above, one’’ll need to add the following DNS record to Jumio email domain:
jumio-up-idp-domain-verification=6c50eb3b-4576-4a87-804e-ab758f0b5f94

![](SSO_Okta/Step19.png)

#### **Step 20:** Once the DNS record is successfully updated, the DNS challenge status will be shown as "Passed" in the Portal.

![](SSO_Okta/Step20.png)

#### **Step 21:** Click “Enable”.

Please make sure to copy the ID from the pop-up, as it will be needed in (step 24)

![](SSO_Okta/Step21.png)

#### **Step 22:** Navigate to “Assign Users to App” and assign the users that should be assigned to the app.

![](SSO_Okta/Step22.png)

#### **Step 23:** Navigate to Directory -> Groups

![](SSO_Okta/Step23.png)

#### **Step 24:** Click Add Group.

Group name should follow the convention: TenantID_GroupLabel

The list of group labels are as follows:

| Role                 |
| -------------------- |
| ADMIN                |
| KYX_ADMIN            |
| SUB_ADMIN            |
| RISK_MANAGER         |
| RISK_ADMIN           |
| RISK_ANALYST_LIMITED |
| RISK_ANALYST         |
| ACCOUNTANT           |

![](SSO_Okta/Step24.png)

For instance, I have created a group for Admin user below

#### **Step 25:** Navigate to Directory -> People

![](SSO_Okta/Step25.png)

Assign the user to the Jumio Application created in Step 8.

![](SSO_Okta/Step25a.png)
![](SSO_Okta/Step25b.png)

Once the application is assigned it will be visible in applications tab for the user.

![](SSO_Okta/Step25c.png)

#### **Step 26:** Navigate to Directory -> Groups

![](SSO_Okta/Step26a.png)

Click the group that was created in step 24. Assign the user to the group.

![](SSO_Okta/Step26b.png)

![](SSO_Okta/Step26c.png)

#### **Step 27:** Assign the Jumio Application to the Group

![](SSO_Okta/Step27.png)

![](SSO_Okta/Step27b.png)

#### **Step 28:** Login to Jumio Portal and Enable the connection for the tenant.

![](SSO_Okta/Step28.png)

#### **Step 29:** Login to Jumio Portal with the email of the user whose group mapping was set in the previous step.

![](SSO_Okta/Step29.png)

#### **Step 30:** It will redirect you to the login page of linked Okta account

![](SSO_Okta/Step30.png)

:::info
SSO configuration is managed at the account level. This means that IDP settings configured for one tenant will be visible across all tenants within the same account. Any admin user from any of the associated tenants will have access to view and modify the IDP settings.
:::

---

# Integrate with Azure

https://documentation.jumio.ai/docs/portals/settings/SSO_Integration/Azure

# Jumio Portal - Single Sign On (SSO) Guide with Azure

This document outlines the step-by-step process and key use cases for integrating SSO into the Jumio Portal using Azure.

**Single Sign-On (SSO)** is a technology that allows users to access multiple applications with a single set of login credentials. Instead of logging in separately to each SaaS application, users authenticate once through a portal login page, streamlining access and improving the user experience.

## Prerequisites for SSO Integration with Azure

Customers using Azure as their Identity Provider (IDP) can enable Single Sign-On (SSO) for the Jumio Portal.
To configure the IDP setup:

- You must log in to the Jumio Portal with a role that belongs to one of the following groups: ADMIN, KYX_ADMIN, or SUB_ADMIN.
- The Tenant ID is required for the configuration. It can be:
  -- Retrieved during the IDP connection setup at the tenant level, or
  -- Provided by the Jumio Support team upon request.

## List of Steps

#### **Step 1:** Login to Jumio Portal.

#### **Step 2:** Go to Settings -> IDP Management Page.

![Step 2](SSO_Okta/Step2.png)

#### **Step 3:** Click “Create" button in the Create Connection pop-up window.

![Step 3](SSO_Azure/Step3.png)

:::note

- **Label**: User-Defined Label for IDP Identification
  This label is used to identify the Identity Provider (IDP). For example, if an organization uses Okta as its IDP, you can set the label as "Azure".
  If the organization has multiple Okta IDPs and plans to integrate both, you can distinguish them with labels like "Azure1" and "Azure2".
- **Provider**: for IDPs that run on SAML protocol, keep the value as samlp
  :::

#### **Step 4:** Login to Azure Active Directory Admin Centre and navigate to Enterprise Applications and click on “New Application”.

![Step 4](SSO_Azure/Step4.png)

#### **Step 5:** You will land on the New Application window.

![Step 5](SSO_Azure/Step5.png)

#### **Step 6:** Click "Create your own Application", provide the app name as per your convenience.

![Step 6](SSO_Azure/Step6.png)

#### **Step 7:** Custom App (Jumio) Overview

When the application is added successfully, you will be able to get access to a custom application portal.

![Step 7](SSO_Azure/Step7.png)

#### **Step 8:** Select SAML, click on Manage > Single Sign-On and select the Single Sign-On Method named SAML.

![Step 8](SSO_Azure/Step8.png)

#### **Step 9:** Set up Single Sign-On with SAML.

![Step 9](SSO_Azure/Step9.png)

When the SAML based Signed-on panel appears,
click on the Edit Button inside the part 1 : Basic SAML configuration.

#### **Step 10:** Basic SAML configuration

Copy/paste the below attributes from Jumio Portal to Azure.

1. Audience URI to Identifier
2. SSO URL to Reply URL

![Step 10](SSO_Azure/Step10.png)
![](SSO_Azure/Step10b.png)
![](SSO_Azure/Step10c.png)

#### **Step 11:** Configuration of “emailaddress” and “jumiogroups” attribute

There are two mandatory fields to send to Jumio Customer Portal through SAML 2.0 transaction during Single Sign On Process in order to be authenticated with the corresponding group assigned to the user.

![](SSO_Azure/Step11a.png)
The “emailaddress” field already exists in Azure AD User Directory as an attribute.

![](SSO_Azure/Step11.png)

Besides, the “jumiogroups” field does not exist. One will need to create a new claim for “jumiogroups”.

![](SSO_Azure/Step11b.png)

(**_Step 15 will cover the configuration of new application roles_**)

#### **Step 12:** Export SAML Certificate from Azure Configuration

Download the Base 64 certificate.

![](SSO_Azure/Step12.png)

#### **Step 13:** Go to Jumio Portal and update the below parameters,

- Login URL (From Azure) to Sign In URL
- Upload the certificate (downloaded in the previous step)
- Email domain: the domain names of the email addresses of the user. For instance: for if airbnb has employee email address as airbnb.com, the email domain will be airbnb.com

#### **Step 14:** Click Submit.

![](SSO_Azure/Step14.png)

#### **Step 15:** You will see that an icon pending will be displayed against the Email Domain.

![](SSO_Azure/Step15.png)

#### **Step 16:** After clicking “Update”, you will see a message next to the email domain indicating a DNS challenge.

You’ll need to add the provided string as a DNS record for the corresponding email domain.
This DNS challenge is used to verify that your organization owns the specified domain.

![](SSO_Azure/Step16.png)

For example, based on the screenshot above, one’’ll need to add the following DNS record to Jumio email domain:`jumio-up-idp-domain-verification=80e8392d-3dfe-48ca-9cac-d3f9385a5bfa`

#### **Step 17:** Once the DNS record is successfully updated, the DNS challenge status will be shown as "Passed" in the Portal.

![](SSO_Azure/Step17.png)

#### **Step 18:** Click “Enable”.

Please make sure to copy the ID from the pop-up, as it will be needed in next Step

![](SSO_Azure/Step18.png)

#### **Step 19:** App Roles,

- Navigate to “Azure Active Directory Admin Center” and go to All Services > App Registration > Jumio (or the name of your custom application).

- When the Jumio (or the custom application) panel appears, go to menu “Manage > App Roles”.

  ![](SSO_Azure/Step19a.png)

- Now, you will create roles corresponding to different Jumio Groups. Click on Create App Role
  Navigate to application configuration tab: Sign on,

  ![](SSO_Azure/Step19b.png)

The values for the App Roles will have the below syntax : tenantID_GroupLabel

The list of group labels are as follows:

| Role Name            |
| -------------------- |
| ADMIN                |
| KYX_ADMIN            |
| SUB_ADMIN            |
| RISK_MANAGER         |
| RISK_ADMIN           |
| RISK_ANALYST_LIMITED |
| RISK_ANALYST         |
| ACCOUNTANT           |

![](SSO_Azure/Step19.png)

**User and Tenant/Group Assignment**

**Case A:** User needs to be assigned to 1 tenant with group Admin

- Let’s say tenantID is `ec449984-9bfa-485a-8135-f4a28943d470`
- In this case, the value for App Role will be `ec449984-9bfa-485a-8135-f4a28943d470_ADMIN`

**Case B:** User needs to be assigned to two tenants with group Admin on first and Sub Admin on Second

- Let’s say tenant ID of tenant A is `ec449984-9bfa-485a-8135-f4a28943d470` and tenant ID of tenant B is `a8aa4fde-8fed-4819-87b7-6cd3ea424999`
- In this case, you will need to create two App Roles with the below values and assign those roles to the user
  `ec449984-9bfa-485a-8135-f4a28943d470_ADMIN` and `a8aa4fde-8fed-4819-87b7-6cd3ea424999_SUB_ADMIN`

#### **Step 20:** Assign Users to the Jumio (custom application).

Navigate to “Azure Active Directory admin center” and go to Enterprise Applications > Jumio (or the name of your custom application). Click on the menu “Manage > Users and Group” and Add Assignment.

Choose user and define the Jumio Role corresponding to this user.

![](SSO_Azure/Step19c.png)

#### **Step 21:** Login to Jumio Portal with the email of the user whose group mapping was set in the previous step

![](SSO_Azure/Step21.png)

---

# Rules Management

https://documentation.jumio.ai/docs/portals/rules-management/rulesManagement

# Risk Management Rules

## What is Rules Management?

Every transaction processed by Jumio is automatically evaluated using Default Risk Scoring, which is designed to assess fraud and compliance risks based on Jumio's built-in intelligence.

The Rules Management section of the Jumio Portal allows you to customize and enhance this default scoring by creating and managing your own rulesets. These rulesets can adjust the risk score based on your specific business needs.

Each ruleset is a collection of rules that analyze one or more data values returned by a capability and assign scores accordingly. When applied, these rules influence the final transaction risk score in addition to the default scoring.

:::tip
You don’t need to configure rulesets for scoring to occur—Jumio’s default rules apply automatically. Use Rules Management when you want to tailor scoring to your own risk model.
:::

The Rules Management section comprises the following main sections:

- [Global Rulesets](../rules-management/working-with-rules#global-rulesets): Available to Jumio Solution Engineers to configure workflows according to services contracted.
- [Rules and Rulesets](../rules-management/working-with-rules): Provides access to your organization’s rulesets. Users with appropriate permissions can view, create, and edit rulesets.

## Velocity Rules

Velocity rules provide a way to flag transactions that involve a suspicious number of actions taken within a given time period. For example you could create a rule that would raise a flag if the same ID number is submitted in five or more transactions across multiple accounts within a ten-minute time frame. Velocity rules can be created around devices, IPs, and other data points to help prevent high-risk transactions by detecting data anomalies in the user’s transaction history.

:::tip
Contact your Jumio Account Manager or Technical Support if you are interested in using velocity rules.
:::

### Use Cases

#### Fraud Detection in Financial Transactions:

Use Case: Detecting fraudulent activities such as credit card fraud or account takeover.

- Action: Trigger an alert if the number of transactions or transaction amounts exceed predefined thresholds, indicating potential fraudulent activity.

- Action: Trigger an alert if the number of times an end user uses multiple IP addresses or the same ID exceeds predefined thresholds, indicating potential fraudulent activity.

#### Authentication Anomaly Detection:

Use Case: Identifying abnormal authentication patterns that may indicate an account takeover attempt.

- Velocity Rule: Monitor the velocity of authentication attempts for each user account within short time intervals (e.g. 5-minute windows).

- Action: Trigger an alert if the number of login attempts from a single user account exceeds a predefined threshold, indicating potential unauthorized access.

#### Location-Based Anomaly Detection:

Use Case: Detecting account creation attempts from unusual or unexpected locations with repeated data.

- Velocity Rule: Monitor the velocity of account creation attempts from different geographic locations with the same ID, within hourly or daily intervals.

- Action: Flag login attempts originating from locations that deviate significantly from the user's initial login patterns, indicating potential account compromise.

#### Device Fingerprinting:

Use Case: Identifying account creation attempts from unrecognized or suspicious devices.

- Velocity Rule: Analyze the velocity of account creation attempts associated with unique device identifiers (e.g. device fingerprints) within short time intervals (e.g. 1-hour windows).

- Action: Raise alerts for account creation attempts from devices with unusual or inconsistent characteristics, indicating potential fraudulent access attempts.

### Velocity Rule Examples

#### Basic Rule Examples:

- when Device ID Alias was seen 5 times in 10 minutes in within network, then risk score =15
- when Device ID Alias, was seen 20 times in 1 day in assosciated network, then risk score =27
- when ID Number was seen 5 times in 10 minutes in global network, then risk score =34
- when ID Number was seen 20 times in 1 day in within network, then risk score =20

#### Complex Rule Examples:

- Same Device ID Alias, 5 times in 1 minute, WITH different IPs. - (Device ID Alias in 1 minute - Device ID Alias in 1 minute with same ip inside network > 5, then risk score =23)

- Same Device ID Alias, 5 times in 1 minute, WITH different CustomerReferences. (Device ID Alias in 1 minute - Device ID Alias in 1 minute with same Customer Internal References inside network > 5, then risk score =27)

- Same Device ID Alias, 30 times in 1 day, WITH different ID Numbers. (Device ID Alias in 1 minute - Device ID Alias + ID Number + ID Type + ID Sub Type in 1 day with same Customer Internal References inside network > 30, then risk score =17)

- Same ID Number, 5 times in 1 minute, WITH different Full Name + DOB.

- Same ID Number, 5 times in 1 minute, WITH different CustomerReferences.

- Same ID Number, 30 times in 1 day, WITH different Device IDs.

## Custom Fields in Rules

This feature allows merchants to send pre-defined custom fields via API within the PREPARED_DATA parameter. These custom fields can be utilized to create rules that determine the risk level of a transaction.

### Business Value

- Enables the ingestion of customer-specific, non-standard data fields for rule evaluation and risk decision-making, expanding beyond the standard Jumio data set.

- Supports the inclusion of non-standard fields for further risk analysis, including graph-based evaluations.

- Enhances flexibility for merchants by allowing custom data to be factored into risk calculations, optimizing fraud detection and user verification.

### Functionality

1. Custom Field Definition in Jumio Portal

- Merchants can define the custom fields and the formats they plan to use via the Jumio Portal interface.
- Supported field formats include:
  - String
  - Array
  - Integer
  - Boolean
  - Object
- The portal provides the ability to:

  - Add new custom fields
  - Delete existing fields
  - Modify (Change) field configurations as needed

  ![](../../portals/images/custom-fields.png)

2. Rule Creation using Custom Fields

- Customers can create custom rules based on the defined custom fields, enabling more granular and specific risk evaluations.
- Custom rules allow for diverse use cases, including checks on non-standard data.
  ![](../../portals/images/rulesets.png)

3. Inclusion in Prepared Data

- Once a merchant creates their custom fields, these fields become optional within the PREPARED_DATA sent via API.
- If the fields are included, they will be used to determine risk scores or trigger custom rules.

```
      {
      "firstname":"John",
      "lastname":"Doe",
      "dateOfBirth":"1982-08-30",
      "customFields":{
        "customerInternalRiskScore":80,
        "customerStatus":"VIP"
      },
      ...
```

### Benefits

This feature enhances flexibility by allowing dynamic rule creation and ingestion of custom data fields that are not available as part of Jumio’s standard fields language, further empowering merchants to refine their risk strategies based on unique data inputs.

---

# Rules, Rulesets and Global Rulesets

https://documentation.jumio.ai/docs/portals/rules-management/working-with-rules

# Rules, Rulesets and Global Rulesets

## Rules

### About the Rules Editor

The rules editor provides tools for building rule expressions. The editor comes in **two different versions** as stated below:

- [Basic Editor](#1-basic-editor)
- [Advanced Editor](#2-advanced-editor)

#### 1. Basic Editor

The default view of the rules editor is the basic version, which features an intuitive interface that is ideal for less technical users. In this version of the editor, you can:

- Build one or more rule expressions by:
  - Selecting a field from a list of all available data fields.
  - Selecting from a list of available operators.
  - Specifying what a selected field will be compared with by entering a value or selecting a second field.
- Define metadata properties such as the rule name, category, description, and labels.
- Specify the score that will be applied to a transaction if it meets the conditions defined for the rule.
  ![Basic Editor](../../portals/images/20231206_basic_editor_thumb_300_0.png)

#### 2. Advanced Editor

The advanced rule editor is for more technical users (like solution engineers) who want to write rule expressions manually. This version of the editor allows for the creation of complex rules with advanced functions.

![Advanced Editor](../../portals/images/20231206_advanced_editor_thumb_300_0.png)

### About Rule Categories

Rule categories provide a way to group rules that relate to particular Jumio services and capabilities. When you create a rule, you must assign it to a category.

Default categories include the following:

- Email Verification
- Phone Verification
- eKYC Verification
- Device Risk Verification
- ID Verification
- Address Verification
- DOB Verification
- Geo-IP Verification
- ID Verification Similarity
- ID Verification Liveness
- ID Authentication

### Create a Rule Using the Basic Editor

1. Open the ruleset with which the rule will be associated.  
   ![Open Ruleset](../../portals/images/20231206_open_ruleset_thumb_300_0.png)

2. Click **Create Rule**.  
   ![Create Rule](../../portals/images/20231206_create_rule_button_thumb_300_0.png)

3. Fill in the rule's metadata on the right side of the page.  
   ![Rule Metadata](../../portals/images/20231206_rule_metadata_thumb_300_0.png)

4. Select a field to use in the rule's expression.  
   ![Select Field](../../portals/images/20231206_new_rule_select_field_thumb_300_0.png)

5. Select an operator to use in the expression. The values available will vary based on the field selected.

6. In the **Compare to** field, choose either **Field** or **Value** to indicate whether the selected field will be compared with another field or a specific value.  
   ![Field or Value](../../portals/images/20231206_new_rule_field_value_thumb_300_0.png)

7. Depending on the previous selection:

   - If **Field**, select another field.
   - If **Value**, enter a specific value.  
     ![Enter Value](../../portals/images/20231206_new_rule_enter_value_thumb_300_0.png)

8. To add another expression, select either **And** or **Or** and repeat the steps as needed.

9. Click **Save**.

### Create a Rule Using the Advanced Editor

1. Open the ruleset with which the rule will be associated.  
   ![Open Ruleset](../../portals/images/20231206_open_ruleset_thumb_300_0.png)

2. Click **Create Rule**.  
   ![Create Rule](../../portals/images/20231206_create_rule_button_thumb_300_0.png)  
   The rules editor displays.

3. Click the **Advanced Editor** toggle.  
   ![Advanced Editor](../../portals/images/20231206_advanced_ed_toggle_thumb_300_0.png)

4. Fill in the rule's metadata on the right side of the page.  
   ![Rule Metadata](../../portals/images/20231206_rule_metadata_adv_thumb_300_0.png)

5. Enter the expression into the editor.  
   ![Enter Expression](../../portals/images/20231206_enter_exp_thumb_300_0.png)

6. Click **Validate Expression** to verify its validity. If the expression is correct, the message "Valid expression" will appear. If not, an error message will display.  
   ![Validate Expression](../../portals/images/20231206_val_exp_thumb_300_0.png)

7. Click **Save**.

### Delete a Rule

**Caution:** The deletion of a rule cannot be undone. Make sure you no longer need the rule before proceeding.

1. From the ruleset detail page, locate the rule you wish to delete.

2. Click the menu icon in the rightmost column and select **Delete**.  
   ![Delete Rule](../../portals/images/20231206_delete_rule_thumb_300_0.png)

3. Click **OK** in the confirmation dialog.

## Rulesets

### View a Ruleset

To view a ruleset, click the chevron icon to the right of its name.  
![View a Ruleset](../../portals/images/20231206_view_ruleset.png)

### Creating and Editing Rulesets

**Methods for Creating Rulesets**

You have several options for creating a ruleset:

- [Create a new ruleset from scratch](#create_a_ruleset_from_scratch) (starts with no rules; add them as needed).

- [Duplicate and customize a global ruleset](#customize_risk_scoring_for_your_workflows) (use it as a template and modify it).

- [Create a ruleset by uploading a CSV file](#create_a_ruleset_by_uploading_a_csv_file).

#### Create a Ruleset from Scratch

Take the following steps to create an empty ruleset to which you can then add rules using the rules editor.

1. From the Rulesets page, click **Create Ruleset**.  
   ![Create Ruleset Button](../../portals/images/rules_create_ruleset_button.png)

2. Enter a name and description for the ruleset.  
   ![Name and Description](../../portals/images/rules_new_rulset_name_desc.png)

3. Click **Create**. The new ruleset will appear at the top of the list with a status of _Draft_. You are now ready to add rules to the ruleset using the [Basic](#basic_editor) or the [Advanced editor](#advanced_editor).

#### Create a Ruleset By Uploading a CSV File

You can create a ruleset by uploading a CSV file that contains rules.

1. Prepare the CSV file. For information on the required layout, see [Layout of the Rulesets CSV File](#layout_of_the_rulesets_csv_file).

2. From the Rulesets page, click **Upload CSV**.  
   ![Upload CSV](../../portals/images/20231206_upload_csv.png)  
   The Upload page displays.

3. Enter a name and description for the ruleset.

4. Upload the CSV file by taking one of the following actions:

   - Drag the file from its folder and drop it into the lower half of the Upload page.  
     ![Drop File](../../portals/images/20231206_drop_your_file.png)
   - Click **Upload File** and select the file using the Open dialog.  
     ![Upload File](../../portals/images/20231206_rulset_upload_file.png)  
     The portal uploads the file and displays its contents on the page.

5. Review the rules that were uploaded to make sure the information is correct.

6. Click **Save**.  
   ![Save Ruleset](../../portals/images/20231206_upload_ruleset_save.png)  
   The application validates the rules in the ruleset. If all rules are valid, the Rulesets page displays again with the new ruleset shown at the top of the list.

:::note
If one or more rules do not pass the validation check, the application will display an error message, and the ruleset will not be saved. You must correct the errors in the CSV file and upload it again.
:::

#### Layout of the Rulesets CSV File

You can create a ruleset in the Jumio Portal by uploading a CSV file that contains a separate rule in each row. The file must contain the following columns.

| Column              | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| RULE_CATEGORY       | The [category](#about_rule_categories) to which the rule belongs. |
| RULE_DESCRIPTION    | Description of the rule.                                          |
| RULE_LABELS         | Labels to be applied to the rule.                                 |
| RULE_LEFT_HAND_SIDE | The expression that defines the conditions for the rule.          |
| RULE_NAME           | The name of the rule.                                             |
| SCORE               | The score assigned if the conditions of the rule are met.         |

### Publish a Ruleset

When you create or edit a ruleset, it will not be available for use in workflows until you publish it.

1. From the Rulesets page, locate the ruleset you want to publish.

2. Click the menu icon in the rightmost column of the ruleset's row.  
   ![Publish Ruleset](../../portals/images/20231206_ruleset_publish.png)

3. Select **Publish** and confirm the action.  
   ![Confirm Publish](../../portals/images/rules_publish_ruleset_20230725.png)

### Edit a Ruleset's Metadata

You can edit the metadata (such as the name or description) of a ruleset at any time.

1. From the Rulesets page, locate the ruleset and click the menu icon next to it.

2. Select **Edit Metadata**.

3. Update the metadata fields as needed and click **Save**.

### Unpublish a Ruleset

To make a ruleset unavailable for workflows, you can unpublish it. The unpublished ruleset will remain visible on the Rulesets page with the status _Not published_. If necessary, you can [republish the ruleset](#publish_a_ruleset) later.

1. From the Rulesets page, locate the ruleset you want to unpublish.

2. Click the menu icon in the rightmost column of the ruleset's row and select **Unpublish**.  
   ![Unpublish Ruleset](../../portals/images/ruleset_unpublish_20230703.png)

3. Confirm the action.

### Download a Ruleset

You can download a ruleset as a CSV file.

1. From the list of rulesets, [open the ruleset](#view_a_ruleset) you wish to download.

2. Click **Download All**.  
   ![Download All](../../portals/images/20231206_ruleset_download_all_thumb_300_0.png)  
   The application creates a CSV file that contains all of the ruleset's rules and saves it to your **Downloads** folder.

### View Previous Versions of a Ruleset

A ruleset's version history is a list of all previous versions, including the user who created each one and the time of creation. You can open previous versions to view the rules they contain.

1. From the Rulesets page, locate the ruleset whose version history you want to view.

2. Click the button in the **Current Version** column of the ruleset's row.  
   ![Current Version](../../portals/images/20240429_ruleset_version_thumb_300_0.png)

3. To view a previous version of the ruleset, click the link next to it.  
   ![Previous Version](../../portals/images/20240429_ruleset_view_prev_version_thumb_300_0.png)  
   The ruleset version's rules display.  
   ![View Previous Rules](../../portals/images/20240429_rulest_prev_vers_thumb_300_0.png)

**Tip:** Click **Download All** to download the rules as a CSV file.

## Global Rulesets

The Global Rulesets page is visible only to portal users assigned the Admin or KYX Admin role. However, non-admin users are able to use global rulesets as templates when creating new rulesets.

Global rulesets are collections of rules that are available to all Jumio customers. To access them, select **Rules Management > Global Rulesets** from the portal menu.

Global rulesets are read-only, but you can use them as templates for creating new rulesets that you can modify as needed.

The ruleset named "Jumio Master Ruleset" is the one you will probably use the most. It was created to serve as a template for you to copy and modify for the purpose of [customizing risk scoring](../rules-management/customizable-risk-scoring) for your transactions. This ruleset includes rules designed to score transactions across all capabilities offered by Jumio.

For the most part, each of the other global rulesets was designed to score transactions for a particular Jumio service. For example, the _ID + Selfie Verification Global Ruleset_ was made for use with the _ID + Selfie Verification_ service. This ruleset contains rules that score transactions based on an analysis of the data returned by capabilities executed by that service, including [Usability](/docs/references/capabilities/usability), [Image Checks](/docs/references/capabilities/image-checks), and [Liveness](/docs/references/capabilities/liveness).

---

# Rules Assistant

https://documentation.jumio.ai/docs/portals/rules-management/rulesAssistant

# Rules Assistant

The Rules AI Assistant helps you create rules using natural language. Instead of manually building a rule in the editor, you can simply describe the business logic you want, and the assistant will generate the corresponding rule for you.

The generated rule can then be reviewed and applied directly to the Rules Editor.

## How Does the AI Assistant Work?

**Step 1:** Open the Rules Editor.

**Step 2:** Enter a description of the rule you want to create using plain language.

**Step 3:** The AI Assistant interprets your request and generates:

- A description of the rule in plain language.
- The corresponding rule expression.

**Step 4:** Review the generated rule.

**Step 5:** If the rule meets your requirements, select **Apply to Editor** to insert it into the Rules Editor, where you can continue editing or save it.

![](./rulesAssistantAI.png)

## Example Workflow

### Enter a Prompt

Create a rule that triggers when the input first name or last name is different from the name extracted from the ID.

### Generated Output

A human-readable explanation describing the rule.
A valid rule expression that compares the prepared data against the extracted document data.

## AI Assistant Capabilities

The Rules AI Assistant can create rules using all variables, operators, and functions supported by the Jumio Rules Engine, including:

- Prepared Data fields
- Extraction results
- Verification results
- Risk scores
- Transaction data
- Logical operators and expressions
- String, numeric, and date functions
- Any other data available within the Rules Engine

Rules Assistant allows you to create anything from simple comparison rules to more advanced business logic without having to write rule expressions manually.

## Best Practices

For the best results:

- Describe the business outcome you want, not the technical implementation.
- Be as specific as possible. For example:
  "Trigger when the customer is under 18 years old."
  "Trigger when the document issuing country is different from the customer's address country."
  "Trigger if the email verification result is FAILED and the device risk score is HIGH."
- Review the generated rule before applying it to ensure it matches your intended logic.

## Limitations and Considerations

- The AI Assistant generates rule suggestions based on your prompt.
- You can modify the generated rule after applying it to the Rules Editor.
- Rules generated by the AI Assistant use the same syntax and capabilities as rules created manually.
- As with any generated content, you should validate the rule before using it in production.

---

# Customizable Risk Scoring

https://documentation.jumio.ai/docs/portals/rules-management/customizable-risk-scoring

# Customizable Risk Scoring

Jumio allows you to customize the rules that assign scores to your organization's transactions. To do so, you must duplicate a global ruleset—we recommend using the Jumio Master Ruleset—and then customize its rules as you see fit. After publishing the ruleset, provide its ruleset ID to your Jumio Solution Engineer, who will configure your organization's account to use the ruleset to score your transactions.

The Jumio Master Ruleset is preloaded with rules for scoring all capabilities provided by Jumio. After you duplicate it, determine which rules need to be used by your workflows and then edit each one to change the score it assigns whenever it is triggered.

## Customize Risk Scoring for Your Workflows

Take the following steps to create a duplicate copy of the Jumio Master Ruleset and customize it for use in scoring your workflows.

1.  From the portal menu, select Rules Management.  
    ![](../../portals/images/select_rules_mgmt_20240410.png)  
    The Rules Management menu slides out from the left.

2.  Select **Rulesets**.  
    ![](../../portals/images/select_global_rulesets_20240410.png)  
    The Rulesets page displays.

3.  Click **Create Ruleset** and select **From Global Ruleset**.  
    ![](../../portals/images/create_from_global_ruleset_20240411.png)  
    A list of global rulesets displays.

4.  Select the global ruleset that you want to duplicate.  
    ![](../../portals/images/select_JMR_20240411.png)  
    The selected ruleset's metadata and rules display on the right side of the page.

5.  Click **Duplicate**.  
    ![](../../portals/images/click_duplicate_20240411.png)  
    The Duplicate Global Ruleset page displays.

6.  Modify the default name and description as desired for the new ruleset and click **Duplicate**.  
    ![](../../portals/images/rules_create_ruleset_click_dup_20230811.png)  
    The Rulesets page redisplays. The new ruleset appears at the top of the list with a status of _Draft_.  
    ![](../../portals/images/rules_create_ruleset_new_draft_20230811.png)

7.  Open the ruleset.

8.  Determine which rules are needed by your workflows and edit them as needed. Most importantly, make sure the **Score** value for each rule as appropriate for your workflows.  
    ![](../../portals/images/edit_rule_20240411.png)  
    For more information on editing rules, see Working with Rules.

9.  Once you are ready to use the ruleset to score your workflows, publish it.

10. Contact your Jumio Solution Engineer and provide them with the new ruleset ID so they can configure your account to use it for scoring your transactions.

---

# Ruleset ID Configuration

https://documentation.jumio.ai/docs/portals/rules-management/rulesetIDConfiguration

# Overview

The **Ruleset ID Configuration** allows you to configure Ruleset IDs directly in the **Jumio Customer Portal** via the Rules Management section.
This feature provides greater flexibility and control over how risk scoring is calculated and customized within workflows.

Customers can configure Ruleset IDs for:

- **Risk Scoring Ruleset ID**
- **Additional Scoring Ruleset ID**

## Access the Configuration

The Rules Management section allows you to create and manage Ruleset IDs directly in the portal.

**Step 1:** Log in to the Jumio Customer Portal.

**Step 2:** From the left navigation menu, navigate to **Rules Management**.

**Step 3:** Under Rules Management, select **Ruleset ID Configuration**.

**Step 4:** The Ruleset ID Configuration page will open, where you can view or manage available rulesets.

![](./rulesetIDConfig.png)

## Available Configuration Types

### 1. Risk Scoring Ruleset ID

The **Risk Scoring Ruleset ID** allows customers to fully override the system’s default risk score calculation using rule-based scoring logic.
When a Ruleset ID is configured for Risk Scoring, the workflow risk score is calculated exclusively based on the outcome of the rules executed within the configured ruleset.

#### Logic

The workflow risk score is calculated according to the following logic:

| Condition                            | Final Risk Score Logic                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Risk score evaluation                | The risk score is determined from the outcome of the last executed ruleset in the Risk primitive. |
| Triggered rule contains score `100`  | Final Risk Score = `100`                                                                          |
| Triggered rule contains score `-100` | Final Risk Score = `0`                                                                            |
| One or more rules triggered          | Final Risk Score = sum of all triggered rule scores, capped between `0` and `100`                 |
| No rules triggered                   | Final Risk Score = `0`                                                                            |

#### Use Case

Use this option when customers want to completely replace the default system-generated risk scoring logic with their own custom rules-based scoring model.

### 2. Additional Scoring Ruleset ID

The **Additional Scoring Ruleset ID** allows customers to supplement the system’s default risk score with additional rule-based scoring.

This option is intended for exception handling and targeted adjustments to the default scoring behavior rather than replacing the entire risk scoring mechanism.

The default system risk score calculation remains active, and the configured ruleset contributes additional scoring logic on top of the default score.

#### Logic

| Step                           | Calculation Logic                                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Base calculation               | **Final score = Default system risk score + Maximum risk score** from the triggered rules in the last executed ruleset |
| Final score greater than `100` | Final Risk Score = `100`                                                                                               |
| Final score less than `0`      | Final Risk Score = `0`                                                                                                 |

#### Use Case

Use this option when customers want to preserve the default Jumio risk scoring while introducing custom handling for specific edge cases.

This configuration is recommended for:

- Exception-based handling
- Incremental score adjustments
- Specialized fraud or risk scenarios
- Customer-specific overrides for selected cases

It is **not intended** to generate a complete standalone risk score.

:::important

- Customers should ensure that configured rule sets are thoroughly tested before enabling them in production environments.
- Risk scores are always normalized between 0 and 100.
  :::

## Example Scenarios

### Example 1: Risk Scoring Ruleset ID

| Triggered Rules    | Rule Scores | Final Score |
| ------------------ | ----------- | ----------- |
| Rule A, Rule B     | 20 + 30     | 50          |
| Rule A             | 100         | 100         |
| Rule A             | -100        | 0           |
| No Rules Triggered | N/A         | 0           |

### Example 2: Additional Scoring Ruleset ID

| Default Score | Triggered Rule Score | Final Score |
| ------------- | -------------------- | ----------- |
| 60            | 20                   | 80          |
| 90            | 20                   | 100         |
| 10            | -20                  | 0           |

## Audit Information

Each Ruleset ID configuration includes audit metadata:

- **Updated By** — User who last modified the configuration
- **Updated Date** — Timestamp of the last update

These fields are read-only and maintained automatically by the system.

---

# Client Libraries

https://documentation.jumio.ai/docs/developer-resources/client-libraries/overview-client-libraries

# Client Libraries

Jumio includes native libraries for several different client types.

- **[Java Spring Boot Library](./java-client-lib/java-client-library)**: Provides an easy way to integrate Jumio services into Spring Boot applications, with built-in support for configuration, REST client handling, and streamlined workflows. Ideal for teams already using the Spring ecosystem.

- **[.NET Client Library](./dotnet-lib/dotnet-sdk)**: Enables seamless integration with Jumio’s APIs in .NET applications, offering strong type safety, async support, and compatibility with both .NET Framework and .NET Core for enterprise-grade deployments.

---

# Java Spring Boot Library

https://documentation.jumio.ai/docs/developer-resources/client-libraries/java-client-lib/java-client-library

# Java Client Library

The Jumio Java client library supports integrating the Jumio Platform into Java Spring applications. You configure an instance of the [JumioClient](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.html) class and use it to manage interactions with the Jumio Platform.

JumioClient exposes [fluent interfaces using the builder design pattern](https://www.baeldung.com/java-fluent-interface-vs-builder-pattern) that make it simple to configure and execute most common interactions with the platform including:

- **Obtaining and caching authorization tokens**.Configure the JumioClient to use with your Jumio data center and OAuth2 credentials and the client will manage the JWT tokens for all calls to the Jumio Platform.

- **Initiating and executing transactions**.

- **Retrieving transaction status and details**. Jumio Client also provides access to lower-level objects that support more detailed configurations.

The Javadoc API reference is available at: [index.html](pathname:///javadoc/index.html)

## 1. Dependencies

Add these dependencies to your Spring Boot project.

### 1.1. Maven Dependencies

```
<repositories>
  <repository>
    <id>jumio-api</id>
    <name>Jumio Api Repository</name>
    <url>https://repo.api.jumio.ai</url>
  </repository>
</repositories>

.....
<dependency>
    <groupId>com.jumio</groupId>
    <artifactId>jumio-client</artifactId>
    <version>1.1.0</version>
</dependency>

```

## 2. Initializing the JumioClient

[JumioClient](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.html)
implements the Builder pattern to make it easy to configure and initialize. It is usually created as a Spring Bean so it can be injected and used as needed in your application.

To configure JumioClient you need to provide:

- A DataCenter object representing the Jumio datacenter your application will be using. These objects are defined as public static instances in the DataCenters class, and can be accessed by `DataCenters.US`, `DataCenters.EU`, or `DataCenters.SGP`.
- A UsernamePassword object constructed from your OAuth2 credentials, obtained from the Jumio Portal. See [API Credentials](../../../portals/settings/IDVSettings#api-credentials).
- A String with the value you want to use for the User-Agent header in calls to Jumio.
- (Optional) A ClientHttpRequestFactory instance, if you want to use a [Spring RestTemplate](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html) other than the default.

### 2.1.Example: JumioClient Bean

<details>

```java
import com.jumio.sdk.kyx.DataCenters;
import com.jumio.sdk.kyx.JumioClient;
import com.jumio.sdk.kyx.UsernamePassword;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JumioClientProvider {

    @Bean
    public JumioClient jumioClient() {
        return JumioClient.builder()
                .dataCenter(DataCenters.EU)
                .oauthCredentials(new UsernamePassword("xyz123...", "123xyz..."))
                .userAgent("MyCompany Test/1.1")
                .defaultRestTemplate()
                .build();
    }

}
```

</details>

### 2.2.Builder Steps

| Builder Method                                   | Parameters                                                                                                                                                                | Description                                                                                                                                                                                      | Return Type                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `builder()`                                      |                                                                                                                                                                           | Returns the first builder step.                                                                                                                                                                  | [BuilderStep1](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.BuilderStep1.html)         |
| `dataCenter()`                                   | [DataCenter](pathname:///javadoc/com/jumio/sdk/kyx/DataCenter.html) accessed as static object from [DataCenters](pathname:///javadoc/com/jumio/sdk/kyx/DataCenters.html). | [DataCenters](pathname:///javadoc/com/jumio/sdk/kyx/DataCenters.html) provides static references to pre-defined objects for the Jumio datacenters.                                               | [BuilderStep2](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.BuilderStep2.html)         |
| `oauthCredentials`                               | [UsernamePassword](pathname:///javadoc/com/jumio/sdk/kyx/UsernamePassword.html)                                                                                           | Object containing your OAuth2 user name and password that you can obtain from the Jumio Portal. See [API Credentials](../../../portals/settings/IDVSettings#api-credentials).                    | [BuilderStep3](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.BuilderStep3.html)         |
| `userAgent()`                                    | String                                                                                                                                                                    | The value you want to use as the user-agent header in the underlying REST request.                                                                                                               | [BuilderStep4](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.BuilderStep4.html)         |
| `defaultRestTemplate()`or `customRestTemplate()` | No parameters or `ClientHttpRequestFactory`                                                                                                                               | Use the default Spring [RestTemplate](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/client/RestTemplate.html) or specify an alternative RestTemplate. | [FinalBuilderStep](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.FinalBuilderStep.html) |
| `build()`                                        |                                                                                                                                                                           | Returns the configured JumioClient.                                                                                                                                                              | [JumioClient](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.html)                       |

## 3.Initiating a Transaction with the Java Library

[JumioClient](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.html) has two methods that provide fluent builder interfaces for initiating a transaction:

- `initiateNewAccount()` for initiating a transaction for a new account.
- `addNewWorkflowToExistingAccount()` for initiating a transaction for an existing account.

The builder steps provide a simple way to configure an account request.

:::note
For additional information on the low-level calls that are executed by the client see [Create or Update Accounts](../../API/CreateUpdateAccounts/creating-and-updating-accounts).
:::

### 3.1. Example: Initiate a Transaction for a New Account

The following snippet shows the fluent builder interface you can use to initiate a transaction for a new account:

```

WebResponse webResponse = jumioClient.initiateNewAccount(FluentBuilderWorkflows.STANDALONE_ID_VERIFICATION_10015)
.customerInternalReference("my_company")
.callbackUrl("https://myserver.mycompany.com/callback")
.withDefaultCredentials()
.performWeb(new WebSettings()
.successUrl("https://jumio.com/success")
.errorUrl("https://jumio.com/failure"));

```

### 3.2. Example: Initiate a Transaction for an Existing Account

The following snippet shows the fluent builder interface you can use to initiate a transaction for an existing account:

```

jumioClient.addNewWorkflowToExistingAccount(FluentBuilderWorkflows.fluentWorkflow(Workflows.workflow(10025)), accountId)
.customerInternalReference(reference.toString())
.callbackUrl(JUMIO_CALLBACK_PUBLIC_URL)
.withDefaultCredentials()
.performWeb(new WebSettings()
.successUrl("https://jumio.com/success")
.errorUrl("https://jumio.com/failure"));

```

### 3.3. Builder Steps

| Builder Method                                                          | Parameters                                                                                                                                                                                                                                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Return Type                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initiateNewAccount()`<br />or<br />`addNewWorkflowToExistingAccount()` | [FluentBuilderWorkflow](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/FluentBuilderWorkflow.html) accessed as static object from [FluentBuilderWorkflows](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/FluentBuilderWorkflows.html).<br /><br />`addNewWorkflowToExistingAccount` also requires the accountID as a String parameter. | [FluentBuilderWorkflows](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/FluentBuilderWorkflows.html) provides static references to pre-defined objects for standard Jumio workflows.                                                                                                                                                                                                                                                                                                                      | [CustomerReferenceBuilderStep](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/builder//FluentBuilderContainer.CustomerReferenceBuilderStep.html)                                                                                                                                                             |
| `customerInternalReference()`                                           | String                                                                                                                                                                                                                                                                                                                                              | String that identifies your organization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [CallbackUrlBuilderStep](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/builder/FluentBuilderContainer.CallbackUrlBuilderStep.html#CallbackUrlBuilderStep)                                                                                                                                                   |
| `callbackUrl()`                                                         | String                                                                                                                                                                                                                                                                                                                                              | String representation of the URL to use for the Callback. If you do not need a callback enter `null`.                                                                                                                                                                                                                                                                                                                                                                                                           | [CredentialRequestBuilderStep](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/builder/FluentBuilderContainer.CredentialRequestBuilderStep.html)                                                                                                                                                              |
| `withDefaultCredentials()`<br />or<br />`withSpecificCredentials()`     | No parameters<br />or<br />List [CredentialRequest](pathname:///javadoc/com/jumio/sdk/account_v1/model/CredentialRequest.html) credentials                                                                                                                                                                                                          | `withDefaultCredentials()` is used for workflows that do not require additional credential configuration.<br />or<br />`withSpecificCredentials()` is used with services such as DocProof that require explicit credential specifications. A [CredentialRequest](pathname:///javadoc/com/jumio/sdk/account_v1/model/CredentialRequest.html) allows you to configure the credential(s) required by the workflow. See [Configuring Specific Credentials](./java-client-library#configuring-specific-credentials). | [PerformWeb](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/builder/FluentBuildWebOnlyContainer.PerformWeb.html)<br />or<br />[PerformWebOrIdWithPreparedData](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/builder/FluentBuilderWithIdAndPreparedDataContainer.PerformWebOrIdWithPreparedData.html) |
| `performWeb()`<br />or<br />`performUploadIds()`                        | [WebSettings](pathname:///javadoc/com/jumio/sdk/account_v1/model/WebSettings.html)<br />or<br />See [Uploading Credentials with the Java Library](./java-client-library#uploading-credentials-with-the-java-library) below.                                                                                                                         | Use a new WebSettings with no additional configuration to use the defaults configured in the Jumio Portal Settings. Optionally, you can override the successUrl and errorUrl by setting the appropriate values, as shown in the examples below.<br />or<br />See [Uploading Credentials with the Java Library](./java-client-library#uploading-credentials-with-the-java-library).                                                                                                                              | [WebResponse](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/response/WebResponse.html)<br />or<br />[IdUploadResponse](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/response/IdUploadResponse.html)                                                                                                 |

`JumioClient` also has a `getAccountAPI()` method that returns an [AccountAPI](pathname:///javadoc/com/jumio/sdk/account_v1/api/AccountApi.html) object you can use if you require more detailed configuration.

### 3.4. WebResponse

The [WebResponse](pathname:///javadoc/com/jumio/sdk/kyx/fluent_builder/response/WebResponse.html) object provides access to both the configured [AccountRequest](pathname:///javadoc/com/jumio/sdk/account_v1/model/AccountRequest.html) and the [AccountResponse](pathname:///javadoc/com/jumio/sdk/account_v1/model/AccountResponse.html) containing the values returned by Jumio. For example, you can extract the web URL and use it to launch the Web Client. See [Returning the Jumio Web Client](./java-client-library#returning-the-jumio-web-client) and [Account Response](../../API/CreateUpdateAccounts/creating-and-updating-accounts#account-responses).

### 3.5. Configuring Specific Credentials

Services such as Document Verification require you to specify the document you will be verifying.

See also:

- [Credentials](../../API/CreateUpdateAccounts/creating-and-updating-accounts#credentials)
- [Standard Services](../../../references/servicesAndworkflow/standardService/standardServices)

**Example: Initiate a Transaction for a New Account**

```java

WebResponse webResponse = jumioClient.initiateNewAccount(FluentBuilderWorkflows.STANDALONE_ID_VERIFICATION_10015)
.customerInternalReference("my_company")
.callbackUrl("https://myserver.mycompany.com/callback")
.withSpecificCredentials(
Collections.singletonList(
new CredentialRequest()
.category("ID")
.type(
new CredentialType()
.values(Arrays.asList("DRIVING_LICENSE", "ID_CARD", "PASSPORT"))
)
.country(new CredentialCountry()
.values(
Arrays.asList(
CountryCodeISO3166alpha3.USA,
CountryCodeISO3166alpha3.CAN,
CountryCodeISO3166alpha3.AUT,
CountryCodeISO3166alpha3.GBR
)
)
)
)
)
.performWeb(new WebSettings()
.successUrl("https://jumio.com/success")
.errorUrl("https://jumio.com/failure"));

```

### 3.6. Returning the Jumio Web Client

You can launch the Jumio Web Client by extracting the web URL from the [AccountResponse](pathname:///javadoc/com/jumio/sdk/account_v1/model/AccountResponse.html).

**Example**

```java
    @GetMapping
    ResponseEntity<Void> initiateWebOnlyVerification() {

        final UUID reference = UUID.randomUUID();


       final WebResponse webResponse = jumioClient.initiateNewAccount(FluentBuilderWorkflows.STANDALONE\_ID\_VERIFICATION\_10015)
                .customerInternalReference(reference.toString())
                .callbackUrl(CALLBACK\_URL)
                .withDefaultCredentials()
                .performWeb(new WebSettings()
                        .successUrl("https://jumio.com/success")
                        .errorUrl("https://jumio.com/failure"));

        final HttpHeaders headers = new HttpHeaders();
        final URI location = Optional.ofNullable(webResponse.getAccountResponse())
                .map(AccountResponse::getWeb)
                .map(AccountResponseWeb::getHref)
                .orElseThrow(() -> new IllegalStateException("No URL configured for your account"));
        headers.setLocation(location);
        return new ResponseEntity<>(headers, HttpStatus.MOVED\_PERMANENTLY);
    }
```

### 3.7. Uploading Credentials with the Java Library

Depending on the workflow that will be executed you can:

- Use the `performUploadIds()` step method to upload credential files from your server.
- Use the `performUploadPreparedData()` step method to upload raw data values.

:::info
Uploading files requires that you obtain user consent. See End-User Consent to Collect Personal Data for additional information.
:::

#### 3.7.1. Example Using performUploadIds()

```java
    @GetMapping(path = "/upload", produces = MediaType.TEXT\_HTML\_VALUE)
    public String htmlUploadForm() {
        return """
                <form action="./upload" method="post" enctype="multipart/form-data">
                    <fieldset>
                        <legend>Upload ID</legend>
                        <input type="file" name="file">
                        <input type="checkbox" name="consent" value="yes" />
                        <input type="submit"value="Upload and verify">
                    </fieldset>
                </form>
                """;
    }

    @PostMapping("/upload")
    public String createAPINewWorkflow(
            @RequestParam("file") MultipartFile file,
            @RequestParam("consent") String consent) throws IOException {

        if (!"yes".equalsIgnoreCase(consent)) {
            throw new IllegalStateException("User did not consent!");
        }

        final UUID reference = UUID.randomUUID();

        final OffsetDateTime dateTimeNow = OffsetDateTime.now();
        UserConsent userConsent = new UserConsent()
                .userIp("46.139.143.174")
                .userLocation(new UserLocation()
                        .country(CountryCodeISO3166alpha3.USA.toString())
                        .state("IL")
                )
                .consent(new Consent()
                        .obtained("yes")
                        .obtainedAt(dateTimeNow)
                );

        final IdUploadResponse finish = jumioClient.initiateNewAccount(FluentBuilderWorkflows.STANDALONE\_ID\_VERIFICATION\_10015)
                .customerInternalReference(reference.toString())
                .callbackUrl(CALLBACK\_URL)
                .withDefaultCredentials()
                .performUploadIds()
                .userConsent(userConsent)
                .uploadFront(file.getInputStream())
                .skipBackUpload()
                .finish();

        return "Done with wfid: " + finish.getAccountResponse().getWorkflowExecution().getId();
    }
```

#### 3.7.2. Example Using performUploadPreparedData()

This example assumes you have a simple data transfer class called EndUserForm, with fields corresponding to the required prepared data values.

```java
@PostMapping(value = "/verifyDL", consumes = {MediaType.APPLICATION_JSON_VALUE})
public String verifyDL(@RequestBody EndUserForm endUserForm) {
    JumioClient jumioClient = applicationContext.getBean(JumioClient.class);
    final PreparedDataResponse response = jumioClient
        .initiateNewAccount(FluentBuilderWorkflows.Standalone_DL_Verification_USA_10008)
        .customerInternalReference("mycompany")
        .callbackUrl(null)
        .withDefaultCredentials()
        .performUploadPreparedData()
        .userConsent(new UserConsent()
            .userLocation(new UserLocation()
                .country(CountryCodeISO3166alpha3.USA.toString())
                .state("CA"))
            .userIp("46.139.143.174")
            .consent(new Consent()
                .obtained("yes")
                .obtainedAt(OffsetDateTime.now())))
        .addPreparedData(new PreparedData()
            .address(new Address()
                .city(endUserForm.getAddress().getCity())
                .country(endUserForm.getAddress().getCountry())
                .line1(endUserForm.getAddress().getLine1())
                .line2(endUserForm.getAddress().getLine2())
                .subdivision(endUserForm.getAddress().getSubdivision())
                .postalCode(endUserForm.getAddress().getPostalCode()))
            .firstName(endUserForm.getFirstName())
            .lastName(endUserForm.getLastName())
            .dateOfBirth(LocalDate.parse(endUserForm.getDob()))
            .socialSecurityNumber(endUserForm.getSsn())
            .id(new IdDetails()
                .idNumber(endUserForm.getIdNumber())
                .type("DRIVING_LICENSE")
                .issuingDate(LocalDate.of(2019, 12, 26))
                .expiryDate(LocalDate.of(2025, 1, 18))))
        .finish();

    return response.toString();

}

```

## 4. Retrieving Transaction Data with the Java Library

[JumioClient](pathname:///javadoc/com/jumio/sdk/kyx/JumioClient.html) has two `retrieveData()` methods for retrieving transaction data.

- `public WorkflowExecutionResponse retrieveData(CallbackRequestBody callbackRequestBody)`
  Use this method when you are Implementing a Callback Service.
- `public WorkflowExecutionResponse retrieveData(UUID accountId, UUID workflowExecutionId)`
  Use this method to retrieve data using the account ID and workflow execution ID.

Both methods return a [WorkflowExecutionResponse](pathname:///javadoc/com/jumio/sdk/retrieval_v3/model/WorkflowExecutionResponse.html) object containing the data corresponding to the values returned by calling the Retrieval REST APIs (See [Calling Retrieval APIs](../../retrieval#calling-retrieval-apis)).

For example, the following snippet accesses the capabilities executed by the transaction and uses a convenience method called extractNonPassedCapabilities to print out the decision details label for any capabilities that have a decision:type value other than "PASSED":

```java

    @GetMapping(path = "/{acctId}/{transId}")
    String returnReason(@PathVariable String acctId, @PathVariable String transId) {

    	JumioClient jumioClient = applicationContext.getBean(JumioClient.class);
    	WorkflowExecutionResponse details = jumioClient.retrieveData(UUID.fromString(acctId), UUID.fromString(transId));
    	WorkflowExecutionResponseCapabilities capabilities = details.getCapabilities();
    	return jumioClient.extractNonPassedCapabilities(capabilities);
    }

```

Calling this endpoint with the account ID and workflow execution ID of a transaction for which the imageChecks capability returned a decision:type value of "WARNING" would return a string such as this:

```

\[imageChecks: WARNING,REPEATED_FACE\]

```

[WorkflowExecutionResponse](pathname:///javadoc/com/jumio/sdk/retrieval_v3/model/WorkflowExecutionResponse.html) provides a variety of methods for accessing the transaction decision, credentials, capabilities, rules, and other values for the transaction.

### 4.1. Implementing a Callback Service

If your integration uses a Callback service you can implement it as shown in the example below.

**Example: /jumio-callback Endpoint**

```java

package com.acme.demowithsdk;

import com.jumio.sdk.callback.model.CallbackRequestBody;
import com.jumio.sdk.kyx.JumioClient;
import com.jumio.sdk.retrieval_v3.model.WorkflowExecutionResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.UUID;

@RestController
@RequestMapping("/jumio-callback")
public class JumioCallbackRestController {

    private final JumioClient jumioClient;

    private static final Logger logger = LoggerFactory.getLogger(JumioCallbackRestController.class);

    public JumioCallbackRestController(JumioClient jumioClient) {
        this.jumioClient = jumioClient;
    }

    @PostMapping
    public void handleCallback(@RequestBody CallbackRequestBody callbackRequestBody) {
        final UUID workflowExecutionId = callbackRequestBody.getWorkflowExecution().getId();

        final String workflowExecutionStatus = callbackRequestBody.getWorkflowExecution().getStatus();
        if (!"PROCESSED".equalsIgnoreCase(workflowExecutionStatus)) {
            logger.warn("Workflow {} has not been processed. Status is {}", workflowExecutionId, workflowExecutionStatus);
            return;
        }

        final WorkflowExecutionResponse workflowExecutionResponse = jumioClient.retrieveData(callbackRequestBody);
        if (!"PASSED".equalsIgnoreCase(workflowExecutionResponse.getDecision().getType())) {
            logger.warn("ID Scan has been rejected for {}", workflowExecutionId);
            return;
        }

        logger.info("Verification {} successfully processed.", workflowExecutionId);
    }

}

```

## Javadoc API reference

[Checkout](pathname:///javadoc/index.html)

---

# .NET Library

https://documentation.jumio.ai/docs/developer-resources/client-libraries/dotnet-lib/dotnet-sdk

# .NET Client Library

The Jumio .NET client library facilitates the integration of the Jumio Platform into .NET applications.
You configure an instance of the `JumioClient` class and utilize it to manage interactions with the Jumio Platform.

`JumioClient` exposes fluent API using the builder design pattern, simplifying the configuration and execution of common interactions with the platform, which include:

- Initializing the `JumioClient`
- Initiating and executing transactions.
- Retrieving transaction status and details.

**Click and download the .NET Client library Collection [here](/resources/jumio-api-client-1.0.0.zip).**

## 1. Initializing the JumioClient

`JumioClient` implements the Builder pattern to streamline configuration and initialization.

To configure `JumioClient` you need to provide:

- A `DataCenter` object representing the Jumio data center your application will use.
- A `string` with the value you want to use for the User-Agent header in calls to Jumio.
- `JumioClient` supports only OAuth2 credentials, obtained from the Jumio Portal.
- (optional) An `IRequestAdapter` instance, if you want to use other then the default `HttpClientRequestAdapter` implementation.

**Example**:

```c#
  var jumioClient = JumioClientBuilder
    .DataCenter(DataCenters.EuTest)
    .UserAgent(new UserAgent("User Agent"))
    .OAuthCredentials(new ApiCredentials("Insert_api_key", "Insert_api_secret"))
    .DefaultRequestAdapter()
    .Build();
```

## 2. Initiating and Executing Transactions.

### 2.1. Using Existing Workflows

`JumioClient` provides two methods with fluent builder interfaces for initiating a transaction:

- `InitiateNewAccount()` for initiating a transaction for a new account.
- `AddNewWorkflowToExistingAccount()` for initiating a transaction for an existing account.

The builder functions for account creation allow you to set up the callback URL, the tokenLifetime, etc.

Starting the construction of the workflow is done via the `StartWorkflow()` function. The `WorkflowBuilders` contains the list of predefined workflow types which are the following:

- Web-only workflows
- Workflows with some permutations of front, back image, selfie image, prepared data
- Workflows with documents

Each workflow has its own predefined steps for ease of use. For non-web-only workflows, user consent to upload data is mandatory.

**Example of a web only workflow**:

```c#
jumioClient
    .AddNewWorkflowToExistingAccount(
        new CustomerInternalReference("Insert_the_reference"),
        WorkflowBuilders.IdIvScreening10032,
        new AccountId("Insert_existing_accountId"))
    .StartWorkflow()
    .WithDefaultCredentials()
    .PerformWeb(
        new WebSettings()
        {
            SuccessUrl = "Insert_success_url",
            ErrorUrl = "Insert_error_url",
        })
```

**Example of a workflow with front, back and prepared data**:

```c#
 jumioClient
    .InitiateNewAccount(
        customer,
        WorkflowBuilders.StandaloneIdVerification10015)
    .CallbackUrl(new CallbackUrl("Insert_callback_url"))
    .StartWorkflow()
    .WithDefaultCredentials()
    .PerformUploadIds()
    .UserConsent(consent)
    .UploadFront(frontFileStream, "image/jpg")
    .UploadBack(backFileStream, "image/jpg")
    .Finish();
```

**Example of a workflow with documents**:

```c#
 jumioClient
    .InitiateNewAccount(
        customer,
        WorkflowBuilders.DocumentVerification10026)
    .CallbackUrl(new CallbackUrl("Insert_callback_url"))
    .StartWorkflow()
    .WithSpecificCredentials(ImmutableArray.Create(credentialRequest))
    .PerformUploadDocuments()
    .UserConsent(consent)
    .UploadDocument(fileStream, "image/jpeg")
    .UploadDocument(backFileStream, "image/jpeg")
    .UploadDocument(documentStream, "application/pdf")
    .Finish()
```

### 2.2. Implementing New Workflows

Adding a new workflow is possible by implementing a new instance of the `WorkflowBuilderBase<TWorkflow>` class.
This allows specifying a new workflow with custom steps.

**Example of a custom workflow**

```c#
// The builder class for the workflow.
public class CustomWorkflowBuilder : WorkflowBuilderBase<CustomWorkflow>
{
    public CustomWorkflowBuilder(WorkflowType workflowType)
        : base(workflowType)
    {
    }

    public override CustomWorkflow CustomWorkflowBuilder(WorkflowService workflowService)
    {
        return new CustomWorkflow(workflowService);
    }
}

// The workflow which defines the credential types and the next workflow step.
public class CustomWorkflow : DefaultOrSpecificCredentialsBase<CustomWorkflowStep>
{
    public CustomWorkflow(WorkflowService workflowService)
        : base(c => new CustomWorkflowStep(workflowService))
    {
    }
}

// A workflow with a custom implementation.
public class CustomWorkflowStep
{
    private readonly WorkflowService workflowService;

    public CustomWorkflowStep(WorkflowService workflowService)
    {
        this.workflowService = workflowService;
    }

    public UserConsentStepForTestWorkflow PerformCustomStep()
    {
        // Custom step implemementation
        // Then return the next step
        return new UserConsentStepForTestWorkflow(workflowService);
    }
}

```

## 3. Retrieving Transaction Status and Details

`JumioClient` provides two retrieveData() methods for retrieving transaction data:

- `public WorkflowExecutionResponse RetrieveData(CallbackRequestBody callbackRequestBody)`
  Use this method when you are Implementing a Callback Service.

- `public WorkflowExecutionResponse RetrieveData(AccountId accountId, WorkflowExecutionId workflowExecutionId)`
  Use this method to retrieve data using the account ID and workflow execution ID.

---

# Upgrade From Previous Versions

https://documentation.jumio.ai/docs/Integrate/upgrading

# Platform Transition

Upgrading to the latest version of the Jumio Platform is designed to be as straightforward as possible, requiring minimal effort on your part. We provide step-by-step guides and resources to ensure a smooth and seamless transition, allowing you to quickly benefit from enhanced features and capabilities. Your success is our priority, and we're here to support you every step of the way.

- Netverify (v2) Users: Refer [Upgrading from Netverify to the Jumio Platform](../Integrate/netVerifyv2/upgrading-from-netverify) for a step-by-step transition guide tailored to your needs.
- v3 Users: Checkout [Upgrading from v3](../Integrate/upgrading-from-v3) for detailed instructions on updating from the initial platform release.

These resources provide clear and actionable steps to ensure a smooth transition, allowing you to take full advantage of Jumio's advanced functionality and improved user experience.

---

# Upgrade from v3

https://documentation.jumio.ai/docs/Integrate/upgrading-from-v3

# Upgrade from v3

The Jumio Platform API is backward compatible with v3. Upgrading to the current Jumio Platform requires minimal changes to your integration. The most significant changes include:

- [Retrieval Details](#retrieval-details)
- [Workflow Keys](#workflow-keys)

## What Remains the Same ?

- **API Authentication** (although you are strongly encouraged to migrate to using OAuth2 Bearer Tokens instead of Basic Authentication, if you have not already done so. See [Authorization](https://documentation.jumio.ai/docs/developer-resources/API/authorization) for additional information).
- **API endpoints**. The APIs you are used to using for account initialization, credential acquisition, transaction status, transaction detail retrieval, and credential deletion remain the same.
- **Transactions** available in the Jumio Portal. Your v3 transactions are accessible through the Portal along with new transactions.

## Retrieval Details

The transaction details return two additional objects:

- A decision object with the overall dicision and risk score for the transaction. For example,

```
   "decision": {
      "type": "PASSED",
      "details": {
         "label": "PASSED"
      },
      "risk": {
         "score": 0.0
      }
   },
   ...
```

Also refer: [Transaction Decisions and Risk Scores](https://documentation.jumio.ai/docs/developer-resources/retrieval#transaction-decisions-and-risk-scores)

- A steps object that provides the URL to the new API for retrieving [Workflow Steps](https://documentation.jumio.ai/docs/developer-resources/retrieval#workflow-steps)

## Workflow Keys

The v3 workflows all have corresponding Jumio Platform workflows that return the new details, in addition to taking advantage of the underlying platform improvements. You can take advantage of the new workflows by simply entering the new key in your account request.

:::info
You can request automatic mapping of all v3 workflow keys to the updated Platform workflow keys by contacting [Support](https://support.jumio.com/s/).
:::

### Workflow Key Mapping

The following table maps v3 Workflow Keys and Descriptions to their corresponding Jumio Platform Workflow Keys and Descriptions.

| **v3 Workflow Key and Description**                          | **Jumio Platform Workflow Key and Description**                   |
| ------------------------------------------------------------ | ----------------------------------------------------------------- |
| Workflow 1: ID Capture and Storage                           | 10031: ID Capture and Storage                                     |
| Workflow 2: ID Verification                                  | 10549: Jumio ID + Selfie Verification with Optional Prepared Data |
| Workflow 3: ID and Selfie Verification                       | 10166: Jumio ID Verification with Optional Prepared Data          |
| Workflow 5: Similarity to Existing ID                        | 10025: Similarity to Existing ID                                  |
| Workflow 6: Standalone Liveness                              | 10016: Standalone Liveness                                        |
| Workflow 9: Authentication                                   | 10014: Jumio Authentication                                       |
| Workflow 16: Authentication On-Premises                      | 10071: Authentication On-Premises                                 |
| Workflow 20: Similarity of Two Images                        | 10024: Similarity of Two Images                                   |
| Workflow 32: ID Verification, Selfie Verification, Screening | 10032: ID + Selfie + Screening                                    |

---

# Netverify

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/upgrading-from-netverify

# Key Differences & Migration

The Jumio Platform is a significant evolution from the earlier Netverify (sometimes referred to as v2) versions of Jumio products. Upgrading from Netverify requires your organization to develop and integrate the new APIs and SDKs with your applications. Work with Jumio Support to have your Netverify transaction data migrated to the Jumio Platform. Migrated data will continue to be available through the Netverify Customer Portal and API as well as through the Jumio Portal and the Jumio Platform APIs.

:::warning
Using the Netverify API to delete transactions will also delete the migrated transactions from the Jumio Platform. Deleted transactions will not be available in the Jumio Portal and cannot be retrieved through the API.
:::

The following information identifies significant differences between Netverify versions and the Jumio Platform, provides links to relevant documentation, and provides mappings between Netverify features and corresponding Jumio Platform features:

- [New Enhancements](#new-enhancements)
- [Netverify Products to Jumio Workflows Mapping](./v2toJumioWorkFlowMapping)
- [Netverify to Jumio Platform Transaction Data Mapping](./v2TransactionDataMapping/v2toJumioTransactionData)

## New Enhancements

Discover the notable enhancements and improvements introduced in the Jumio Platform compared to earlier versions. Below, we’ve highlighted the key updates along with links to detailed documentation for easy reference.

- [Jumio API Authentication: Transition from Basic Auth to OAuth2 Tokens](#jumio-api-authentication-transition-from-basic-auth-to-oauth2-tokens)
- [Initiating a Transaction](#initiating-a-transaction)
- [Callbacks](./Callbacks-Retrieval-Netverify#netverify-callbacks)
- [Retrieval APIs](./Callbacks-Retrieval-Netverify#retrieval-api)

The Jumio Portal replaces previous Jumio customer portals as the user interface for reviewing transactions, accessing reports, and managing configuration options. See Welcome to the Jumio Portal.

### Jumio API Authentication: Transition from Basic Auth to OAuth2 Tokens

Authorization for the Jumio REST APIs has changed. Basic authentication is deprecated. Oauth2 bearer tokens are required to authorize API calls. [Checkout](../../developer-resources/API/authorization)

In v2, you can authenticate each API call using [basic credentials](https://en.wikipedia.org/wiki/Basic_access_authentication) (token + secret). The Jumio Platform supports [OAuth2 bearer tokens](https://oauth.net/2/bearer-tokens/) for authentication. You can generate a bearer token by calling a dedicated API endpoint.

:::note
While the Jumio Platform continues to support basic authentication, you are strongly encouraged to use the more secure bearer tokens. Support for basic authentication will be discontinued at some point in the future.
:::

#### Netverify API Authentication

All Document Verification API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Jumio Portal under Settings > API credentials.

:::caution
Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.
:::

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see supported cipher suites.

#### Jumio Platform API Authentication

All calls to Jumio REST APIs should be authorized using OAuth2 Bearer Tokens. You obtain the bearer token by calling the Access Token URL (OAuth2) for your region with your API token and secret values, which you can find in the Jumio Portal under:

**_Settings > Identity Verification > API credentials > OAuth2 Clients_**

See [Authorization](../../developer-resources/API/authorization)

### Initiating a Transaction

Jumio Platform transactions are associated with an account ID, which allows multiple transactions to be associated with an end user. A transaction is initated by either creating or updating an account. The set of Jumio services used to process the transaction is controlled by a workflow that is specified as part of the request to create or update the account. Refer the following:

- [Integrating Jumio Services](../../developer-resources/integration) for an overview of accounts, credentials, workflows, and transactions on the Jumio Platform.
- [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) for information on the relevant APIs for initiating a transaction.
- [Services and Workflows Reference](/docs/references/servicesAndworkflow/services-workflow) for reference information on standard workflows and customization options.

#### Initiating a Transaction in v2

Jumio's Netverify API allowed new transactions to be instantiated without context. You could create a new transaction for any user at any time with the same API call. The services executed by a given transaction were determined either by the API endpoint itself, or by including/removing certain API body parameters. There was no way to associate multiple transactions with the same user.

**How did user attribution work in v2?**

By using the **"customerId"** field, you could associate a given scan to a user. However, Jumio provided no out-of-the-box management infrastructure for your user/customer objects. You had to track and manage your own users indexed by customer ID fields that you could define arbitrarily.

**Example: /initiate Request Body**

```
{
"customerInternalReference" : "transaction_1234",
"userReference" : "user_1234",
"successUrl" : "https://www.abc.com/success",
"errorUrl" : "https://www.abc.com/error",
"callbackUrl" : "https://www.abc.com/callback",
"reportingCriteria" : "myReport1234",
"workflowId" : 200,
"presets" :
   [
     {
         "index"   : 1,
        "country" : "AUT",
        "type"    : "PASSPORT"
      }
   ],
"locale" : "en-GB"
}
```

**Response**

```
{
  "timestamp": "2018-07-03T08:23:12.494Z",
  "transactionReference": "xxxxxxxx-...-xxxxxx",
  "redirectUrl": "https://abc.NetVerify.com/..."
}
```

**Example: /performNetVerify Request Body**

```
{
   "merchantIdScanReference":"",
   "country":"",
   "idType":"",
    "frontsideImage":"/9j/4AA...AEB//2Q=="

    "userConsent": {
      "userIp": "226.80.211.232",
      "userLocation": {
         "country": "USA",
         "state": "IL"
      },
       "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-07-20T17:20:35.000Z"
      }
   }


   "enabledFields":"idNumber,idFirstName,...",
   "merchantReportingCriteria":"",
   "customerId":"",
   "firstName":"firstName",
   "lastName":"lastName",
    "expiry":"2015-01-01",
   "number":"123456789",
   "dob":"1970-01-01",
   "personalNumber":"123",
   "callbackGranularity":"onAllSteps",
   "mrzCheck":true,
   "frontsideImageMimeType":"image/jpeg",
   "callbackUrl":"https://….",
   [...]
    }
```

**Response**

```
{
   "timestamp": "2017-08-16T10:37:44.623Z",
   "jumioIdScanReference": "xxxxxxxx-xxxx-..."
}
```

#### Initiating a Transaction in the Jumio Platform

The Jumio Platform enhances user-management by introducing new concepts for supporting multiple transactions for a single end userClosed, including accountsClosed, and workflows.

Each of your end users who interacts with Jumio has their own accountClosed. Think of each account as a container for the transactions and documents associated with the user.

Instead of calling an endpoint for a specific service you call an /accounts endpoint. To initiate the first transaction for a new end user you use a POST request to initiate the transaction and create a new account. To initiate a subsequent transaction for the same end user you use a PUT request with the account ID as a path parameter. The Jumio services that will be used for the transaction are determined by the workflow key value that is specified in the request body.

Checkout:

- [Create, Update or Link Accounts](https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts)
- [Integrate Jumio Services](https://documentation.jumio.ai/docs/developer-resources/API/Integration_Intro)

##### Example /api/v1/accounts Request Body

```
{
   "customerInternalReference":"myOrganization",
   "workflowDefinition":{
      "key": 10015
   }
}
```

The response provides all of the information required to acquire the end user's credentials and finalize the transaction.

##### Example Response

```
{
    "timestamp": "2022-11-28T23:45:02.536Z",
    "account": {
        "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
    },
    "web": {
        "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&locale=en-US"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
    },
    "workflowExecution": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "credentials": [
            {
                "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            },
            {
                "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            }
        ]
    }
}
```

---

# Netverify to Jumio Platform Transaction Data Mapping

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/Callbacks-Retrieval-Netverify

# Callbacks and Retrieval API - Netverify to the Jumio Platform

Callbacks in the Jumio Platform do not return any PII data for the transaction. Jumio Platform callbacks only provide the transaction status and metadata. To access transaction details you must call the retrieval APIs.

Learn more about **callback** [here](https://documentation.jumio.ai/docs/developer-resources/callback).

## Netverify Callbacks

Netverify callbacks included complete transaction details as URL parameters appended to your callback URL.

### Example Callback Parameters

```
idExpiry=2022-12-31&idType=PASSPORT&idDob=....
```

## Jumio Platform Callbacks

Jumio Platform callbacks do not contain any PII data. Transaction status and metadata are provided as the body of the POST request sent to your Callback URL.

### Example Callback Request Body

```
{
  "callbackSentAt":"2021-01-21T14:55:01.917Z",
  "workflowExecution":{
    "id":"22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "definitionKey":"3",
    "status":"PROCESSED"
},
  "account":{
    "id":"11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}
```

## Retrieval API

The APIs and data model for retrieving transactions have changed.

For more information checkout,

- [Calling Retrieval APIs](https://documentation.jumio.ai/docs/developer-resources/retrieval#calling-retrieval-apis)
- [Netverify to Jumio Platform Transaction Data Mapping](./v2TransactionDataMapping/v2toJumioTransactionData)

### Netverify Retrieval APIs

Netverify retrieval APIs used different endpoints for different Jumio products, such as ID Verification, Document Verification, and Authorization.

#### Examples Details Response

<details>
```
{
    "timestamp": "2019-03-20T16:25:38.663Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-...",
    "document": {
        "type": "DRIVING_LICENSE",
        "dob": "1990-01-01",
        "expiry": "2022-12-31",
        "firstName": "FIRST NAME",
        "issuingCountry": "AUT",
        "issuingDate": "2013-01-01",
        "lastName": "LAST NAME",
        "number": "123456789",
        "status": "APPROVED_VERIFIED"
    },
    "transaction": {
        "clientIp": "XX.XX.X.XX",
        "customerId": "CUSTOMERID",
        "date": "2019-01-01T11:01:10.227Z",
        "merchantReportingCriteria": "...",
        "merchantScanReference": "...",
        "source": "WEB_UPLOAD",
        "status": "DONE"
    },
    "verification": {
        "identityVerification": {
            "similarity": "MATCH",
            "validity": "true"
        },
        "mrzCheck": "NOT_AVAILABLE"
    },
		"facemap": {
        "classifier": "facemap",
        "href": "https://netverify.com/api/netverify/v2/scans/xxx..."
    }
}
```
</details>

### Jumio Platform Retrieval APIs

The structure of Jumio Platform detail responses provide separate objects for credentialsClosed and capabilitiesClosed.

#### Example Details Response

<details>
```
{
    "workflow": {
        "id": "9541ae91-834e-4914-a30d-6534fed4eb6d",
        "status": "PROCESSED",
        "definitionKey": "10549",
        "userReference": "FBC02D3F-C3B5-4B19-A663-00AE0886A704_1660925181283",
        "customerInternalReference": "test ref"
    },
    "account": {
        "id": "310ede34-41ab-4f2b-ac47-b5c3553edf03"
    },
    "createdAt": "2022-11-07T22:56:00.112Z",
    "startedAt": "2022-11-07T22:57:34.012Z",
    "completedAt": "2022-11-07T22:57:47.892Z",
    "credentials": [
        {
            "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
            "category": "SELFIE",
            "parts": [
                {
                    "classifier": "FACE",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/7e5ad90a-9277-44d4-a5cb-7797420220fc/parts/FACE"
                }
            ]
        },
        {
            "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/b420829c-abe6-4df8-93cb-93f85cd9d5ac/parts/FRONT"
                },
                {
                    "classifier": "BACK",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/b420829c-abe6-4df8-93cb-93f85cd9d5ac/parts/BACK"
                }
            ]
        },
        {
            "id": "78974167-956f-4087-b4f1-04782c929e05",
            "category": "FACEMAP",
            "parts": [
                {
                    "classifier": "FACEMAP"
                },
                {
                    "classifier": "LIVENESS_1",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_1"
                },
                {
                    "classifier": "LIVENESS_3",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_3"
                },
                {
                    "classifier": "LIVENESS_2",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_2"
                },
                {
                    "classifier": "LIVENESS_5",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_5"
                },
                {
                    "classifier": "LIVENESS_4",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_4"
                },
                {
                    "classifier": "LIVENESS_6",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_6"
                }
            ]
        }
    ],
    "decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    },
    "steps": {
        "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/workflow-executions/9541ae91-834e-4914-a30d-6534fed4eb6d/steps"
    },
    "capabilities": {
        "extraction": [
            {
                "id": "29ddc912-d5dd-4750-85ba-10d969556d32",
                "credentials": [
                    {
                        "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "DRIVING_LICENSE",
                    "subType": "REGULAR_DRIVING_LICENSE",
                    "issuingCountry": "USA",
                    "firstName": "THOMAS JACOB",
                    "lastName": "GOERING",
                    "dateOfBirth": "1957-01-18",
                    "expiryDate": "2025-01-18",
                    "issuingDate": "2019-12-26",
                    "documentNumber": "N7624107",
                    "state": "CA",
                    "gender": "M",
                    "currentAge": "65"
                }
            }
        ],
        "similarity": [
            {
                "id": "76a58e7b-b9db-493d-9a8b-a1756e499085",
                "credentials": [
                    {
                        "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
                        "category": "SELFIE"
                    },
                    {
                        "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "MATCH"
                    }
                },
                "data": {
                    "similarity": "MATCH"
                }
            }
        ],
        "liveness": [
            {
                "id": "bfa003f6-c400-4696-973c-7dbdf890006b",
                "credentials": [
                    {
                        "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
                        "category": "SELFIE"
                    },
                    {
                        "id": "78974167-956f-4087-b4f1-04782c929e05",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "predictedAge": 46,
                    "ageConfidenceRange": "34-58"
                }
            }
        ],
        "dataChecks": [
            {
                "id": "1d0587eb-aca3-41a7-be70-fbcd08de420c",
                "credentials": [
                    {
                        "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ],
        "imageChecks": [
            {
                "id": "1110bc6c-708c-444d-b41a-6164d71e3c6f",
                "credentials": [
                    {
                        "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
                        "category": "SELFIE"
                    },
                    {
                        "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "REPEATED_FACE"
                    }
                },
                "data": {
                    "faceSearchFindings": {
                        "status": "DONE",
                        "findings": [
                            "22771260-8cb0-42a2-a38a-d8f853063cc2",
                            "27232651-4b18-4cf1-8d4a-df0451abc717"
                        ]
                    }
                }
            }
        ],
        "usability": [
            {
                "id": "70ee4aad-fde7-44f9-92f9-97ca77c28f09",
                "credentials": [
                    {
                        "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "9fb1876e-6078-4ea5-aba6-d68c200634fb",
                "credentials": [
                    {
                        "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "810cb95c-a7d0-46fc-bd2a-45b241a669f8",
                "credentials": [
                    {
                        "id": "78974167-956f-4087-b4f1-04782c929e05",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
    }
}
```

</details>

---

# Netverify Products to Jumio Workflows Mapping

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2toJumioWorkFlowMapping

# Product Mapping

## Netverify Products to Jumio Workflows Mapping

Jumio provides standalone workflows that call the services that provide the functionality corresponding to the products.

| Service                                            | Mapped Workflow Key | Description                                                                                                                                      | Credentials         | Capabilities                                                                                |
| -------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- |
| **ID & Selfie Verification**                       | 10549               | Verifies a government-issued ID and a selfie. Ensures ID authenticity and matches selfie with ID photo. Also includes uploading supporting data. | ID, Selfie, Facemap | Usability, Extraction, Image Checks, Data Checks, Liveness, Similarity                      |
| **ID Verification**                                | 10015               | Verifies the authenticity and validity of a government-issued photo ID. Requires uploading supporting data.                                      | ID                  | Usability, Extraction, Image Checks, Data Checks                                            |
| **ID & Selfie Verification + Watchlist Screening** | 10032               | Includes all ID & Identity Verification functionality plus Watchlist Screening for sanctions and PEP identification.                             | ID, Selfie, Facemap | Usability, Extraction, Image Checks, Data Checks, Liveness, Similarity, Watchlist Screening |
| **Document Verification**                          | 10026               | Verifies documents such as utility bills, bank statements, etc. Extracts relevant data for use in other services or risk signals.                | Document            | Usability, Extraction, Image Checks                                                         |
| **Fastfill/ID Capture and Storage**                | 10031               | Extracts and stores data from a government-issued ID.                                                                                            | ID                  | Usability, Extraction                                                                       |

For further information, refer [Capabilities](https://documentation.jumio.ai/docs/references/capabilities/) and [Credentials](https://documentation.jumio.ai/docs/references/credentials/).

---

# Transaction Data Mapping

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/v2toJumioTransactionData

# Transaction Data Mapping

## Netverify to Jumio Platform Transaction Data Mapping

The data model for Jumio Platform transactions is different from the data model for Netverify ID verification transactions. In general, the Jumio Platform data is more complex than the Netverify data, reflecting the additional workflow steps and capability options that are available in the Jumio Platform. The purpose of this document is to provide a mapping from common fields and values in the Netverify data to corresponding fields and values in the Jumio Platform data, to help facilitate the transition from the former to the latter.

## Callbacks

Jumio Platform callbacks do not include decision details about the transaction. They are intended to convey whether or not the workflow completed, and provide other metadata. All details about the transaction can be obtained by calling the retrieval APIs.

## Retrieval API Responses

A Netverify ID verification transaction includes an overall status result and details including:

- Transaction metadata.
- Document data describing the scanned or uploaded documents, including the status and reject reasons if applicable.
- Verification data describing whether or not the selfie matches the document, and any reject reasons.

Jumio Platform transactions execute:

- A defined workflow consisting of a sequence of steps.
- The workflow is passed a set of credentials, including any scanned or uploaded documents and the selfie, which are then passed to each step in turn.
- Each step is implemented by one or more capabilities that perform some specific task. Each capability evaluates the credentials and generates decision data.

The workflow renders an overall decision based on the cumulative results of the decisions rendered by each capability.

The mappings in the following section identify the data fields in the Jumio workflows and capabilities that most directly correlate with the transaction, document, and verification fields in the Netverify transactions.

For example, a typical Netverify transaction includes a “document” object with fields for the values extracted from the scanned or uploaded document:

```
"document": {
        "type": "DRIVING_LICENSE",
        "dob": "1990-01-01",
        "expiry": "2022-12-31",
        "firstName": "FIRST NAME",
        "issuingCountry": "AUT",
        "issuingDate": "2013-01-01",
        "lastName": "LAST NAME",
        "number": "123456789",
        "status": "APPROVED_VERIFIED"
    },
```

In a Jumio Platform transaction, the corresponding values are in a nested object for a capability called “extraction” that is contained in a top-level “capabilities” array:

```
"capabilities": {
        "extraction": [
            {
                "id": "1a11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "PASSPORT",
                    "subType": "E_PASSPORT",
                    "firstName": "JANE",
                    "lastName": "DOE",
                    "dateOfBirth": "1990-01-01",
                    "expiryDate": "2023-12-01",
                    "issuingDate": "2014-01-01",
                    "documentNumber": "xxxxxxxx",
                    "personalNumber": "<<<<<<<<<<<<<<",
                    "address": {
                        "country": "AUT",
                        "formattedAddress": "AUT"
                    }
                }
            }
        ],
```

Similarly, the Netverify transaction includes a “verification” object that includes a nested “identityVerification” object with values for “similarity” and “validity” that provide the results of the comparison of the selfie to the picture on the photo ID:

```
"verification": {
        "identityVerification": {
            "similarity": "MATCH",
            "validity": "true"
        }
}
```

In the Jumio Platform transaction, each scan or uploaded document in the transaction is passed to a set of capabilities, depending on the type of scan or document. The selfie is passed to a capability called “liveness” that provides a “decision” object with a nested “details” object that contains a “label” value corresponding to the Netverify “similarity” value:

```
"capabilities": {"liveness": [
    {
        "id": "fdf7a6f2-2905-45da-a4ec-587d590795cc",
        “validFaceMapForAuthentication”: “https://retrieval.emea-1.jumio.link/api/v1/accounts/3dceeccd-d364-4c16-8769-514a8f76bb89/credentials/f518e6c4-20b1-4d66-b1d1-92b9face8bf0/parts/FACEMAP”,
        "credentials": [
            {
                "id": "6760a8e4-f1ee-4209-a43c-5e66526ac166",
                "category": "SELFIE"
            },
            {
                "id": "09cc66aa-03d2-4951-b38d-bbd07d6998fd",
                "category": "FACEMAP"
            }
        ],
        "decision": {
            "type": "REJECTED",
            "details": {
                "label": "LIVENESS_UNDETERMINED"
            }
        },
        "data": {
            "type": "JUMIO_STANDARD"
        }
    }
],
```

The tables in the following section provide specific mappings between values in the Netverify transactions and the Jumio Platform transactions.

## Status and Reason Mappings

- [Transaction Status Values](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings)

- [Verification Reject Reasons](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings#verification-reject-reasons)

- [Identity Verification Responses](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/IDverification)

- [Reject Reason Details](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/rejectReason)

- [Retrieval Response Examples](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/retrievalResponse)

---

# Status and Reason Mappings

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings

# Status and Reason Mappings

- [Transaction Status Values](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings)

- [Verification Reject Reasons](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings#verification-reject-reasons)

- [Identity Verification Responses](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/IDverification)

- [Reject Reason Details](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/rejectReason)

- [Retrieval Response Examples](/docs/Integrate/netVerifyv2/v2TransactionDataMapping/retrievalResponse)

## Transaction Status Values

### Jumio Plaform Status

| **Status**      | **Description**                                                           |
| --------------- | ------------------------------------------------------------------------- |
| INITIATED       | The transaction has been created but no data has been captured yet        |
| ACQUIRED        | Required data (e.g., images or inputs) has been successfully captured     |
| PROCESSED       | The transaction has been processed and results are available              |
| SESSION_EXPIRED | The user session expired before completing the transaction                |
| TOKEN_EXPIRED   | The authorization token expired before the transaction could be completed |

### Netverify Status

| **Status**      | **Description**                                                           |
| --------------- | ------------------------------------------------------------------------- |
| PENDING         | The transaction is created and waiting to be initiated                    |
| INITIATED       | The verification process has started                                      |
| ACQUIRED        | Required data (e.g., images or inputs) has been successfully captured     |
| DONE            | The verification flow is completed from the user side                     |
| PROCESSED       | The transaction has been processed and results are available              |
| FAILED          | The verification process failed due to an error or rejection              |
| SESSION_EXPIRED | The user session expired before completing the transaction                |
| TOKEN_EXPIRED   | The authorization token expired before the transaction could be completed |

## Verification Reject Reasons

For a Netverify transaction, if a scanned or uploaded document has a status value other than APPROVED_VERIFIED, the verification data includes a rejectReason object that includes a code number and a description. A Jumio Platform transaction includes an overall decision that is based on the decisions rendered by each capability in the transaction workflow. Values corresponding to the reject reason descriptions are contained in nested decision.details.label fields provided by each capability.

For each Netverify document status the table shows the associated verification reject reason codes and descriptions, and the corresponding capability decision detail label in the Jumio Platform.

### Document Status: APPROVED_VERIFIED

| Netverify: document.status | Jumio Platform Capability: code decision.details.label |
| -------------------------- | ------------------------------------------------------ |
| APPROVED_VERIFIED          | All capabilities: OK                                   |

### Document Status: DENIED_FRAUD

| Netverify: `verification.rejectReason` `rejectReasonDescription` | Jumio Platform Capability: `decision.details.label` | Description                                                                                                       |
| ---------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [100] MANIPULATED_DOCUMENT                                       | IMAGE_CHECKS: LOOKUPS_HIGH_RISK_SIMILAR_IMAGE       | The image of the ID document closely resembles a past transaction with different data.                            |
| [106] FAKE                                                       | IMAGE_CHECKS: FAKE                                  | The submitted document appears to be counterfeit or not a genuine identity document.                              |
| [107] PHOTO_MISMATCH                                             | IMAGE_CHECKS: GHOST_IMAGE_DIFFERENT                 | The portrait on the document does not match the expected identity image or appears to have been substituted.      |
| [108] MRZ_CHECK_FAILED                                           | DATA_CHECKS: MRZ_CHECKSUM                           | The Machine Readable Zone (MRZ) contains invalid or inconsistent checksum values.                                 |
| [110] CHIP_DATA_MANIPULATED                                      | DATA_CHECKS: NFC_CERTIFICATE                        | The NFC chip data or certificate indicates possible manipulation or tampering.                                    |
| [111] MISMATCH_PRINTED_BARCODE_DATA                              | DATA_CHECKS: MISMATCHING_DATAPOINTS                 | The printed document data does not match the information encoded in the barcode.                                  |
| [112] CHIP_MISSING                                               | IMAGE_CHECKS: CHIP_MISSING                          | An NFC chip is expected for this document type but was not detected.                                              |
| [113] MISMATCHING_DATA_REPEATED_FACE                             | DATA_CHECKS: MISMATCHING_DATA_REPEATED_FACE         | The document contains inconsistent identity data associated with the same facial image.                           |
| [114] DIGITAL_MANIPULATION                                       | IMAGE_CHECKS: DIGITAL_MANIPULATION                  | The ID image shows evidence of digital editing or alteration.                                                     |
| [115] MISMATCH_HRZ_MRZ_DATA                                      | DATA_CHECKS: MISMATCH_HRZ_MRZ_DATA                  | The Human Readable Zone (HRZ) data does not match the Machine Readable Zone (MRZ) data.                           |
| [116] SUPERIMPOSED_TEXT                                          | IMAGE_CHECKS: SUPERIMPOSED_TEXT                     | One or more text fields on the ID image show digital or physical manipulations.                                   |
| [118] MISMATCH_FRONT_BACK                                        | IMAGE_CHECKS: MISMATCH_FRONT_BACK                   | The front and back images belong to different documents or contain inconsistent information.                      |
| [119] HIGH_FRAUD_RISK                                            | DATA_CHECKS: HIGH_FRAUD_RISK                        | Multiple fraud indicators were detected, resulting in a high fraud risk assessment.                               |
| [133] MANIPULATED_DOCUMENT_LOW_CONFIDENCE                        | IMAGE_CHECKS: MANIPULATED_DOCUMENT_LOW_CONFIDENCE   | The image of the ID document resembles a past transaction with different data. This is a low-confidence warning.  |
| [205] PUNCHED_DOCUMENT                                           | IMAGE_CHECKS: PUNCHED                               | The document appears to have been physically punched, perforated, or intentionally damaged.                       |
| [303] SUPERIMPOSED_TEXT_LOW_CONFIDENCE                           | IMAGE_CHECKS: SUPERIMPOSED_TEXT_LOW_CONFIDENCE      | One or more text fields on the ID image show digital or physical manipulations. This is a low-confidence warning. |

### Document Status: DENIED_UNSUPPORTED_ID_TYPE

| Netverify : document.status | Jumio Platform Capability: decision.details.label |
| --------------------------- | ------------------------------------------------- |
| DENIED_UNSUPPORTED_ID_TYPE  | USABILITY: UNSUPPORTED_DOCUMENT_TYPE              |

### Document Status: DENIED_UNSUPPORTED_ID_COUNTRY

| Netverify : document.status   | Jumio Platform Capability: decision.details.label |
| ----------------------------- | ------------------------------------------------- |
| DENIED_UNSUPPORTED_ID_COUNTRY | USABILITY: UNSUPPORTED_COUNTRY                    |

### Document Status: ERROR_NOT_READABLE_ID

| Netverify: verification.rejectReason rejectReasonDescription | Jumio Platform Capability: decision.details.label |
| ------------------------------------------------------------ | ------------------------------------------------- |
| [210] CAMERA_BLACK_WHITE                                     | USABILITY: BLACK_WHITE                            |
| [214] MISSING_FRONT                                          | USABILITY: MISSING_PAGE                           |
| [209] MISSING_SIGNATURE                                      | USABILITY: MISSING_SIGNATURE                      |
| [201] NO_DOCUMENT                                            | USABILITY: NOT_A_DOCUMENT                         |
| [200] NOT_READABLE_DOCUMENT                                  | USABILITY: BAD_QUALITY                            |
| [103] PHOTOCOPY_COLOR                                        | USABILITY: PHOTOCOPY                              |
| [104] DIGITAL_COPY                                           | USABILITY: DIGITAL_COPY                           |
| [211] DIFFERENT_PERSONS_SHOWN                                | IMAGE_CHECKS: DIFFERENT_PERSON                    |
| [213] INVALID_WATERMARK                                      | IMAGE_CHECKS: WATERMARK                           |
| [300] MANUAL_REJECTION                                       | IMAGE_CHECKS: OTHER_REJECTION                     |
| [202] SAMPLE_DOCUMENT                                        | IMAGE_CHECKS: SAMPLE                              |

### Document Status: NO_ID_UPLOADED

| Netverify: document.status | Jumio Platform Capability: decision.details.label |
| -------------------------- | ------------------------------------------------- |
| NO_ID_UPLOADED             | USABILITY: NOT_UPLOADED                           |

---

# Identity Verification Responses

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/IDverification

# Identity Verification Responses

| **Netverify: verification.identityVerification** | **Jumio Platform: Dependency: usability**      |
| ------------------------------------------------ | ---------------------------------------------- |
| **similarity**                                   | **capabilities.similarity**                    |
| MATCH                                            | decision.type: PASSED                          |
|                                                  | decision.details.label: MATCH                  |
|                                                  | data.similarity: MATCH                         |
| NO_MATCH                                         | decision.type: REJECTED                        |
|                                                  | decision.details.label: NO_MATCH               |
|                                                  | data.similarity: NO_MATCH                      |
| NOT_POSSIBLE                                     | decision.type: WARNING                         |
|                                                  | decision.details.label: NOT_POSSIBLE           |
|                                                  | data.similarity: NOT_POSSIBLE                  |
|                                                  |                                                |
| **validity**                                     | **capabilities.liveness**                      |
| FALSE                                             | decision.type: REJECTED                        |
|                                                  | decision.details.label: LIVENESS_UNDETERMINED  |
|                                             | decision.details.label: LIVENESS_FAILED        |
|                                                  |                                                |
| NO_FACE_PRESENT                                  | decision.type: REJECTED                        |
|                                                  | decision.details.label: NO_FACE_PRESENT        |
| MULTIPLE_PEOPLE                                  | decision.type: REJECTED                        |
|                                                  | decision.details.label: MULTIPLE_PEOPLE        |
| FACE_NOT_FULLY_VISIBLE                           | decision.type: REJECTED                        |
|                                                  | decision.details.label: FACE_NOT_FULLY_VISIBLE |
| BLACK_AND_WHITE                                  | decision.type: REJECTED                        |
|                                                  | decision.details.label: BLACK_AND_WHITE        |
| BAD_QUALITY                                      | decision.type: WARNING                         |
|                                                  | decision.details.label: BAD_QUALITY            |
| AGE_DIFFERENCE_TOO_BIG                           | decision.type: WARNING                         |
|                                                  | decision.details.label: AGE_DIFFERENCE         |
| ENTIRE_ID_USED_AS_SELFIE                         | decision.type: REJECTED                        |
|                                                  | decision.details.label: ID_USED_AS_SELFIE      |
| SELFIE_CROPPED_FROM_ID                           | decision.type: REJECTED                        |
|                                                  | decision.details.label: ID_USED_AS_SELFIE      |
| SELFIE_IS_SCREEN_PAPER_VIDEO                     | decision.type: REJECTED                        |
|                                                  | decision.details.label: DIGITAL_COPY           |
| SELFIE_MANIPULATED                               | decision.type: REJECTED                        |
|                                                  | decision.details.label: MANIPULATED            |
|                                                  | decision.details.label: PHOTOCOPY              |

---

# Reject Reason Details

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/rejectReason

# Reject Reason Details

## rejectReasonCode = 100

| Netverify: verification.rejectReason.rejectReasonDetails detailsCode detailsDescription | Jumio Platform Capability: decision.details.label |
| --------------------------------------------------------------------------------------- | ------------------------------------------------- |
| 1001 PHOTO                                                                              | imageChecks: MANIPULATED_DOCUMENT_PHOTO           |
| 1002 DOCUMENT_NUMBER                                                                    | imageChecks: MANIPULATED_DOCUMENT_DOCUMENT_NUMBER |
| 1003 EXPIRY                                                                             | imageChecks: MANIPULATED_DOCUMENT_EXPIRY          |
| 1004 DOB                                                                                | imageChecks: MANIPULATED_DOCUMENT_DOB             |
| 1005 NAME                                                                               | imageChecks: MANIPULATED_DOCUMENT_NAME            |
| 1006 ADDRESS                                                                            | imageChecks: MANIPULATED_DOCUMENT_ADDRESS         |
| 1007 SECURITY_CHECKS                                                                    | imageChecks: MANIPULATED_DOCUMENT_SECURITY_CHECKS |
| 1008 SIGNATURE                                                                          | imageChecks: MANIPULATED_DOCUMENT_SIGNATURE       |
| 1009 PERSONAL_NUMBER                                                                    | imageChecks: MANIPULATED_DOCUMENT_PERSONAL_NUMBER |
| 10011 PLACE_OF_BIRTH                                                                    | imageChecks: MANIPULATED_DOCUMENT_PLACE_OF_BIRTH  |
| 10012 GENDER                                                                            | imageChecks: MANIPULATED_DOCUMENT_GENDER          |
| 10013 ISSUING_DATE                                                                      | imageChecks: MANIPULATED_DOCUMENT_ISSUING_DATE    |

## rejectReasonCode = 200

| Netverify: verification.rejectReason.rejectReasonDetails detailsCode detailsDescription | Jumio Platform Capability: decision.details.label |
| --------------------------------------------------------------------------------------- | ------------------------------------------------- |
| 2001 BLURRED                                                                            | usability: BLURRED                                |
| 2002 BAD_QUALITY                                                                        | usability: BAD_QUALITY_IMAGE                      |
| 2003 MISSING_PART_DOCUMENT                                                              | usability: PART_OF_DOCUMENT_MISSING               |
| 2004 HIDDEN_PART_DOCUMENT                                                               | usability: PART_OF_DOCUMENT_HIDDEN                |
| 2005 DAMAGED_DOCUMENT                                                                   | usability: DAMAGED_DOCUMENT                       |
| 2006 GLARE                                                                              | usability: GLARE                                  |
| 2007 MISSING_MANDATORY_DATAPOINTS                                                       | usability: MISSING_MANDATORY_DATAPOINTS           |

---

# Retrieval Response Examples

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/retrievalResponse

# Retrieval Response Examples

The following retrieval response examples show typical fields and values that are captured for a transaction. They are provided to assist with understanding the differences in the data models.

`Netverify /v2/scans/<scanReference>/data Response`

A GET request to the /v2/scans/&lt;scanReference&gt;/data API returns a JSON object containing nested objects for document, transaction, and verification.

:::info
the &lt;scanReference&gt; value is obtained from the response to the call to the Netverify Acquisitions API
:::

https://acquisition.netverify.com/api/netverify/v2/acquisitions API:

## Response

```
{
"timestamp": "2017-10-17T06:37:51.969Z",
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

For additional information see: [ID Verification Retrieval API Implementation Guide](../../../references/servicesAndworkflow/standardService/IDIVService#handling-the-idiv-response)

## Example

```
{
    "timestamp": "2019-03-20T16:25:38.663Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "document": {
        "type": "DRIVING_LICENSE",
        "dob": "1990-01-01",
        "expiry": "2022-12-31",
        "firstName": "FIRST NAME",
        "issuingCountry": "AUT",
        "issuingDate": "2013-01-01",
        "lastName": "LAST NAME",
        "number": "123456789",
        "status": "APPROVED_VERIFIED"
    },
    "transaction": {
        "clientIp": "XX.XX.X.XX",
        "customerId": "CUSTOMERID",
        "date": "2019-01-01T11:01:10.227Z",
        "merchantReportingCriteria": "YOURREPORTINGCRITERIA",
        "merchantScanReference": "YOURSCANREFERENCE",
        "source": "WEB_UPLOAD",
        "status": "DONE"
    },
    "verification": {
        "identityVerification": {
            "similarity": "MATCH",
            "validity": "true"
        }
    }, "facemap": {
        "classifier": "facemap",
        "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/facemap"
    }
}
```

## Jumio Platform API Responses

Following are examples of the API response bodies, in JSON format.

### Account Creation Response

The &lt;accountId&gt; value, &lt;workflowExcecutionId&gt; value, authorization tokens, and URLs are obtained from the response to the call to the Accounts API.
`(https://account.<region>.jumio.ai/api/v1/accounts API):`

<details>

<summary>Response</summary>
```
{
  "timestamp": "2022-11-22T23:51:19.152Z",
  "account": {
    "id": "310ede34-41ab-4f2b-ac47-b5c3553edf03"
  },
  "web": {
    "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMMQ7CMAyF4btkxlJibNdhY2TlBq6TsLQUiUogIe5O2huwvvfp_4T6Pq_hFJJITpJkyCnmcAjmfil9V7PI7AieKwKV6JCTITCqobbIqejGd3xshDq4gOQmQC4CI1eCXmCLpQ5ax45frf7D_Vpb14_luc52h3WZb-A2Tbh9ewilUYyskCgyEEqBUajA0ck051adNXx_y3qZiOwAAAA.Hv4xo7lzBstXZLYu6XVFp2TK3quWANfecnftOGXIuX2C5vvLN00PRkS31x5jiI6wfr2o5A65tEl67Ps7WhDE4w&locale=en-US"
  },
  "sdk": {
    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMMQ7CMAyF4btkxlJibNdhY2TlBq6TsLQUiUogIe5O2huwvvfp_4T6Pq_hFJJITpJkyCnmcAjmfil9V7PI7AieKwKV6JCTITCqobbIqejGd3xshDq4gOQmQC4CI1eCXmCLpQ5ax45frf7D_Vpb14_luc52h3WZb-A2Tbh9ewilUYyskCgyEEqBUajA0ck051adNXx_y3qZiOwAAAA.Hv4xo7lzBstXZLYu6XVFp2TK3quWANfecnftOGXIuX2C5vvLN00PRkS31x5jiI6wfr2o5A65tEl67Ps7WhDE4w"
  },
  "workflowExecution": {
    "id": "9541ae91-834e-4914-a30d-6534fed4eb6d",
    "credentials": [
      {
        "id": "f769b899-2752-45d1-83b2-f5e13631d052",
        "category": "ID",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMMQ7CMAyF4btkxlJibNdhY2TlBq6TsLQUiUogIe5O2huwvvfp_4T6Pq_hFJJITpJkyCnmcAjmfil9V7PI7AieKwKV6JCTITCqobbIqejGd3xshDq4gOQmQC4CI1eCXmCLpQ5ax45frf7D_Vpb14_luc52h3WZb-A2Tbh9ewilUYyskCgyEEqBUajA0ck051adNXx_y3qZiOwAAAA.Hv4xo7lzBstXZLYu6XVFp2TK3quWANfecnftOGXIuX2C5vvLN00PRkS31x5jiI6wfr2o5A65tEl67Ps7WhDE4w",
          "parts": {
            "front": "https://api.amer-1.jumio.ai/api/v1/accounts/8aa055c2-c9e2-4d0c-91a2-528a28f051d8/workflow-executions/3f4287c6-69f6-4c66-b5e4-0555a0de78eb/credentials/f769b899-2752-45d1-83b2-f5e13631d052/parts/FRONT",
            "back": "https://api.amer-1.jumio.ai/api/v1/accounts/8aa055c2-c9e2-4d0c-91a2-528a28f051d8/workflow-executions/3f4287c6-69f6-4c66-b5e4-0555a0de78eb/credentials/f769b899-2752-45d1-83b2-f5e13631d052/parts/BACK"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/8aa055c2-c9e2-4d0c-91a2-528a28f051d8/workflow-executions/3f4287c6-69f6-4c66-b5e4-0555a0de78eb"
        }
      },
      {
        "id": "02065ddb-d87d-45b3-9972-967d2c0837f1",
        "category": "FACEMAP",
        "allowedChannels": ["WEB", "SDK"]
      },
      {
        "id": "68179e08-ba1c-4794-a35a-32ea9c16f264",
        "category": "SELFIE",
        "allowedChannels": ["WEB", "API", "SDK"],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMMQ7CMAyF4btkxlJibNdhY2TlBq6TsLQUiUogIe5O2huwvvfp_4T6Pq_hFJJITpJkyCnmcAjmfil9V7PI7AieKwKV6JCTITCqobbIqejGd3xshDq4gOQmQC4CI1eCXmCLpQ5ax45frf7D_Vpb14_luc52h3WZb-A2Tbh9ewilUYyskCgyEEqBUajA0ck051adNXx_y3qZiOwAAAA.Hv4xo7lzBstXZLYu6XVFp2TK3quWANfecnftOGXIuX2C5vvLN00PRkS31x5jiI6wfr2o5A65tEl67Ps7WhDE4w",
          "parts": {
            "face": "https://api.amer-1.jumio.ai/api/v1/accounts/8aa055c2-c9e2-4d0c-91a2-528a28f051d8/workflow-executions/3f4287c6-69f6-4c66-b5e4-0555a0de78eb/credentials/68179e08-ba1c-4794-a35a-32ea9c16f264/parts/FACE"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/8aa055c2-c9e2-4d0c-91a2-528a28f051d8/workflow-executions/3f4287c6-69f6-4c66-b5e4-0555a0de78eb"
        }
      }
    ]
  }
}
```
</details>

### Workflow Details Response

A GET request to the `/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>` API returns a JSON object containing arrays of nested objects for the credentials and the capabilities in the workflow.

<details>
<summary>Response</summary>

```
{
  "workflow": {
    "id": "9541ae91-834e-4914-a30d-6534fed4eb6d",
    "status": "PROCESSED",
    "definitionKey": "10549",
    "userReference": "FBC02D3F-C3B5-4B19-A663-00AE0886A704_1660925181283",
    "customerInternalReference": "test ref"
  },
  "account": {
    "id": "310ede34-41ab-4f2b-ac47-b5c3553edf03"
  },
  "createdAt": "2022-11-07T22:56:00.112Z",
  "startedAt": "2022-11-07T22:57:34.012Z",
  "completedAt": "2022-11-07T22:57:47.892Z",
  "credentials": [
    {
      "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc",
      "category": "SELFIE",
      "parts": [
        {
          "classifier": "FACE",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/7e5ad90a-9277-44d4-a5cb-7797420220fc/parts/FACE"
        }
      ]
    },
    {
      "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac",
      "category": "ID",
      "parts": [
        {
          "classifier": "FRONT",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/b420829c-abe6-4df8-93cb-93f85cd9d5ac/parts/FRONT"
        },
        {
          "classifier": "BACK",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/b420829c-abe6-4df8-93cb-93f85cd9d5ac/parts/BACK"
        }
      ]
    },
    {
      "id": "78974167-956f-4087-b4f1-04782c929e05",
      "category": "FACEMAP",
      "parts": [
        { "classifier": "FACEMAP" },
        {
          "classifier": "LIVENESS_1",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_1"
        },
        {
          "classifier": "LIVENESS_3",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_3"
        },
        {
          "classifier": "LIVENESS_2",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_2"
        },
        {
          "classifier": "LIVENESS_5",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_5"
        },
        {
          "classifier": "LIVENESS_4",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_4"
        },
        {
          "classifier": "LIVENESS_6",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/LIVENESS_6"
        }
      ]
    }
  ],
  "decision": {
    "type": "WARNING",
    "details": { "label": "WARNING" },
    "risk": { "score": 50.0 }
  },
  "steps": {
    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/workflow-executions/9541ae91-834e-4914-a30d-6534fed4eb6d/steps"
  },
  "capabilities": {
    "extraction": [
      {
        "id": "29ddc912-d5dd-4750-85ba-10d969556d32",
        "credentials": [
          { "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac", "category": "ID" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } },
        "data": {
          "type": "DRIVING_LICENSE",
          "subType": "REGULAR_DRIVING_LICENSE",
          "issuingCountry": "USA",
          "firstName": "THOMAS JACOB",
          "lastName": "GOERING",
          "dateOfBirth": "1957-01-18",
          "expiryDate": "2025-01-18",
          "issuingDate": "2019-12-26",
          "documentNumber": "N7624107",
          "state": "CA",
          "gender": "M",
          "currentAge": "65"
        }
      }
    ],
    "similarity": [
      {
        "id": "76a58e7b-b9db-493d-9a8b-a1756e499085",
        "credentials": [
          { "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc", "category": "SELFIE" },
          { "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac", "category": "ID" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "MATCH" } },
        "data": { "similarity": "MATCH" }
      }
    ],
    "liveness": [
      {
        "id": "bfa003f6-c400-4696-973c-7dbdf890006b",
        "validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/310ede34-41ab-4f2b-ac47-b5c3553edf03/credentials/78974167-956f-4087-b4f1-04782c929e05/parts/FACEMAP",
        "credentials": [
          { "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc", "category": "SELFIE" },
          { "id": "78974167-956f-4087-b4f1-04782c929e05", "category": "FACEMAP" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } },
        "data": {
          "type": "JUMIO_STANDARD",
          "predictedAge": 46,
          "ageConfidenceRange": "34-58"
        }
      }
    ],
    "dataChecks": [
      {
        "id": "1d0587eb-aca3-41a7-be70-fbcd08de420c",
        "credentials": [
          { "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac", "category": "ID" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } }
      }
    ],
    "imageChecks": [
      {
        "id": "1110bc6c-708c-444d-b41a-6164d71e3c6f",
        "credentials": [
          { "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc", "category": "SELFIE" },
          { "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac", "category": "ID" }
        ],
        "decision": {
          "type": "WARNING",
          "details": { "label": "REPEATED_FACE" }
        },
        "data": {
          "faceSearchFindings": {
            "status": "DONE",
            "findings": [
              "22771260-8cb0-42a2-a38a-d8f853063cc2",
              "27232651-4b18-4cf1-8d4a-df0451abc717"
            ]
          }
        }
      }
    ],
    "usability": [
      {
        "id": "70ee4aad-fde7-44f9-92f9-97ca77c28f09",
        "credentials": [
          { "id": "b420829c-abe6-4df8-93cb-93f85cd9d5ac", "category": "ID" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } }
      },
      {
        "id": "9fb1876e-6078-4ea5-aba6-d68c200634fb",
        "credentials": [
          { "id": "7e5ad90a-9277-44d4-a5cb-7797420220fc", "category": "SELFIE" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } }
      },
      {
        "id": "810cb95c-a7d0-46fc-bd2a-45b241a669f8",
        "credentials": [
          { "id": "78974167-956f-4087-b4f1-04782c929e05", "category": "FACEMAP" }
        ],
        "decision": { "type": "PASSED", "details": { "label": "OK" } }
      }
    ]
  }
}

```

</details>

---

# ID Verification Web Implementation Guide

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/idVerification/netVerify-web-implementation

# ID Verification Web Implementation Guide

This guide explains how to integrate ID Verification into a web application, configure workflows, display the verification journey, and retrieve results.

## Initiating a ID Verification transaction

Call the RESTful API POST endpoint /initiate with a JSON object containing the properties described below to create a transaction for each user. You will receive a JSON object in the response containing a timestamp, Jumio transaction reference (scan reference), and a URL which you can use to present ID Verification to your user.

HTTP Request Method: POSTREST

- URL (US): https://netverify.com/api/v4/initiateREST
- URL (EU): https://lon.netverify.com/api/v4/initiateREST
- URL (SGP): https://core-sgp.jumio.com/api/v4/initiate

:::note
Jumio Netverify customers are now subject to default rate limits of 3 per second and 180 per minute for initiate requests.
:::

## Authentication and Encryption

ID Verification API calls are protected using [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617). Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under `Settings > API credentials`.

:::warning
Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.
:::

The [TLS Protocol](https://datatracker.ietf.org/doc/html/rfc5246) is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [Supported cipher suites](https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites#supported-tls-cipher-suites).

## Request Headers

The following fields are required in the header section of your request:

```
Accept: application/json
Content-Type: application/jsonContent-Length: see [RFC-7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.2)
Authorization: (see [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)) User-Agent: YourCompany YourApp/v1.0
```

:::note
Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
:::

## Request Body

The body of your initiate API request allows you to

- provide your own internal tracking information for the user and transaction.
- specify what user information is captured and by which method.
- indicate where the user should be directed after the user journey.
- select the language to be displayed.
- preset options to enhance the user journey.

:::info
Values set in your API request will override the corresponding settings configured in the Customer Portal.
:::

Required items appear in bold type.

| Name                           | Type    | Max. Length       | Description                                                                                                                                                                                |
| ------------------------------ | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **customerInternalReference1** | string  | 100               | Your internal reference for the transaction.                                                                                                                                               |
| **userReference1**             | string  | 100               | Your internal reference for the user.                                                                                                                                                      |
| reportingCriteria              | string  | 100               | Your reporting criteria for the transaction.                                                                                                                                               |
| successUrl2                    | string  | 2047              | Redirects to this URL after a successful transaction. Overrides [Success URL](#callback-error-and-success-urls) in the Customer Portal.                                                    |
| errorUrl2                      | string  | 255               | Redirects to this URL after an unsuccessful transaction. Overrides [Error URL](#callback-error-and-success-urls) in the Customer Portal.                                                   |
| callbackUrl2                   | string  | 255               | Sends verification result to this URL upon completion. Overrides [Callback URL](#callback-error-and-success-urls) in the Customer Portal.                                                  |
| workflowId                     | integer | 3                 | Applies this acquisition workflow to the transaction. Overrides [Capture method](#capture-method) in the Customer Portal. See [supported workflowId values](#supported-workflowid-values). |
| presets1                       | JSON    | -                 | Preset options to enhance the user journey. See [supported preset values](#supported-presets-values).                                                                                      |
| locale                         | string  | 5                 | Renders content in the specified language. Overrides [Default locale](#default-locale) in the Customer Portal. See [supported locale values](#supported-locale-values).                    |
| tokenLifetimeInMinutes         | number  | Max. value: 86400 | Time in minutes until the authorization token expires. (minimum: 5, maximum: 86400). Overrides [Authorization token lifetime](#authorization-token-lifetime) in the Customer Portal.       |

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses. 2 See URL constraints for [Callback, Error, and Success URLs](#callback-error-and-success-urls).

## Supported workflowId Values

Acquisition workflows allow you to set a combination of verification and capture method options.

:::info
Identity Verification must be enabled for your account to use an `ID + Identity workflowId`.
:::

| Value | Verification type | Capture method  |
| ----- | ----------------- | --------------- |
| 100   | ID only           | camera + upload |
| 101   | ID only           | camera only     |
| 102   | ID only           | upload only     |
| 200   | ID + Identity     | camera + upload |
| 201   | ID + Identity     | camera only     |
| 202   | ID + Identity     | upload only     |

## Supported presets Values

It is possible to specify presets for **ID Verification, for Identity Verification**, for both together, or for neither. For each preset you use, all values must be passed together as a JSON array (see [Sample request](#sample-request)) for the request to be valid.

### ID Verification presets

**Preset country and document type** - Preset the country and document type to bypass the selection screen.

**_Required items appear in bold type._**

| Name        | Type    | Max. length | Description                                                                                                          |
| ----------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
| **index**   | integer | 1           | must be set to 1                                                                                                     |
| **country** | string  | 3           | Possible values:[ISO 3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) and XKX (Kosovo) |
| **type**    | string  | 15          | Possible values:PASSPORT, DRIVING_LICENSE, ID_CARD                                                                   |

### Identity Verification presets

Identity Verification in ID Verification allows you to make sure the person submitting the ID for verification is the same person in the ID photo. This comprises two steps: the Face Match step and the optional Liveness Check step. The Face Match step allows us to compare the face in the ID photo with the face of the person submitting the transaction for similarity, and the additional Liveness Check ensures that person is present during the transaction.

Identity Verification can be enabled with the Face Match step only or in conjunction with a Liveness Check.

#### Biometric Face Capture

ID Verification's liveness detection technology creates a three-dimensional map of your user's face, providing unprecedented accuracy for the Liveness Check, and creates an enrollment transaction for the use of the Authentication feature.

:::info
To use Biometric Face Capture, Identity Verification and Biometric Face Capture must be enabled for your account by Jumio Support.
:::

Biometric Face Capture requires that the user has access to a camera. In order to ensure that Biometric Face Capture is always used for the Liveness Check, your users must be restricted to using their camera either for the entire transaction, or for the Identity Verification step.

This can be accomplished by:

- changing your Capture method in the Settings area of the [Customer Portal](#configuring-settings-in-the-customer-portal) to Webcam only for the entire transaction.
- including [workflowId 201](#supported-workflowid-values) to specify "ID + Identity, camera only" in the API request when you initate a ID Verification transaction.
- asking Jumio Support to enable Force Camera for Identity to allow upload of the ID image, but force the user to use a camera for the Identity Verification step.

| capture method  | when                  | result                      |
| --------------- | --------------------- | --------------------------- |
| upload only     | always                | user asked to upload selfie |
| camera + upload | user uploads ID image | user asked to upload selfie |
| camera + upload | camera not available  | user asked to upload selfie |
| camera + upload | browser not supported | user asked to upload selfie |
| camera only     | camera not available  | error 9820                  |
| camera only     | browser not supported | error 9820                  |

## Supported locale Values

Hyphenated combination of [ISO 639-1:2002 alpha-2](https://en.wikipedia.org/wiki/ISO_639-1) language code plus [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country (where applicable).

<details>
<summary>Expand the table below</summary>
| Value | Locale |
|-------|--------|
| ar | Arabic |
| bg | Bulgarian |
| cs | Czech |
| da | Danish |
| de | German |
| el | Greek |
| en | American English (default) |
| en-GB | British English |
| es | Spanish |
| es-MX | Mexican Spanish |
| et | Estonian |
| fi | Finnish |
| fr | French |
| he | Hebrew |
| hr | Croatian |
| hu | Hungarian |
| hy | Armenian |
| id | Indonesian |
| it | Italian |
| ja | Japanese |
| ka | Georgian |
| km | Khmer |
| ko | Korean |
| lt | Lithuanian |
| ms |
</details>

## Response

Unsuccessful requests will return the relevant [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6) and information about the cause of the error.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                     | Type   | Max. length | Description                                                       |
| ------------------------ | ------ | ----------- | ----------------------------------------------------------------- |
| **timestamp**            | String | 24          | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
| **transactionReference** | String | 36          | Jumio reference number for the transaction.                       |
| **redirectUrl**          | String |             | URL used to load the ID Verification client.                      |

## Examples

### Sample Request

```
POST https://netverify.com/api/v4/initiate/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
"customerInternalReference" : "transaction_1234",
"userReference" : "user_1234",
"successUrl" : "https://www.yourcompany.com/success",
"errorUrl" : "https://www.yourcompany.com/error",
"callbackUrl" : "https://www.yourcompany.com/callback",
"reportingCriteria" : "myReport1234",
"workflowId" : 200,
"presets" :
	[
		{
			"index"   : 1,
			"country" : "AUT",
			"type"    : "PASSPORT"
		}
	],
"locale" : "en-GB"
}
```

:::warning
Sample requests cannot be run as-is. Replace example data with your own values.
:::

### Sample Response

```
{
  "timestamp": "2018-07-03T08:23:12.494Z",
  "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "redirectUrl": "https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx"
}
```

## Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your ID Verification page. Save changes using your Customer Portal password to activate them.

:::info
Values set in your API request will override the corresponding settings configured in the Customer Portal.
:::

### Application settings — General

#### Callback, Error, and Success URLs

- Define a Callback URL to receive verification results and extracted user data from Jumio when a transaction is completed. For more information, see our [Callback](https://documentation.jumio.ai/docs/Integrate/netVerifyv2/Callbacks-Retrieval-Netverify#netverify-callbacks) documentation.
- Define a Success URL to direct the user after images are accepted for processing. If no Success URL is specified in the Customer Portal or the initiate API request, the Jumio default success page will be displayed, including any custom [images](#images) you have specified.
- Define an Error URL to direct the user when the verification process ends with an error or a failure after 3 submission attempts. If no Error URL is specified in the Customer Portal or the initiate API request, the Jumio default error page will be displayed, including any custom images you have specified.

#### URL requirements:

- HTTPS using the [TLS Protocol](https://datatracker.ietf.org/doc/html/rfc5246) (most recent version recommended)
- Valid [URL](https://datatracker.ietf.org/doc/html/rfc3986) using [ASCII](https://en.wikipedia.org/wiki/ASCII) characters or [IDNA](https://datatracker.ietf.org/doc/html/rfc3492) Punycode

#### URL restrictions:

- IP addresses, ports, certain query parameters and fragment identifiers are not allowed.
- Personally identifiable information (PII) is not allowed in any form.

Jumio appends the following parameters to your Success or Error URL to redirect your user at the conclusion of the user journey. These cannot be used as part of your Success or Error URL:

| Name                       | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| transactionStatus          | SUCCESS for successful submissions. ERROR for errors and failure after 3 attempts. |
| customerInternalReference1 | Your internal reference for the transaction.                                       |
| transactionReference       | Jumio reference number for the transaction.                                        |
| errorCode                  | Displayed when transactionStatus is ERROR.                                         |

1 - Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

#### Capture method

Specify how your user can submit their ID or Identity image for verification.

Choose from:

- Webcam and image upload
- Webcam only
- Image upload only

:::important
Selecting "Webcam only" means some [mobile browsers](#mobile-browsers) will not be supported.
:::

**_Skip "Start ID verification" screen (deprecated)_**
Select this checkbox to bypass the introductory screen in the ID Verification Web client.

#### Authorization token lifetime

Specify the duration of time for which your redirectUrl will remain valid. Enter the value in minutes (minimum 5, maximum 86400). The default value is 30 minutes.

### Application settings — Redirect

#### Domain name prefix

You can optionally define a domain name prefix (https://yourcompany.netverify.com) for the URL of your ID Verification page.

- Allowed characters are letters a-z, numbers 0-9, -
- Must not start or end with -
- Max. 63 characters

#### Default locale

Select a language from the dropdown list to set your display language for ID Verification. If no language is selected, ID Verification will be displayed in English (US).

<details>
<summary> Choose from the table below </summary>

| Language                 |
| ------------------------ |
| Arabic                   |
| Armenian                 |
| Bulgarian                |
| Chinese (China)          |
| Chinese (Hong Kong)      |
| Croatian                 |
| Czech                    |
| Danish                   |
| Dutch                    |
| English                  |
| English (United Kingdom) |
| Estonian                 |
| Finnish                  |
| French                   |
| German                   |
| Georgian                 |
| Greek                    |
| Hebrew                   |
| Hungarian                |
| Indonesian               |
| Italian                  |
| Japanese                 |
| Khmer                    |
| Korean                   |
| Lithuanian               |
| Malay                    |
| Norwegian                |
| Polish                   |
| Portuguese               |
| Portuguese (Brazil)      |
| Romanian                 |
| Russian                  |
| Slovak                   |
| Spanish                  |
| Spanish (Mexico)         |
| Swedish                  |
| Thai                     |
| Turkish                  |
| Vietnamese               |

</details>

### Customize client

#### Colors

Specify primary and secondary colors for each locale to give ID Verification your own look and feel.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

You can also reset all colors to the Jumio default.

#### Images

Add a Header image for each locale to brand your ID Verification page.

Add a Success image and Error image for each locale to be displayed on the Jumio default success and error pages when you do not specify your own Success URL and Error URL.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

All images must be formatted as [JPG](https://jpeg.org/jpeg/) or [PNG](https://en.wikipedia.org/wiki/PNG) and must not exceed 10 MB.

### Displaying ID Verification

The redirectUrl returned in the response to your initate API call, which loads your customized ID Verification page, can be used in several ways:

- within an iFrame on your web page
- as a link on your web page
- as a link shared securely with a user

#### Using ID Verification in an iFrame

If you want to embed ID Verification on a web page, place the iFrame tag in your HTML code where you want the client to appear. Use the redirectUrl as value of the src attribute.

:::warning

- The allow="camera" attribute must be included to enable the camera for image capture in supported browsers.
- In case you are nesting the iFrame in another iFrame the allow="camera" attribute must be added to every iFrame.
- Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
- The containing page where the iFrame is added has to be in a secure context (HTTPS).
  :::

**Note:** Due to security reasons the authorizationToken is automatically removed from the redirectUrl once the client is loaded in the browser and stored in a session instead. It will look like this:

https://yourcompany.netverify.com/web/v4/app?locale=en-GB

#### Width and height

We recommend adhering to the responsive breaking points in the table below.

| Size class | Width    | Height   |
| ---------- | -------- | -------- |
| Large      | ≥ 900 px | ≥ 710 px |
| Medium     | 640 px   | 660 px   |
| Small      | 560 px   | 600 px   |
| X-Small    | ≤ 480 px | ≤ 535 px |

:::note

- When specifying the width and height of your iFrame you may prefer to use percentage values so that the iFrame behaves responsively on your page.
- The ID Verification Web client itself will responsively fill the iFrame that it is loaded into.
  :::

#### Liveness

For a better user experience when creating a three-dimensional map of your user's face, you must allow full screen mode. This will address the positioning and distance between the capture interface and the camera.

:::warning

- The allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen attributes must be included to enable the camera for image capture in supported browsers in full screen mode.
- In case you are nesting the iFrame in another iFrame the allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen attributes must be added to every iFrame.
- Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
- The containing page where the iFrame is added has to be in a secure context (HTTPS).
- Liveness is not possible within an iFrame on incognito mode.
  :::

##### Example HTML

**_Absolute sizing example_**

```
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="930" height="750" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

**_Responsive sizing example_**

```
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

**_Biometric Face Capture example_**

```
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
```

#### Optional iFrame logging

When the ID Verification client is embedded in an iFrame^1, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success event is received). Events include data that allows the containing page to identify which ID Verification transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the ID Verification Web client in this notification is represented as JSON in the data string property of the listener method's event argument. Parsing this JSON string results in an object with the properties described below.

All data is encoded with [UTF-8](https://datatracker.ietf.org/doc/html/rfc3629).

^1 This functionality is not available for instances of ID Verification running in a standalone window or tab.

#### event.data object

**_Required items appear in bold type._**

| Property                       | Type        | Description                                                                                              |
| ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------- |
| **authorizationToken**         | string      | Authorization token, valid for a specified duration.                                                     |
| **transactionReference**       | string      | Jumio reference number for the transaction.                                                              |
| **customerInternalReference1** | string      | Your internal reference for the transaction.                                                             |
| **eventType**                  | integer     | Type of event that has occurred. Possible values: 510 (application state-change)                         |
| **dateTime**                   | string      | UTC timestamp of the event in the browser. Format: YYYY-MM-DDThh:mm:ss.SSSZ                              |
| **payload**                    | JSON object | Information specific to the event generated. (see [event.data.payload object](#eventdatapayload-object)) |

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

#### event.data.payload object

**_Required items appear in bold type._**

| Name      | Type        | Description                                                                                                                                                                                       |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **value** | string      | Possible values: **loaded** (ID Verification loaded in the user's browser.) **success** (Images were accepted for verification.) **error** (Verification could not be completed due to an error.) |
| metainfo  | JSON object | Additional meta-information for error events. (see [metainfo object](#eventdatapayloadmetainfo-object))                                                                                           |

#### event.data.payload.metainfo object

**_Required items appear in bold type._**

| Property | Type    | Description                                                  |
| -------- | ------- | ------------------------------------------------------------ |
| code     | integer | see [errorCode values](#after-the-user-journey)in the table. |

#### Example iFrame logging code

```
function receiveMessage(event) {
	var data = window.JSON.parse(event.data);
	console.log('Netverify Web was loaded in an iframe.');
	console.log('auth token:', data.authorizationToken);
	console.log('transaction reference:', data.transactionReference);
	console.log('customer internal reference:', data.customerInternalReference);
	console.log('event type:', data.eventType);
	console.log('date-time:', data.dateTime);
	console.log('event value:', data.payload.value);
	console.log('event metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);
```

### Using ID Verification in a native WebView

ID Verification Web can be embedded within a WebView in your native mobile application.

See [Native WebView](#native-webview) for information about support on Android and iOS.

#### Android

The following sections explain the steps needed to embed ID Verification Web in a native Android WebView.

Please also refer to the sample code beneath.

##### Permissions and Settings

Make sure that the required permissions are granted.

- android.permission.INTERNET - for remote resources access
- android.permission.CAMERA - for camera capture
- android.permission.READ_EXTERNAL_STORAGE - for upload functionality

The following settings are required for the native WebView for Android.

- Enable [javaScriptEnabled](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setjavascriptenabled) - tells the WebView to enable JavaScript execution
- Allow [allowFileAccess](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setallowfileaccess) - enables file access within WebView
- Allow [allowFileAccessFromFileUrls](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setallowfileaccessfromfileurls) - sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from other file scheme URLs
- Allow [allowUniversalAccessFromFileUrls](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setallowuniversalaccessfromfileurls) - sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin
- Allow [allowContentAccess](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setallowcontentaccess) - enables content URL access within WebView
- Allow [javaScriptCanOpenWindowsAutomatically](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setjavascriptcanopenwindowsautomatically) - tells JavaScript to open windows automatically
- Enable [domStorageEnabled](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setdomstorageenabled) - sets whether the DOM storage API is enabled
- **Do not allow** [mediaPlaybackRequiresUserGesture](https://developer.android.com/reference/kotlin/android/webkit/WebSettings#setmediaplaybackrequiresusergesture) - sets whether the WebView requires a user gesture to play media

##### Embedding required script

To allow Jumio to identify the user runtime environment you will need to interact with the webview window object by embedding a required script. This script sets flag **NVW_WEBVIEW** to true.

##### Optional postMessage communication

You can handle messages from the ID Verification Web Client using the same method as described in [Optional iFrame Logging](#optional-iframe-logging).

You will need to register a postMessage handler and put the relevant code sections in the PostMessageHandler class as in the example mentioned below.

##### Sample code

**_AndroidManifest.xml example_**

```
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.jumio.nvw4">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    ...
</manifest>
```

**_build.gradle example_**

```
dependencies {
    implementation 'androidx.appcompat:appcompat:1.2.0-beta01'
    implementation 'androidx.webkit:webkit:1.2.0'
    ...
}
```

**_WebViewFragment.kt example_**

<details>

<summary> EXPAND WebViewFragment.kt </summary>
```kotlin
class WebviewFragment : Fragment() {

    companion object {
        var TAG: String = "NVW4"
        var PERMISSION_REQUEST_CODE: Int = 1000
        private var mUploadMessage: ValueCallback<Uri?>? = null
        var uploadMessage: ValueCallback<Array<Uri>>? = null
        const val REQUEST_SELECT_FILE = 1002
        private const val FILECHOOSER_RESULTCODE = 1003

        private var _binding: FragmentWebviewBinding? = null
        private val binding get() = _binding!!


        //Inject javascript code here that is executed after the page is loaded
        val injectFunction = """
        function () {
            window['__NVW_WEBVIEW__'] = {
            isAndroid: true
            }
        }
        """.trimIndent()

        private var mFilePathCallback: ValueCallback<Array<Uri>>? = null

        fun newInstance(url: String): WebviewFragment {
            val fragment = WebviewFragment()

            val args = Bundle()
            args.putString("url", url)
            fragment.arguments = args

            return fragment
        }
    }

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        _binding = FragmentWebviewBinding.inflate(inflater, container, false)
        return binding.root
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        WebView.setWebContentsDebuggingEnabled(true)

        binding.webview.settings.javaScriptEnabled = true
        binding.webview.settings.allowFileAccessFromFileURLs = true
        binding.webview.settings.allowFileAccess = true
        binding.webview.settings.allowContentAccess = true
        binding.webview.settings.allowUniversalAccessFromFileURLs = true
        binding.webview.settings.javaScriptCanOpenWindowsAutomatically = true
        binding.webview.settings.mediaPlaybackRequiresUserGesture = false
        binding.webview.settings.domStorageEnabled = true

        binding.webview.addJavascriptInterface(PostMessageHandler(), "__NVW_WEBVIEW_HANDLER__")

        binding.webview.webChromeClient = object : WebChromeClientFullScreen() {

            // Grant permissions for cam
            @TargetApi(Build.VERSION_CODES.M)
            override fun onPermissionRequest(request: PermissionRequest) {
                activity?.runOnUiThread {
                    if ("android.webkit.resource.VIDEO_CAPTURE" == request.resources[0]) {
                        if (ContextCompat.checkSelfPermission(
                                activity!!,
                                Manifest.permission.CAMERA
                            ) == PackageManager.PERMISSION_GRANTED
                        ) {
                            Log.d(
                                TAG,
                                String.format(
                                    "PERMISSION REQUEST %s GRANTED",
                                    request.origin.toString()
                                )
                            )
                            request.grant(request.resources)
                        } else {
                            ActivityCompat.requestPermissions(
                                activity!!,
                                arrayOf(
                                    Manifest.permission.CAMERA,
                                    Manifest.permission.READ_EXTERNAL_STORAGE
                                ),
                                PERMISSION_REQUEST_CODE
                            )
                        }
                    }
                }
            }

            // For Lollipop 5.0+ Devices
            @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
            override fun onShowFileChooser(
                mWebView: WebView?,
                filePathCallback: ValueCallback<Array<Uri>>?,
                fileChooserParams: FileChooserParams
            ): Boolean {
                if (uploadMessage != null) {
                    uploadMessage!!.onReceiveValue(null)
                    uploadMessage = null
                }
                try {
                    uploadMessage = filePathCallback
                    val intent = fileChooserParams.createIntent()
                    intent.type = "image/*"
                    try {
                        startActivityForResult(intent, REQUEST_SELECT_FILE)
                    } catch (e: ActivityNotFoundException) {
                        uploadMessage = null
                        Toast.makeText(
                            activity?.applicationContext,
                            "Cannot Open File Chooser",
                            Toast.LENGTH_LONG
                        ).show()
                        return false
                    }
                    return true
                } catch (e: ActivityNotFoundException) {
                    uploadMessage = null
                    Toast.makeText(
                        activity?.applicationContext,
                        "Cannot Open File Chooser",
                        Toast.LENGTH_LONG
                    ).show()
                    return false
                }
            }

            private fun openFileChooser(uploadMsg: ValueCallback<Uri?>) {
                mUploadMessage = uploadMsg
                val i = Intent(Intent.ACTION_GET_CONTENT)
                i.addCategory(Intent.CATEGORY_OPENABLE)
                i.type = "image/*"
                startActivityForResult(
                    Intent.createChooser(i, "File Chooser"),
                    FILECHOOSER_RESULTCODE
                )
            }

            override fun onConsoleMessage(consoleMessage: ConsoleMessage): Boolean {
                Log.d(TAG, consoleMessage.message())
                return true
            }

            override fun getDefaultVideoPoster(): Bitmap {
                return Bitmap.createBitmap(10, 10, Bitmap.Config.ARGB_8888)
            }
        }

        binding.webview.webViewClient = object : WebViewClient() {

            override fun onReceivedError(
                view: WebView?,
                errorCode: Int,
                description: String?,
                failingUrl: String?
            ) {
                Toast.makeText(activity, description, Toast.LENGTH_SHORT).show()
            }

            override fun onReceivedSslError(
                view: WebView?,
                handler: SslErrorHandler?,
                error: SslError?
            ) {
                handler?.proceed()
            }

            override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
                // Put your javascript function that you want to execute here
                binding.webview.loadUrl("javascript:($injectFunction)()")
            }
        }

        binding.webview.loadUrl(arguments?.get("url") as String)
    }

    override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            if (requestCode == REQUEST_SELECT_FILE) {
                if (uploadMessage == null)
                    return
                uploadMessage!!.onReceiveValue(
                    WebChromeClient.FileChooserParams.parseResult(
                        resultCode,
                        intent
                    )
                )
                uploadMessage = null
            }
        } else if (requestCode == FILECHOOSER_RESULTCODE) {
            if (null == mUploadMessage)
                return
            val result =
                if (intent == null || resultCode != AppCompatActivity.RESULT_OK) null else intent.data
            mUploadMessage!!.onReceiveValue(result)
            mUploadMessage = null
        } else {
            Toast.makeText(
                activity?.applicationContext,
                "Failed to Upload Image",
                Toast.LENGTH_LONG
            ).show()
        }
        super.onActivityResult(requestCode, resultCode, intent)
    }

    class PostMessageHandler {
        @JavascriptInterface
        fun postMessage(json: String?, transferList: String?): Boolean {
            /*
                There we're handling messages from NVW4 client, its the same as for iFrame logging;
                More details can be found here:
                https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
            */
            Log.d(TAG, "postMessage triggered, json: " + json.toString())
            return true
        }
    }

    	/**
    	 * Custom WebChromClient to handle iProov full screen requirement
    	 * More details can be found here:
    	 * https://github.com/iProov/android/wiki/Java-WebView
    	 */
    open inner class WebChromeClientFullScreen : WebChromeClient() {
        private var customView: View? = null
        private var customViewCallback: CustomViewCallback? = null
        private var originalOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
        private var originalVisibility = View.INVISIBLE

        /**
         * Callback will tell the host application that the current page would
         * like to show a custom View in a particular orientation
         */
        override fun onShowCustomView(view: View, callback: CustomViewCallback) {
            //If we have custom view, that means that we are already in full screen, and need to go to original state
            if (customView != null) {
                onHideCustomView()
                return
            }
            //going full screen
            customView = view
            //We need to store there parameters, so we can restore app state, after we exit full screen mode
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                originalVisibility = activity?.window?.decorView?.visibility!!
                (activity?.window?.decorView as FrameLayout).addView(
                    customView,
                    FrameLayout.LayoutParams(-1, -1)
                )
                activity?.window?.setDecorFitsSystemWindows(false)
            } else {
                originalVisibility = activity?.window?.decorView?.windowSystemUiVisibility!!
                (activity?.window?.decorView as FrameLayout).addView(
                    customView,
                    FrameLayout.LayoutParams(-1, -1)
                )
                activity?.window?.decorView?.systemUiVisibility =
                    3846 or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
            }
            originalOrientation = activity?.requestedOrientation!!
        }

        /**
         * Callback will tell the host application that the current page exited full screen mode,
         * and the app has to hide custom view.
         */
        override fun onHideCustomView() {
            (activity?.window?.decorView as FrameLayout).removeView(
                customView
            )
            customView = null
            //Restoring app state, as it was before we go to full screen
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                activity?.window?.setDecorFitsSystemWindows(true)
            } else {
                activity?.window?.decorView?.systemUiVisibility = originalVisibility
            }
            activity?.requestedOrientation = originalOrientation
            if (customViewCallback != null) customViewCallback!!.onCustomViewHidden()
            customViewCallback = null
        }
    }

```

</details>

#### Use of iProov
Please be aware that if iProov is included in your workflow, it is necessary to extend WebChromeClient class to implement a custom view, in order to handle certain iProov full screen requirements.

See WebViewFragment.kt code sample above, specifically WebChromeClientFullScreen inner class.

#### Sample App
Check out our [Sample App](https://github.com/Jumio/mobile-webview/tree/master/android) for the Native Android WebView

##### iOS
Jumio supports two types of webview for iOS, you can choose either of these:

**Safari WebView**

| Pros | Cons |
|------|------|
| Access to the camera during ID and Identity | No optional postMessage communication |
| Fewer integration steps | Fewer options for troubleshooting |

**Native iOS WebView**

| Pros | Cons |
|------|------|
| Optional postMessage communication | Image upload only (no access to the camera) |
| Better options for troubleshooting | More integration steps |

#### Safari WebView
The following sections explain the steps needed to embed ID Verification Web in a Safari View Controller.

Please also refer to the sample code beneath.

##### Permissions and Settings
Make sure that camera permissions are granted.

##### Sample code
ViewController.swift example

```

import AVFoundation
import SafariServices
import UIKit
​
class ViewController: UIViewController {

    @IBAction func loadButton(_ sender: Any) {
        checkCameraPermission()
        let url: String = "https://www.jumio.com/"
        showSafariVC(inputText)
    }

    // present SFSafariViewController
    private func showSafariVC(_ stringURL: String) {
        guard let URL = URL(string: stringURL) else {
            return
        }

​
let safariVC = SFSafariViewController(url: URL)
present(safariVC, animated: true)
}

    func safariViewControllerDidFinish(_ safariVC: SFSafariViewController) {
        safariVC.dismiss(animated: true, completion: nil)
    }

    // ask for camera permissions
    func checkCameraPermission() {
        AVCaptureDevice.requestAccess(for: .video) { (granted) in
            if !granted {
                print("Camera permission denied")
            }
        }
    }

}

```

##### Sample App
Check out our [Sample App](https://github.com/Jumio/mobile-webview/tree/master/ios/SafariViewController-Pilot) for the iOS Safari WebView

#### Native iOS WebView
The following sections explain the steps needed to embed ID Verification Web in a native iOS WebView.

Please also refer to the sample code beneath.

##### Permissions and Settings
No specific permissions are needed as we cannot access the camera due to native WebView limitations for iOS.

##### Embedding required script
To allow Jumio to identify the user runtime environment you will need to interact with the webview window object by embedding a required script. This script sets flag __NVW_WEBVIEW__ to true.

Optional postMessage communication
You can handle messages from the ID Verification Web Client using the same method as described in Optional iFrame Logging.

Please register a postMessage handler and put the relevant code sections in the userContentController function as mentioned below.

**Sample code**
ViewController.swift example

```

class ViewController: UIViewController {
@IBOutlet weak var webView: WKWebView!
​
override func viewDidLoad() {
super.viewDidLoad()
webView.navigationDelegate = self;
​
/**
_ Registering handler for postMessage communication (iFrame logging equivalent - optional)
_/
webView.configuration.userContentController.add(self, name: "**NVW*WEBVIEW_HANDLER**")
​
webView.load( URLRequest("<<NVW4 SCAN REF LINK>>"));
}
}
​
extension ViewController: WKNavigationDelegate {
/**
* Embedding script at very beginning, before NVW4 initialize (important)
_/
func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) {
/\*\*

- Necesssary integration step - embedding script
  \*/
  self.webView?.evaluteJavaScript("(function() { window['__NVW_WEBVIEW__'] = true })()") { _, error in
  if let error = error {
  print("ERROR while evalutaing javascript \(error)") // error handling whenever executing script fails
  }
  print("executed injected javascript")
  };
  }
  }
  ​
  extension ViewController: WKScriptMessageHandler {
  /\*\*
  _ PostMessage handler for iframe logging equivalent (optional)
  _/
  func userContentController(\_ userController: WKUserContentController, didReceive message: WKScriptMessage) {
  if message.name == "**NVW_WEBVIEW_HANDLER**", let messageBody = message.body as? String {
  /\*
  _ See iFrame logging:
  \_ https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
  \*/
  }
  }
  }

```

##### Sample App
Check out our [Sample App](https://github.com/Jumio/mobile-webview/tree/master/ios/WebView-Pilot) for the Native iOS WebView


### After the user journey
At the end of the user journey, the user is directed to your Success URL if the images they submitted were accepted for processing. If no Success URL has been defined, the Jumio default success page will be displayed, including any custom success [image](#images) you have specified in the Customer Portal.

If acceptable images are not provided after three attempts (see [Reject reasons](https://documentation.jumio.ai/docs/Integrate/netVerifyv2/v2TransactionDataMapping/statusMappings#verification-reject-reasons)), the user is directed to your Error URL. If no Error URL has been defined, the Jumio default error page will be displayed, including any custom error image you have specified in the Customer Portal.

To display relevant information on your success or error page, you can use the following parameters which we append when redirecting to your successUrl or errorUrl as HTTP GET query string parameters1. It is also possible to set successUrl and errorUrl to the same address, by using the query parameter transactionStatus.

***Required items appear in bold type.***

| Name | Description |
|------|-------------|
| **transactionStatus** | Possible values: **SUCCESS** for successful submissions. **ERROR** for errors and failure after 3 attempts. |
| **customerInternalReference2** | Your internal reference for the transaction. |
| **transactionReference** | Jumio reference number for the transaction. |
| errorCode | Displayed when transactionStatus is ERROR. Possible values: 9100 (Error occurred on our server.) 9200 (Authorization token missing, invalid, or expired.) 9210 (Session expired after the user journey started.) 9300 (Error occurred transmitting image to our server.) 9400 (Error occurred during verification step.) 9800 (User has no network connection.) 9801 (Unexpected error occurred in the client.) 9810 (Problem while communicating with our server.) 9820 (File upload not enabled and camera unavailable.) 9821 (The Biometric Face Capture face capture process failed, e.g. issue with iProov) 9822 (Browser does not support camera.) 9835 (No acceptable submission in 3 attempts.) |

1 Because HTTP GET parameters can be manipulated on the client side, they may be used for display purposes only. 2 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

#### Sample success redirect
```

https://www.yourcompany.com/success/?transactionStatus=SUCCESS&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

```

#### Sample error redirect
```

https://www.yourcompany.com/error/?transactionStatus=ERROR&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&errorCode=9820

```

### Supported environments
Jumio offers guaranteed support for ID Verification on the following browsers and the latest major version of each operating system.

#### Desktop browsers

| Browser | Major version | Operating system | Supports image upload | Supports camera capture | Supports Biometric Face Capture |
|----------|----------------|------------------|------------------------|--------------------------|----------------------------------|
| Google Chrome | current + 1 previous | Windows + Mac | X | X | X |
| Mozilla Firefox | current + 1 previous | Windows + Mac | X | X | X |
| Apple Safari | current | Mac | X | X | X |
| Microsoft Edge | current | Windows | X | X | X |

#### Mobile browsers
| Browser name | Major browser version | Operating system | Supports image upload | Supports camera capture | Supports Biometric Face Capture |
|--------------|----------------------|------------------|------------------------|--------------------------|----------------------------------|
| Google Chrome | current | Android + iOS | X | X | X |
| Samsung Internet | current | Android | X | X | X |
| Apple Safari | current | iOS | X | X | X1 |

1Fullscreen functionality during capture only supported for iPads. iPhone process works, but fullscreen is limited and capture may be less accurate.

#### Native WebView
| Operating system | Major version | Supports image upload | Supports camera capture | Supports Biometric Face Capture |
|------------------|--------------|------------------------|--------------------------|----------------------------------|
| Native Android WebView | current + 1 previous | X | X | X |
| Native iOS WebView1 | current + 1 previous | X |  |  |
| iOS Safari WebView | current + 1 previous | X | X | X |

1If you are using a native WebView for iOS you will need to enable image upload to allow the end user to finish the user journey.
```

---

# performNetverify Implementation Guide

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/performNetverify

# performNetverify

This is a reference manual and configuration guide for the ID Verification API product. It illustrates how to implement the ID Verification API.

## Using performNetverify

performNetverify offers a Restful ID verification API without Jumio-hosted user interface. Simply send an HTTP POST including the customer's ID image to the URL below. You will immediately receive a JSON response with a Jumio scan reference and a timestamp. A callback will be sent after the verification is complete (see [Callback](https://documentation.jumio.ai/docs/Integrate/netVerifyv2/Callbacks-Retrieval-Netverify)).

:::warning
Passports (MRZ) have the highest success rate among ID types. It is recommended for best conversion rates and better data extraction to suggest that your users upload passports when using this submission channel.
:::

HTTP Request Method:POSTREST

- URL (US): https://netverify.com/api/netverify/v2/performNetverifyREST
- URL (EU): https://lon.netverify.com/api/netverify/v2/performNetverifyREST
- URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/performNetverify

## Authentication and Encryption

ID Verification API calls are protected using [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617). Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.

:::warning
Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.
:::

The [TLS Protocol](https://datatracker.ietf.org/doc/html/rfc5246) is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [Supported cipher suites](https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites#supported-tls-cipher-suites).

## Request Headers

The following fields are required in the header section of your request:

```
Accept: application/json
Content-Type: application/jsonContent-Length: see [RFC-7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.2)
Authorization: (see [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)) User-Agent: YourCompany YourApp/v1.0
```

:::info

- Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
- Calls with missing or suspicious headers, suspicious parameter values, or without HTTP Basic Authentication will result in HTTP status code 403 Forbidden.
  :::

## Request body

:::info
Values set in your API request will override the corresponding settings configured in the Customer Portal.
:::
**_Required fields appear in bold type._**

| Parameter                   | Type   | Max. Length                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **merchantIdScanReference** | String | 100                                                          | Your reference for each scan. Must not contain sensitive data such as PII (Personally Identifiable Information) or account login information.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **frontsideImage**          | String | Max. 15MB, < 8000 pixels per side, longest side > 300 pixels | Base64 encoded image of the front side of the ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **faceImage** \*            | String | Max. 15MB, < 8000 pixels per side, longest side > 300 pixels | Base64 encoded image of the face. _Mandatory if Face Match is enabled._                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **country**                 | String | 3                                                            | Possible values: [ISO 3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code, XKX (Kosovo).                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **idType**                  | String | 255                                                          | PASSPORT, DRIVING_LICENSE, ID_CARD, VISA.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| frontsideImageMimeType      | String |                                                              | MIME type of the front side image. Possible values: image/jpeg (default), image/png.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| faceImageMimeType           | String |                                                              | MIME type of the face image. Possible values: image/jpeg (default), image/png.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| backsideImage               | String | Max. 15MB, < 8000 pixels per side, longest side > 300 pixels | Base64 encoded image of the back side of the ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| backsideImageMimeType       | String |                                                              | MIME type of the back side image. Possible values: image/jpeg (default), image/png.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| enabledFields               | String | 100                                                          | Defines which fields will be extracted during ID verification. Fields not listed here will not be processed for this transaction, regardless of Customer Portal settings. Face Match and Address extraction will not be processed unless enabled for your account. To enable them, contact your Customer Success Manager or Jumio Support. See [supported documents for address extraction](#supported-documents-for-address-extraction). Possible values: "idNumber,idFirstName,idLastName,idDob,idExpiry,idUsState,idPersonalNumber,idFaceMatch,idAddress". |
| merchantReportingCriteria   | String | 100                                                          | Your reporting criteria for each scan.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **customerId** \*           | String | 100                                                          | Identification of the customer. Must not contain sensitive data such as PII or account login information. _Mandatory if using Jumio Screening._                                                                                                                                                                                                                                                                                                                                                                                                               |
| callbackUrl                 | String | 255                                                          | Callback URL for confirmation after verification is completed (see [Callback URL](#callback-url) for constraints).                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| firstName                   | String | 100                                                          | First name of the customer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| lastName                    | String | 100                                                          | Last name of the customer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| usState                     | String | 100                                                          | If idType = PASSPORT or ID_CARD: Last two characters of [ISO 3166-2 US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code, [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country name, Kosovo, [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, XK (Kosovo), [ISO 3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3), XKX (Kosovo). If idType = DRIVING_LICENSE: Last two characters of [ISO 3166-2 US state](https://en.wikipedia.org/wiki/ISO_3166-2:US) code.               |
| expiry                      | String |                                                              | Expiry date in the format YYYY-MM-DD.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| number                      | String | 100                                                          | Identification number of the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| dob                         | String |                                                              | Date of birth in the format YYYY-MM-DD.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| callbackGranularity         | String | 255                                                          | Possible values: onFinish (default) – Callback sent after entire verification; onAllSteps – Additional callback sent when images are received.                                                                                                                                                                                                                                                                                                                                                                                                                |
| personalNumber              | String | 14                                                           | Personal number of the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **userConsent** \*          | Object |                                                              | User consent required where a product uses facial recognition technology or processes biometric data. See [userConsent](#request-userconsent). _Mandatory for End-User Consent even if the user is not based in the USA._                                                                                                                                                                                                                                                                                                                                     |

## Request userConsent

| Parameter                  | Type   | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **userIp\***               | String | —           | Current IP address of the end-user used during the verification.**Mandatory for [End-User Consent](#end-user-consent-for-biometric-data-in-api)**, even if the user is not based in the USA.                                                                                                                                                                                                                                                                           |
| **userLocation\***         | Object | —           | Contains:• `userLocation.country`• `userLocation.state`**Mandatory for End-User Consent**, even if the user is not based in the USA.                                                                                                                                                                                                                                                                                                                                   |
| **userLocation.country\*** | String | 3           | Current country based on end-user location during verification.Possible values:• [ISO 3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)**Mandatory for End-User Consent**, even if the user is not based in the USA.                                                                                                                                                                                                                      |
| userLocation.state         | String | 100         | Current state based on end-user location during verification.Applicable only in countries where state exists, including the USA.Possible values:• For [USA](https://www.iso.org/obp/ui/#iso:code:3166:US), [CAN](https://www.iso.org/obp/ui/#iso:code:3166:CA), [AUS](https://www.iso.org/obp/ui/#iso:code:3166:AU) → alpha-2 state code only (without country & hyphen), e.g., IL (Illinois), NSW (New South Wales)• For other countries → any string (if applicable) |
| **consent\***              | Object | —           | Contains:• `consent.obtained`• `consent.obtainedAt`**Mandatory for End-User Consent**, and required if `userLocation.country = USA` and `consent.obtained = yes`.                                                                                                                                                                                                                                                                                                      |
| **consent.obtained\***     | String | —           | Indicates whether end-user consent was obtained.Possible values:• `yes` – Consent was given• `no` – Consent was not given• `na` – Not applicable**Mandatory for End-User Consent**, and required if country = USA.                                                                                                                                                                                                                                                     |
| **consent.obtainedAt\***   | String | —           | Timestamp when consent was obtained (UTC).Format: `YYYY-MM-DDThh:mm:ss.SSSZ`**Mandatory for End-User Consent**, and required if `consent.obtained = yes`.                                                                                                                                                                                                                                                                                                              |

## Supported documents for address extraction

| Country        | ID Card | Driving License | Passport | Callback Format |
| -------------- | ------- | --------------- | -------- | --------------- |
| Australia      | No      | Yes             | No       | RAW             |
| Bahrain        | No      | Yes             | No       | RAW             |
| Canada         | No      | Yes             | No       | RAW             |
| France         | Yes     | Yes             | Yes      | RAW             |
| Germany        | Yes     | No              | No       | RAW             |
| Indonesia      | Yes     | No              | No       | RAW             |
| Ireland        | No      | Yes             | No       | RAW             |
| Malaysia       | Yes     | No              | No       | RAW             |
| Malta          | Yes     | Yes             | No       | RAW             |
| Mexico         | Yes     | No              | No       | RAW             |
| Peru           | Yes     | Yes             | No       | RAW             |
| Romania        | Yes     | No              | No       | RAW             |
| Singapore      | Yes     | No              | No       | RAW             |
| Spain          | Yes     | No              | No       | RAW             |
| United Kingdom | No      | Yes             | No       | RAW             |
| United States  | Yes     | Yes             | No       | RAW             |

## End-User Consent for Biometric Data in API

To collect consent on Jumio’s behalf, you will need to incorporate certain explicit consent collection language and a link to [Jumio’s Privacy Notice](https://www.jumio.com/privacy-center/privacy-notices/online-services-notice/) within your user consent flow before collection of end-user biometric data, if the end-user is located inside the United States.

The following is an example of how consent may be presented to the end-user, but you may use your own custom language as long as the required elements are present:

“By clicking “Start” you consent to Jumio collecting, processing, and sharing your personal information, which may include biometric data, pursuant to its Privacy Notice.”

### When to share consent parameters?

Every transaction which includes any product/workflow step in which biometrics are collected needs to have consent parameters adapted and populated. This means if Face match is enabled for your account you will need to share consent parameters for performNetverify.

If consent is not provided or other scenarios where consent needs to be resubmitted use our Account Update API to add the needed consent parameters.

If your Privacy Policy and Terms & Conditions allowing continuous use of consent obtained from end-user on biometric data collection and processing the timestamp (consent.obtainedAt) should be when the original/updated consent was obtained.

:::warning
If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt) has to be updated accordingly.
:::

:::note
Until further notice Jumio will not perform any treatment based on the consent parameters. After a notice period business validation will be performed, which could also lead to a rejection of the transaction also providing additional consent specific error codes. We will inform you separately on a specific date.
:::

### Where to share consent parameters?

Within the consent area in the API request body.

- Always mandatory: Populate the end-user IP address and end-user current location (userConsent.userIp,userLocation.country)
- Mandatory if userLocation.country = USA: Populate the consent parameters (i.e., status, timestamp)
  See examples for a [sample request](#sample-request) including the user consent parameters.

## Response

| Parameter            | Type   | Max Length | Description                                                        |
| -------------------- | ------ | ---------- | ------------------------------------------------------------------ |
| timestamp            | String | —          | Timestamp (UTC) of the response.Format: `YYYY-MM-DDThh:mm:ss.SSSZ` |
| jumioIdScanReference | String | 36         | Jumio's reference number for each scan.                            |

## Examples

### Sample request

**_Including End-User Consent (USA)_**

```
POST https://netverify.com/api/netverify/v2/performNetverify HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "merchantIdScanReference": "YOURSCANREFERENCE",
  "frontsideImage": "YOURBASE64STRING",
  "country": "XKX",
  "idType": "PASSPORT",
  "customerId":"customerId",
  "userConsent": {
      "userIp": "226.80.211.232",
      "userLocation": {
          "country": "USA",
          "state": "IL"
      },
       "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-07-20T17:20:35.000Z"

      }
  }
}
```

**_Including End-User Consent (AUT)_**

```
POST https://netverify.com/api/netverify/v2/performNetverify HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "merchantIdScanReference": "YOURSCANREFERENCE",
  "frontsideImage": "YOURBASE64STRING",
  "country": "XKX",
  "idType": "PASSPORT",
  "customerId":"customerId",
  "userConsent": {
      "userIp": "192.168.0.1",
      "userLocation": {
          "country": "AUT"
      }
  }
}
```

:::warning
Sample requests cannot be run as-is. Replace example data with your own parameter values.
:::

### Sample Response

```
{
  "timestamp": "2017-08-16T10:37:44.623Z",
  "jumioIdScanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your ID Verification page. Save changes using your Customer Portal password to activate them.

**Values set in your API request will override the corresponding settings configured in the Customer Portal.**

### Application settings — General

#### Callback URL

Define a Callback URL to receive verification results and extracted user data from Jumio when a transaction is completed. For more information, see our Callback documentation.

##### URL requirements

- HTTPS using the [TLS Protocol](https://datatracker.ietf.org/doc/html/rfc5246) (most recent version recommended)
- Valid [URL](https://datatracker.ietf.org/doc/html/rfc3986) using [ASCII](https://en.wikipedia.org/wiki/ASCII) characters or [IDNA](https://datatracker.ietf.org/doc/html/rfc3492) Punycode

##### URL restrictions

- IP addresses, ports, query parameters and fragment identifiers are not allowed.
- Personally identifiable information (PII) is not allowed in any form.

---

# ID Verification Retrieval API Implementation Guide

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/idVerification/retrievalAPIImplementation

# ID Verification Retrieval API Implementation Guide

This guide describes how to implement the ID Verification Retrieval API.

## Usage

The Retrieval API is an alternative way to retrieve the results of a Jumio transaction for customers who choose not to implement our callback functionality, or in cases where a callback could not be received or processed.

Please contact Jumio Support at support@jumio.com to coordinate bulk requests to the Retrieval API.

## Best Practice

- You must use the status retrieval for all requests until the transaction is no longer in PENDING status.
- If the transaction status is DONE or FAILED (not pending), retrieve details and image(s) once.
- Maximum of 10 consecutive retrieval attempts after successful image acquisition (SDK/Web: User journey finshed; API: after ID Verification API call)
- If a final result is not available after 10 attempts, you are allowed to perform an additional retrieval call once per day.
- Request timings recommendation:
  40, 60, 100, 160, 240, 340, 460, 600, 760, 940 seconds
  You are also allowed to set your own definition.

## Authentication and encryption

ID Verification API calls are protected using [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617). Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password.

You can view and manage your API token and secret in the Customer Portal under Settings > API credentials. You can create a separate set of API credentials to be used specifically with the Retrieval and Delete API in the Customer Portal under Settings > API credentials > Transaction administration APIs.

:::warning
Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.
:::

The [TLS Protocol](https://datatracker.ietf.org/doc/html/rfc5246) is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see [Supported cipher suites](https://documentation.jumio.ai/docs/developer-resources/API/integration-prerequisites#supported-tls-cipher-suites).

## Request Headers

The following fields are required in the header section of your request:

`Accept: application/jsonorimage/jpeg, image/png when retrieving a specific image Authorization: (see [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)) User-Agent: YourCompany YourApp/v1.0`

:::info
Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
:::

:::warning
Sample requests cannot be run as-is. Replace example data with your own values.
:::

## ID Verification retrieval

### Retrieving status

Call the RESTful API GET endpoint below to retrieve the status of a ID Verification transaction by specifying the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>`

:::info
Jumio Netverify customers are now subject to default rate limits of 45 per second and 2700 per minute for retrieval requests.
:::

### Response

Unsuccessful requests will return the relevant [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6) and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**\*\***Required items appear in bold type.**\*\***

| Name              | Type   | Max. length | Description                                                        |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------ |
| **timestamp**     | string |             | Timestamp of the response in the format `YYYY-MM-DDThh:mm:ss.SSSZ` |
| **scanReference** | string | 36          | Jumio’s reference number for the transaction                       |
| **status**        | string |             | Possible states: PENDING, DONE, FAILED                             |

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

:::warning
Sample requests cannot be run as-is. Replace example data with your own values.
:::

Sample response

```
{
    "timestamp": "2019-01-01T16:23:55.039Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "DONE"
}
```

### Retrieving details

Call the RESTful API GET endpoint below to retrieve document, transaction, and verification details by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/dataREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/dataREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name              | Type   | Max. length | Description                                                                                   |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------- |
| **timestamp**     | string |             | Timestamp of the response in the format `YYYY-MM-DDThh:mm:ss.SSSZ`                            |
| **scanReference** | string | 36          | Jumio’s reference number for the transaction                                                  |
| **document**      | object |             | As listed in the section _Retrieving document data_ (without timestamp and scanReference)     |
| **transaction**   | object |             | As listed in the section _Retrieving transaction data_ (without timestamp and scanReference)  |
| verification      | object |             | As listed in the section _Retrieving verification data_ (without timestamp and scanReference) |
| facemap           | object |             | facemap (if download of facemap is enabled), see table below                                  |

#### Parameter facemap

**_Required items appear in bold type._**

| Name           | Type   | Max. Length | Description                                   |
| -------------- | ------ | ----------- | --------------------------------------------- |
| **classifier** | string | 5           | Possible value: facemap                       |
| **href**       | string | 5           | REST URL used to retrieve the facemap content |

**Retrieving facemap**
Call the RESTful API GET endpoint to retrieve a raw facemap which will be returned in a binary format.

Use HTTP GET with Basic Authorization using your API token and secret, as userid and password.
Header: The following parameters are mandatory in the header section of your request.

- User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION
  The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.
  The TLS protocol is required during the TLS handshake (see [Supported cipher suites]) and we strongly recommend using the latest version.

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, does not contain a valid facemap or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing requested the information.

### Examples

#### Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

:::warning
Sample requests cannot be run as-is. Replace example data with your own values.
:::

#### Sample response

```
{
    "timestamp": "2019-03-20T16:25:38.663Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "document": {
        "type": "DRIVING_LICENSE",
        "dob": "1990-01-01",
        "expiry": "2022-12-31",
        "firstName": "FIRST NAME",
        "issuingCountry": "AUT",
        "issuingDate": "2013-01-01",
        "lastName": "LAST NAME",
        "number": "123456789",
        "status": "APPROVED_VERIFIED"
    },
    "transaction": {
        "clientIp": "XX.XX.X.XX",
        "customerId": "CUSTOMERID",
        "date": "2019-01-01T11:01:10.227Z",
        "merchantReportingCriteria": "YOURREPORTINGCRITERIA",
        "merchantScanReference": "YOURSCANREFERENCE",
        "source": "WEB_UPLOAD",
        "status": "DONE"
    },
    "verification": {
        "identityVerification": {
            "similarity": "MATCH",
            "validity": "true"
        },
        "mrzCheck": "NOT_AVAILABLE"
    },
        "facemap": {
        "classifier": "facemap",
        "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/facemap"
    }
}
```

### Retrieving document data only

Call the RESTful API GET endpoint below to retrieve document data by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/documentREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/documentREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/document`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                         | Type   | Max. length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| timestamp                    | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                                                                                                                                                                                                                                                                                                      |
| scanReference                | string | 36          | Jumio’s reference number for the transaction                                                                                                                                                                                                                                                                                                                                                                                                                          |
| status                       | string |             | ID Verification: APPROVED_VERIFIED, DENIED_FRAUD, DENIED_UNSUPPORTED_ID_TYPE, DENIED_UNSUPPORTED_ID_COUNTRY, ERROR_NOT_READABLE_ID, NO_ID_UPLOADED                                                                                                                                                                                                                                                                                                                    |
| type                         | string |             | ID Verification: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED                                                                                                                                                                                                                                                                                                                                                                                                |
| idSubtype                    | string | 255         | Possible subtypes if type = ID_CARD: NATIONAL_ID, CONSULAR_ID, ELECTORAL_ID, RESIDENT_PERMIT_ID, TAX_ID, STUDENT_ID, PASSPORT_CARD_ID, MILITARY_ID, PUBLIC_SAFETY_ID, HEALTH_ID, OTHER_ID, VISA, UNKNOWN. Possible subtypes if idType = DRIVING_LICENSE: REGULAR_DRIVING_LICENSE, LEARNING_DRIVING_LICENSE. Possible subtypes if idType = PASSPORT: E_PASSPORT (only for mobile)                                                                                      |
| issuingCountry               | string | 3           | Possible countries: [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code - XKX (Kosovo)                                                                                                                                                                                                                                                                                                                                                |
| firstName                    | string | 255         | Customer's first name                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| lastName                     | string | 255         | Customer's last name                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| middleName                   | string | 255         | Customer's middle name. For document types that have a separate, dedicated middle name.                                                                                                                                                                                                                                                                                                                                                                               |
| dob                          | string |             | Date of birth in the format YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                                |
| expiry                       | string |             | Date of expiry in the format YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                               |
| issuingDate                  | string | 10          | Issue date in the format YYYY-MM-DD (if issuing date extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                           |
| number                       | string | 255         | Identification number of the document                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| usState                      | string | 255         | Possible values: Last two characters of [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code; Last 2-3 characters of [ISO 3166-2:AU](https://en.wikipedia.org/wiki/ISO_3166-2:AU) state code; Last two characters of [ISO 3166-2:CA](https://en.wikipedia.org/wiki/ISO_3166-2:CA) state code; [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country name; XKX (Kosovo); Free text - if it can't be mapped to a state/country code |
| personalNumber               | string | 255         | Personal number of the document                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| optionalData1                | string | 255         | Optional field of MRZ line 1                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| optionalData2                | string | 255         | Optional field of MRZ line 2                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| address                      | object |             | Address in RAW format, see table below                                                                                                                                                                                                                                                                                                                                                                                                                                |
| issuingAuthority             | string | 50          | Issuing authority of the document (if issuing authority extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                        |
| issuingPlace                 | string | 50          | Issuing place of the document (if issuing place extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                |
| curp                         | string | 18          | CURP (if CURP extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| gender                       | string | 1           | Possible values: M, F                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| nationality                  | string | 3           | Nationality of the document holder in [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code (if extraction is enabled)                                                                                                                                                                                                                                                                                                                  |
| placeOfBirth                 | string | 255         | Place of birth of document holder                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| taxNumber                    | string | 255         | Tax number of the document if idCountry = ITA and idType = HEALTH_ID or TAX_ID (if Tax number extraction is enabled). Also known as fiscalNumber in Italy.                                                                                                                                                                                                                                                                                                            |
| cpf                          | string | 255         | CPF number of the document (if CPF number extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                      |
| registrationNumber           | string | 255         | Registration number of the document (if Registration number extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                    |
| mothersName                  | string | 255         | Name of the document holder's mother (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                       |
| fathersName                  | string | 255         | Name of the document holder's father (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                       |
| personalIdentificationNumber | string | 255         | National personal identification number of the document (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                    |
| rgNumber                     | string | 255         | "General Registration" number of Brazilian documents (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                       |
| voterIdNumber                | string | 255         | "Clave de elector" number for idCountry = MEX (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                              |
| issuingNumber                | string | 255         | "Numero de emission" number for idCountry = MEX (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                            |
| expiryDateParts              | object |             | Object containing the expiry date information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`                                                                                                                                                                                                                                                                                                 |
| dobDateParts                 | object |             | Object containing the date of birth information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`                                                                                                                                                                                                                                                                                               |
| issuingDateParts             | object |             | Object containing the issuing date information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`                                                                                                                                                                                                                                                                                                |
| laborIdentificationNumber    | string |             | CUIL number of the document (if CUIL number extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                    |
| documentCopy                 | string |             | Ejemplar number of the document (if Ejemplar number extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                            |
| residentPermitType           | string |             | Permit type related to "Golden Visas" if idCountry = GBR (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                   |
| residentPermitRemarks        | string |             | Permit type related to "Golden Visas" if idCountry = GBR (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                   |
| documentIdentificationNumber | string |             | Document Identification Number (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                             |
| citizenship                  | string |             | Citizenship if idCountry = IDN (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                             |
| maritalStatus                | string |             | Marital Status if idCountry = IDN (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                          |
| religion                     | string |             | Religion if idCountry = IDN, MYS (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                           |
| lastNameAtBirth              | string |             | Last name at birth if idCountry = SLO (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                                      |
| remarks                      | string |             | Special remarks/titles if idCountry = SLO Example: Mgr (if extraction is enabled)                                                                                                                                                                                                                                                                                                                                                                                     |
| disability                   | string |             | Check if there is at least one disability icon available on the back side if idCountry = BHR. Possible values: YES, NO (if extraction is enabled)                                                                                                                                                                                                                                                                                                                     |

1 If one of the values such as "day" is not included in the document it will also not be returned in the object. For examples and additional details, refer to our Knowledge Base.

#### RAW address format

| Name             | Type   | Max. Length | Description                                                       |
| ---------------- | ------ | ----------- | ----------------------------------------------------------------- |
| line1            | string | 255         | Line item1                                                        |
| line2            | string | 255         | Line item2                                                        |
| line3            | string | 255         | Line item3                                                        |
| line4            | string | 255         | Line item4                                                        |
| line5            | string | 255         | Line item5                                                        |
| country          | string | 3           | Possible countries: ISO 3166-1 alpha-3 country code, XKX (Kosovo) |
| postalCode       | string | 255         | Postal code                                                       |
| city             | string | 255         | City                                                              |
| formattedAddress | string |             | Complete address in a formatted way                               |

:::note
On 2020-08-15 we removed old address formats (EU, US). Retrieving document data for transactions older than 2020-08-15 which were initially returned in EU or US format will be now returned in RAW format.
:::

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response

```
{
    "type": "DRIVING_LICENSE",
    "dob": "1990-01-01",
    "expiry": "2022-12-31",
    "firstName": "FIRST NAME",
    "issuingCountry": "AUT",
    "gender": "M",
    "issuingDate": "2013-01-01",
    "lastName": "LAST NAME",
    "nationality": "BHR",
    "personalNumber": "12345679",
    "number": "123456789",
    "status": "APPROVED_VERIFIED",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:44:56.741Z"
}
```

### Retrieving transaction data only

Call the RESTful API GET endpoint below to retrieve transaction metadata by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/transactionREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/transactionREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/transaction`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                      | Type   | Max. length | Description                                                                                                                                                                          |
| ------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **timestamp**             | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                     |
| **scanReference**         | string | 36          | Jumio’s reference number for the transaction                                                                                                                                         |
| **status**                | string |             | Possible states: PENDING, DONE, FAILED                                                                                                                                               |
| **source**                | string |             | ID Verification Web embedded: WEB, WEB-CAM, WEB-UPLOAD. ID Verification Web redirect: REDIRECT, REDIRECT-CAM, REDIRECT-UPLOAD. ID Verification API: API. ID Verification Mobile: SDK |
| **date**                  | string |             | Timestamp of the scan creation in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                |
| clientIp                  | string |             | IP address of the client in the format xxx.xxx.xxx.xxx                                                                                                                               |
| customerId                | string | 255         | Your internal reference for the user.                                                                                                                                                |
| merchantScanReference     | string | 255         | Your internal reference for each transaction                                                                                                                                         |
| merchantReportingCriteria | string | 255         | Your internal reporting criteria for each transaction                                                                                                                                |

#### Examples

**Sample request**

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
**Sample response**

```
{
    "clientIp": "xxx.xxx.xxx.xxx",
    "customerId": "CUSTOMERID",
    "date": "2019-02-01T11:01:10.227Z",
    "merchantReportingCriteria": "YOURMERCHANTREPORTINGCRITERIA",
    "merchantScanReference": "YOURSCANREFERENCE",
    "source": "WEB_UPLOAD",
    "status": "DONE",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:46:57.127Z"
}
```

### Retrieving verification data only

Call the RESTful API GET endpoint below to retrieve verification data by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/verificationREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/verificationREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/verification`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                 | Type   | Max. length | Description                                                      |
| -------------------- | ------ | ----------- | ---------------------------------------------------------------- |
| **timestamp**        | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ |
| **scanReference**    | string | 36          | Jumio’s reference number for the transaction                     |
| mrzCheck             | string |             | Possible values: OK, NOT_AVAILABLE                               |
| rejectReason         | object |             | Reject reason, see tables below                                  |
| identityVerification | object |             | Identity verification, see table below                           |
| additionalChecks     | object |             | Additional checks, see table below                               |

#### Parameter rejectReason

| Name                    | Type                     | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rejectReasonCode        | string                   | 5           | see below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| rejectReasonDescription | string                   | 255         | Possible codes and descriptions for verification status **DENIED_FRAUD**: <ul><li>100 MANIPULATED_DOCUMENT</li><li>105 FRAUDSTER</li><li>106 FAKE</li><li>107 PHOTO_MISMATCH</li><li>108 MRZ_CHECK_FAILED</li><li>109 PUNCHED_DOCUMENT</li><li>110 CHIP_DATA_MANIPULATED (only available for ePassport)</li><li>111 MISMATCH_PRINTED_BARCODE_DATA</li><li>112 CHIP_MISSING</li><li>113 MISMATCHING_DATA_REPEATED_FACE1</li><li>114 DIGITAL_MANIPULATION</li><li>115 MISMATCH_HRZ_MRZ_DATA</li><li>118 MISMATCH_FRONT_BACK</li></ul> Possible codes and descriptions for verificationStatus = **ERROR_NOT_READABLE_ID**: <ul><li>102 PHOTOCOPY_BLACK_WHITE</li><li>103 PHOTOCOPY_COLOR</li><li>104 DIGITAL_COPY</li><li>200 NOT_READABLE_DOCUMENT</li><li>201 NO_DOCUMENT</li><li>202 SAMPLE_DOCUMENT</li><li>206 MISSING_BACK</li><li>207 WRONG_DOCUMENT_PAGE</li><li>209 MISSING_SIGNATURE</li><li>210 CAMERA_BLACK_WHITE</li><li>211 DIFFERENT_PERSONS_SHOWN</li><li>213 INVALID_WATERMARK</li><li>214 MISSING_FRONT</li><li>300 MANUAL_REJECTION</li></ul> |
| rejectReasonDetails     | JSON object / JSON array |             | Reject reason details as JSON object (if only one item is returned) or JSON array (containing JSON objects) if rejectReasonCode = 100 or 200, see table below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

1activation required

#### Parameter rejectReasonDetails

| Name               | Type   | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detailsCode        | string | 5           | see below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| detailsDescription | string | 255         | Possible codes and description details for rejectReasonCode = 100: <ul><li>1001 PHOTO</li><li>1002 DOCUMENT_NUMBER</li><li>1003 EXPIRY</li><li>1004 DOB</li><li>1005 NAME</li><li>1006 ADDRESS</li><li>1007 SECURITY_CHECKS</li><li>1008 SIGNATURE</li><li>1009 PERSONAL_NUMBER</li><li>1011 PLACE_OF_BIRTH</li></ul> Possible codes and description details for rejectReasonCode = 200: <ul><li>2001 BLURRED</li><li>2002 BAD_QUALITY</li><li>2003 MISSING_PART_DOCUMENT</li><li>2004 HIDDEN_PART_DOCUMENT</li><li>2005 DAMAGED_DOCUMENT</li><li>2006 GLARE</li><li>2007 MISSING_MANDATORY_DATAPOINTS</li></ul> |

#### Parameter identityVerification

| Name       | Description                                                                                                                                                                                                                                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| similarity | Possible values: <ul><li>MATCH</li><li>NO_MATCH</li><li>NOT_POSSIBLE</li></ul>                                                                                                                                                                                                                                                                                             |
| validity   | Possible values: <ul><li>TRUE</li><li>FALSE</li></ul>                                                                                                                                                                                                                                                                                                                      |
| reason     | Provided if validity = FALSE. Possible values: <ul><li>SELFIE_CROPPED_FROM_ID</li><li>ENTIRE_ID_USED_AS_SELFIE</li><li>MULTIPLE_PEOPLE</li><li>SELFIE_IS_SCREEN_PAPER_VIDEO</li><li>SELFIE_MANIPULATED</li><li>AGE_DIFFERENCE_TOO_BIG</li><li>NO_FACE_PRESENT</li><li>FACE_NOT_FULLY_VISIBLE</li><li>BAD_QUALITY</li><li>BLACK_AND_WHITE</li><li>LIVENESS_FAILED</li></ul> |

#### Parameter additionalChecks

| Name                     | Type | Description                                                                                          | Notes               |
| ------------------------ | ---- | ---------------------------------------------------------------------------------------------------- | ------------------- |
| addressValidation        | JSON | Result of Address Validation see table below                                                         | activation required |
| proofOfResidency         | JSON | Result of Proof of Residency check if idCountry = AUS, BRA, CAN, DEU, ESP, GBR, MEX, see table below | activation required |
| watchlistScreening       | JSON | Result of Jumio Screening (see ID Verification & ComplyAdvantage Screening Implementation Guide)     | activation required |
| faceSearchFindings       | JSON | Result of 1:n face search on previous transactions see table below                                   | activation required |
| personalNumberValidation | JSON | Result of validation for CPF number see table below                                                  | activation required |

#### Parameter addressValidation

| Name           | Type | Description                                                                                                                                                                                            |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| searchResults  | enum | If verificationStatus = APPROVED_VERIFIED possible values: <ul><li>POSITIVE_RESULT</li><li>PARTIAL_RESULT</li><li>NEGATIVE_RESULT</li></ul> else <ul><li>CHECK_NOT_DONE (see searchResponse)</li></ul> |
| searchResponse | enum | Possible values: <ul><li>UNSUPPORTED_COUNTRY</li><li>NOT_ENOUGH_DATA</li><li>TECHNICAL_ERROR</li></ul>                                                                                                 |

#### Parameter proofOfResidency

| Name           | Type | Description                                                                                                                                                                                            |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| searchResults  | enum | If verificationStatus = APPROVED_VERIFIED possible values: <ul><li>POSITIVE_RESULT</li><li>PARTIAL_RESULT</li><li>NEGATIVE_RESULT</li></ul> else <ul><li>CHECK_NOT_DONE (see searchResponse)</li></ul> |
| searchResponse | enum | Possible values: <ul><li>UNSUPPORTED_COUNTRY</li><li>NOT_ENOUGH_DATA</li><li>TECHNICAL_ERROR</li></ul>                                                                                                 |

#### Parameter faceSearchFindings

| Name     | Type              | Description                                                                                                                                                                                                                                                                                                 |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status   | enum              | Possible values: <ul><li>DONE</li><li>PENDING</li><li>ERROR</li></ul>                                                                                                                                                                                                                                       |
| findings | String/JSON array | A face (on the ID or Selfie) is matching with another face (on the ID or Selfie) from a previous transaction. Possible values: <ul><li>No findings: parameter not returned</li><li>Single finding: String of the transaction reference</li><li>Multiple findings: Array of transaction references</li></ul> |

See [1:n Best Practice](https://support.jumio.com/hc/en-us/articles/1260803713790) for further details.

#### Parameter personalNumberValidation

| Name          | Type | Description                                                                                                                                                                   |
| ------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| searchResults | enum | If verificationStatus = APPROVED_VERIFIED possible values: <ul><li>POSITIVE_RESULT</li><li>NEGATIVE_RESULT</li></ul> else <ul><li>CHECK_NOT_DONE (see searchReason)</li></ul> |
| searchReason  | enum | Possible values: <ul><li>NOT_ENOUGH_DATA</li><li>TECHNICAL_ERROR</li></ul>                                                                                                    |

### Examples

**Sample request**

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/verification HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
**Sample response**
Approved verified

```
{
    "additionalChecks": {
        "addressValidation": {
            "searchResults": "POSITIVE_RESULT"
        }
        "proofOfResidency": {
            "searchResults": "PARTIAL_RESULT"
        }
        "faceSearchFindings": {
            "status": "DONE",
            "findings": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
        }
        "personalNumberValidation": {
          "searchResults": "POSITIVE_RESULT"
        }
    },
    "identityVerification": {
        "similarity": "MATCH",
        "validity": "true"
    },
    "mrzCheck": "OK",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:48:31.331Z"
}
```

**Error (not readable ID)**

```
{
    "mrzCheck": "OK",
    "rejectReason": {
        "rejectReasonCode": "201",
        "rejectReasonDescription": "NO_DOCUMENT"
    },
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:51:39.876Z"
}
```

### Retrieving available images

Call the RESTful API GET endpoint below to retrieve a list of the available images for a transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/imagesREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/imagesREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name              | Type              | Max. length | Description                                                      |
| ----------------- | ----------------- | ----------- | ---------------------------------------------------------------- |
| **timestamp**     | string            |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ |
| **scanReference** | string            | 36          | Jumio’s reference number for the transaction                     |
| images            | JSON array/object |             | See table below                                                  |
| livenessImages    | JSON array        |             | List of REST URLs to retrieve specific liveness images           |

#### Parameter images

**_Required items appear in bold type._**

| Name           | Type   | Description                                                                   |
| -------------- | ------ | ----------------------------------------------------------------------------- |
| **classifier** | string | ID Verification: <ul><li>front</li><li>face</li><li>back</li></ul>            |
| **href**       | string | REST URL to retrieve specific image (see Retrieving a specific image section) |

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response

```
{
    "timestamp": "2019-03-01T11:53:52.878Z",
    "images": [
        {
            "classifier": "back",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/back"
        },
        {
            "classifier": "front",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/front"
        },
        {
            "classifier": "face",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face"
        }
    ],
        "livenessImages": [
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/7",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/5",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/6",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/3",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/4",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/2"
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

### Retrieving a specific image

Call the RESTful GET API endpoint below to retrieve a specific image from a transaction by specifying the image classifier and the Jumio transaction reference (scan reference) of an existing transaction from your account as path parameters.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/images/<classifier>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/images/<classifier>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images/<classifier>`

Request path parameters
**_Required items appear in bold type._**

| Name              | Type   | Max. length | Description                                                        |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------ |
| **scanReference** | string | 36          | Jumio’s reference number for the transaction                       |
| **classifier**    | string |             | ID Verification: <ul><li>front</li><li>face</li><li>back</li></ul> |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, has been deleted, or does not contain the image you requested.

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/front HTTP/1.1
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
```

### Retrieving liveness images

Call the RESTful API GET endpoint below to retrieve liveness images from a transaction by specifying the liveness number and the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>`

#### Request path parameters

**_Required items appear in bold type._**

| Name               | Type    | Max. length | Description                                  |
| ------------------ | ------- | ----------- | -------------------------------------------- |
| **scanReference**  | string  | 36          | Jumio’s reference number for the transaction |
| **livenessNumber** | integer |             | Number of image from the liveness sequence   |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1 HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

### Authentication retrieval

#### Retrieving details

Call the RESTful API GET endpoint below to retrieve the details of an Authentication transaction by specifying the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                               | Type              | Max. length | Description                                                                                                              |
| ---------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| **transactionReference**           | string            | 36          | Jumio’s reference number for the Authentication transaction                                                              |
| **enrollmentTransactionReference** | string            | 36          | Jumio’s reference number of the enrollment transaction (ID)                                                              |
| **transactionResult**              | string            |             | Possible values: <ul><li>CREATED</li><li>STARTED</li><li>PASSED</li><li>FAILED</li><li>INVALID</li><li>EXPIRED</li></ul> |
| **transactionDate**                | string            |             | Timestamp of the transaction in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                      |
| **scanSource**                     | string            |             | Possible value: <ul><li>SDK</li><li>WEB</li></ul>                                                                        |
| userReference                      | string            |             | Your internal reference for the user                                                                                     |
| images                             | JSON array/object |             | See table below                                                                                                          |
| livenessImages                     | JSON array        |             | List of REST URLs to retrieve specific liveness images                                                                   |

##### Parameter images

**_Required items appear in bold type._**

| Name       | Type   | Description                                                           |
| ---------- | ------ | --------------------------------------------------------------------- |
| classifier | string | Possible value: <ul><li>face</li></ul>                                |
| href       | string | REST URL to retrieve specific image (see Retrieving a specific image) |

### Examples

**Sample request**

```
GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
**Sample response**

```
{
    "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "enrollmentTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "transactionResult": "PASSED",
    "scanSource": "SDK",
    "transactionDate": "2019-05-23T14:32:27.534",
    "images": [
        {
            "classifier": "face",
            "href": "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face"
        }
    ],
    "livenessImages": [
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/2",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/3",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/4",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/5",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/6",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/7"
    ]
}
```

### Retrieving a specific image

Call the RESTful API GET endpoint below to retrieve the face image from an Authentication transaction by specifying the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>`

#### Request path parameters

**_Required items appear in bold type._**

| Name                 | Type   | Max. length | Description                                                 |
| -------------------- | ------ | ----------- | ----------------------------------------------------------- |
| transactionReference | string | 36          | Jumio’s reference number for the Authentication transaction |
| classifier           | string |             | Possible value: <ul><li>face</li></ul>                      |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

#### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

### Retrieving liveness images

Call the RESTful API GET endpoint below to retrieve liveness images from an Authentication transaction by specifying the liveness number and the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>`

#### Request path parameters

**_Required items appear in bold type._**

| Name                 | Type    | Max. length | Description                                                 |
| -------------------- | ------- | ----------- | ----------------------------------------------------------- |
| transactionReference | string  | 36          | Jumio’s reference number for the Authentication transaction |
| livenessNumber       | integer |             | Number of image from the liveness sequence                  |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

### Examples

Sample request

```
GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1 HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

### Document Verification retrieval

#### Retrieving status

Call the RESTful API GET endpoint below to retrieve the status of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>REST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name          | Type   | Max. length | Description                                                      |
| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
| timestamp     | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ |
| scanReference | string | 36          | Jumio’s reference number for the transaction                     |
| status        | string |             | Possible states: <ul><li>DONE</li><li>FAILED</li></ul>           |

### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:52:48.864Z",
    "status": "DONE"
}
```

#### Retrieving details

Call the RESTful API GET endpoint below to retrieve the document and transaction details of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/dataREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/dataREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name              | Type   | Max. length | Description                                                                                                       |
| ----------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **timestamp**     | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                  |
| **scanReference** | string | 36          | Jumio’s reference number for the transaction                                                                      |
| document          | object |             | Same parameters as listed in the section Retrieving document data only but without timestamp and scanReference    |
| transaction       | object |             | Same parameters as listed in the section Retrieving transaction data only but without timestamp and scanReference |

#### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response
Credit card (CC)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:42:31.858Z",
    "document": {
        "status": "EXTRACTED",
        "type": "CC",
        "extractedData": {
            "firstName": "FULL NAME",
            "signatureAvailable": false,
            "extractedData": "{\"expiryDate\":\"01/22\",\"firstName\":\"FULL NAME\",\"pan\":\"XXXXXXXXXXXX1234\"
            }"
        },
        "country": "AUT"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}
```

Social Security card (SSC)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:40:49.124Z",
    "document": {
        "status": "EXTRACTED",
        "type": "SSC",
        "extractedData": {
            "firstName": "FIRST NAME",
            "lastName": "LAST NAME",
            "ssn": "123-45-6789",
            "signatureAvailable": false,
            "extractedData": "{\"lastName\":\"LAST NAME\",\"firstName\":\"FIRST NAME\",\"signaturePresent\":\"true\",\"ssn\":\"123-45-6789\"
            }"
        },
        "country": "USA"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}
```

Bank statement (BS)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:32:22.606Z",
    "document": {
        "status": "EXTRACTED",
        "type": "BS",
        "extractedData": {
            "firstName": "FULL NAME",
            "signatureAvailable": false,
            "extractedData": "{\"city\":\"CITY\",\"addressFormat\":\"RAW\",\"postalCode\":\"12345\",\"accountNumber\":\"123456789\",\"subdivision\":\"XX\",\"firstName\":\"FULL NAME\",\"issueDate\":\"2019-01-01\",\"line1\":\"12345 EASY STREET\"}"
        },
        "country": "USA",
        "originalDocument": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/original"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}
```

### Retrieving document data only

Call the RESTful API GET endpoint below to retrieve the document data of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/documentREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/documentREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/document`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name               | Type   | Max. length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **timestamp**      | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **scanReference**  | string | 36          | Jumio’s reference number for the transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **status**         | string |             | Possible states: <ul><li>UPLOADED (default)</li><li>EXTRACTED if the document provided is supported for data extraction</li><li>DISCARDED if the document provided is not supported for data extraction</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| type               | string |             | Possible types: <ul><li>CC (Credit card, front and back side)</li><li>BS (Bank statement, front side)</li><li>IC (Insurance card, front side)</li><li>UB (Utility bill, front side)</li><li>CAAP (Cash advance application, front and back side)</li><li>CRC (Corporate resolution certificate, front and back side)</li><li>CCS (Credit card statement, front and back side)</li><li>LAG (Lease agreement, front and back side)</li><li>LOAP (Loan application, front and back side)</li><li>MOAP (Mortgage application, front and back side)</li><li>TR (Tax return, front and back side)</li><li>VT (Vehicle title, front side)</li><li>VC (Voided check, front side)</li><li>STUC (Student card, front side)</li><li>HCC (Health care card, front side)</li><li>CB (Council bill, front side)</li><li>SENC (Seniors card, front side)</li><li>MEDC (Medicare card, front side)</li><li>BC (Birth certificate, front side)</li><li>WWCC (Working with children check, front side)</li><li>SS (Superannuation statement, front side)</li><li>TAC (Trade association card, front side)</li><li>SEL (School enrolment letter, front side)</li><li>PB (Phone bill, front side)</li><li>SSC (Social security card, front side)</li><li>CUSTOM (Custom document type)</li><li>OTHER (Other document type)</li></ul> |
| country            | string | 3           | Possible countries: <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| originalDocument   | string | 255         | URL to retrieve the original document (PDF), if available                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| customDocumentCode | string | 100         | Your custom document code (configured in the Customer Portal) if type = CUSTOM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extractedData      | object |             | Extracted data when the document provided is supported for data extraction, see table below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

#### extractedData object

| Name               | Type    | Max. Length | Description                                                                                 |
| ------------------ | ------- | ----------- | ------------------------------------------------------------------------------------------- |
| signatureAvailable | Boolean |             | true if signature available, otherwise false                                                |
| ssn                | string  | 255         | Social security number (if readable)                                                        |
| firstName          | string  | 255         | First name if readable for SSC type, full name if readable for all other types              |
| lastName           | string  | 255         | Last name if readable (SSC type only).                                                      |
| extractedData      | object  |             | Extracted data when the document provided is supported for data extraction, see table below |

#### Nested extractedData object

| Name             | Type   | Max. Length | Description                                                                                             |
| ---------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------- |
| addressFormat    | string | 255         | RAW                                                                                                     |
| line1            | string | 100         | Address line 1                                                                                          |
| line2            | string | 100         | Address line 2                                                                                          |
| countryCode      | string | 3           | Possible countries of residence: <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul> |
| postalCode       | string | 15          | Postal code                                                                                             |
| city             | string | 64          | City                                                                                                    |
| subdivision      | string | 50          | Name of subdivision (US state is returned in this field)                                                |
| firstName        | string | 255         | First name if readable for SSC type, full name if readable for all other types                          |
| lastName         | string | 255         | Last name if readable (SSC type only)                                                                   |
| ssn              | string | 255         | Social security number if readable (SSC type only)                                                      |
| signaturePresent | string | 255         | "true" if signature is present, otherwise "false"                                                       |
| accountNumber    | string |             | IBAN or account number                                                                                  |
| swiftCode        | string | 20          | BIC/SWIFT code                                                                                          |
| issueDate        | string |             | Issue date in the format YYYY-MM-DD                                                                     |
| expiryDate       | string |             | Date of expiry in the format MM/YY (CC type only)                                                       |
| pan              | string | 20          | Personal account number of credit card (CC type only)                                                   |

### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

Sample response

Credit card (CC)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:02:43.691Z",
    "status": "EXTRACTED",
    "type": "CC",
    "extractedData": {
        "firstName": "FULL NAME",
        "signatureAvailable": false,
        "extractedData": "{\"expiryDate\":\"01/22\",\"firstName\":\"FULL NAME\",\"pan\":\"XXXXXXXXXXXX1234\"}"
    },
    "country": "AUT"
}
```

Social Security card (SSC)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:05:21.904Z",
    "status": "EXTRACTED",
    "type": "SSC",
    "extractedData": {
        "firstName": "FIRST NAME",
        "lastName": "LAST NAME",
        "ssn": "123-45-6789",
        "signatureAvailable": false,
        "extractedData": "{\"lastName\":\"LAST NAME\",\"firstName\":\"FIRST NAME\",\"signaturePresent\":\"true\",\"ssn\":\"123-45-6789\"}"
    },
    "country": "USA"
}
```

Bank statement (BS)

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:07:25.098Z",
    "status": "EXTRACTED",
    "type": "BS",
    "extractedData": {
        "firstName": "FULL NAME",
        "signatureAvailable": false,
        "extractedData": "{\"city\":\"CITY\",\"addressFormat\":\"RAW\",\"postalCode\":\"12345\",\"accountNumber\":\"123456789\",\"subdivision\":\"XX\",\"firstName\":\"FULL NAME\",\"issueDate\":\"2019-01-01\",\"line1\":\"12345 EASY STREET\"}"
    },
    "country": "USA",
    "originalDocument": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/original"
}
```

### Retrieving transaction data only

Call the RESTful API GET endpoint below to retrieve the transaction metadata of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/transactionREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/transactionREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/transaction`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name                      | Type   | Max. length | Description                                                      |
| ------------------------- | ------ | ----------- | ---------------------------------------------------------------- |
| **timestamp**             | string |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ |
| **scanReference**         | string | 36          | Jumio’s reference number for each transaction                    |
| **status**                | string |             | Possible states: <ul><li>DONE</li><li>FAILED</li></ul>           |
| **source**                | string |             | Possible status: <ul><li>DOC_API</li><li>DOC_UPLOAD</li></ul>    |
| merchantReportingCriteria | string | 255         | Your internal reporting criteria for each transaction            |
| merchantScanReference     | string | 255         | Your internal reference for each transaction                     |
| customerId                | string | 255         | Your internal reference for the user.                            |

### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response

```
{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T16:02:25.646Z",
    "status": "DONE",
    "merchantScanReference": "YOURSCANREFERENCE",
    "customerId": "CUSTOMERID",
    "source": "DOC_UPLOAD"
}
```

### Retrieving available images

Call the RESTful API GET endpoint below to retrieve a list of the available images for a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pagesREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/pagesREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/pages`

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

**_Required items appear in bold type._**

| Name              | Type              | Max. length | Description                                                      |
| ----------------- | ----------------- | ----------- | ---------------------------------------------------------------- |
| **timestamp**     | string            |             | Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ |
| **scanReference** | string            | 36          | Jumio’s reference number for the transaction                     |
| images            | JSON array/object |             | See table below                                                  |

#### Parameter images

**_Required items appear in bold type._**

| Name           | Type    | Description                                                                   |
| -------------- | ------- | ----------------------------------------------------------------------------- |
| **classifier** | integer | Page number specifed when uploading the image                                 |
| **href**       | string  | REST URL to retrieve specific image (see Retrieving a specific image section) |

### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.
Sample response
Bank statement (BS)

```
{
    "timestamp": "2019-01-01T16:04:07.751Z",
    "images": [
        {
            "classifier": 1,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/1"
        }
        {
            "classifier": 2,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/2"
        }
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

Credit card (CC)

```
{
    "timestamp": "2019-01-01T16:10:42.368Z",
    "images": [
        {
            "classifier": 101,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/101"
        }
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

### Retrieving a specific image

Call the RESTful HTTP GET API below to receive a specific image from a Document Verification transaction by specifying the Jumio scan reference as a path parameter.

To retrieve an unmasked credit card image, append the query parameter maskhint=unmasked. By default, retrieval of unmasked credit card images is disabled, and will return HTTP status code 403 Forbidden. If you want to enable it please contact Jumio Support. Retrieving unmasked credit card images might impose additional security requirements on your systems depending on whether you already store/transmit/process credit card data on your systems.

If you are unsure about the PCI DSS ramifications of retrieving unmasked credit card images, please refer to Information Supplement: PCI DSS E-commerce Guidelines, version 2.0, January 2013, and/or contact your acquirer or a PCI DSS QSA (Qualified Security Assessor).

`HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>REST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>`

Request path parameters
**_Required items appear in bold type._**

| Name          | Type   | Max. Length | Description                                                           |
| ------------- | ------ | ----------- | --------------------------------------------------------------------- |
| scanReference | string | 36          | Jumio’s reference number for the transaction                          |
| page_number   | string | 36          | Page number specified when uploading the image                        |
| maskhint      | string |             | For credit cards: <ul><li>masked (default)</li><li>unmasked</li></ul> |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, has been deleted, or does not contain the image you requested.

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

### Examples

Sample request

```
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/1 HTTP/1.1
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

---

# ID Verification Delete API Implementation Guide

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/idVerification/deleteAPIImplementation

This guide illustrates how to implement the ID Verification Delete API.

## Usage

If you do not wish to store sensitive customer data after a verification has been completed, you can delete the image(s) and any extracted data in a transaction record either directly in the Customer Portal or via the Delete API.

⚠️ Deletion is immediate and irreversible. Jumio cannot perform any quality or technical support investigations on transactions that have been deleted.
If you are upgrading to the Jumio Platform and have migrated Netverify transaction data to the Platform, deleting through this API will also delete the migrated data.
Authentication and encryption
ID Verification API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.

You can generate a separate set of API credentials in the Customer Portal to use when retrieving or deleting transaction data under Settings > API credentials > Transaction administration APIs.

⚠️ Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.
The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported cipher suites.

### Request headers

The following fields are required in the header section of your request:

`Accept: application/jsonAuthorization: (see RFC 7617) User-Agent: YourCompany YourApp/v1.0`

:::info
Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
:::

### Delete API for ID Verification

Use the HTTP DELETE method to call the RESTful API endpoint below. Specify the ID Verification transaction reference you want to delete as a path parameter.

`HTTP Request Method:DELETEREST URL (US): https://netverify.com/api/netverify/v2/scans/<transactionReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<transactionReference>REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<transactionReference>`

#### Request body

Required items appear in bold type.

| Name                     | Type   | Max. Length | Description                                                                         |
| ------------------------ | ------ | ----------- | ----------------------------------------------------------------------------------- |
| **transactionReference** | String | 36          | Jumio reference number for an existing ID Verification transaction in your account. |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction record.

### Example

Sample ID Verification delete request

```
DELETE https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

### Delete API for Authentication

Use the HTTP DELETE method to call the RESTful API endpoint below. Specify the Authentication transaction reference you want to delete as a path parameter.

`HTTP Request Method:DELETEREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>`

#### Request body

**_Required items appear in bold type._**

| Name                     | Type   | Max. Length | Description                                                                        |
| ------------------------ | ------ | ----------- | ---------------------------------------------------------------------------------- |
| **transactionReference** | String | 36          | Jumio reference number for an existing Authentication transaction in your account. |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted PII data, images and facemap from the specified authentication transaction record.

### Example

Sample Authentication delete request

```
DELETE https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

### Delete API for Document Verification

Use the HTTP DELETE method to call the RESTful API endpoint below. Specify the Document Verification transaction reference you want to delete as a path parameter.

`HTTP Request Method:DELETEREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<transactionReference>REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<transactionReference>REST URL (SGP): https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<transactionReference>`

#### Request body

Required items appear in bold type.

| Name                     | Type   | Max. Length | Description                                                                               |
| ------------------------ | ------ | ----------- | ----------------------------------------------------------------------------------------- |
| **transactionReference** | String | 36          | Jumio reference number for an existing Document Verification transaction in your account. |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction record.

### Example

Sample Document Verification delete request

```
DELETE https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

---

# Netverify Callback

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/idVerification/callbackIDVerification

# Netverify Callback

The callback is the authoritative answer from Jumio. Specify a callback URL (for constraints see Configuring Settings in the Customer Portal) to automatically receive the result for each transaction.

## Usage

Once Jumio has sent the callback, save it on your side and send us a response of `200 OK`.

Any validation of the content should be done afterwards. In case you face any issues, please contact Jumio Technical Support at support@jumio.com with a sample.

---

## Jumio Callback IP List

Whitelist these IP addresses for callbacks and use them to verify that the callback originated from Jumio.

### US Data Center

34.202.241.227  
34.226.103.119  
34.226.254.127  
52.52.51.178  
52.53.95.123  
54.67.101.173

Use the hostname: `callback.jumio.com` to look up the most current IP addresses.

### EU Data Center

34.253.41.236  
35.157.27.193  
52.48.0.25  
52.57.194.92  
52.58.113.86  
52.209.180.134

Use the hostname: `callback.lon.jumio.com`

### SGP Data Center

3.0.109.121  
52.76.184.73  
52.77.102.92

Use the hostname: `callback.core-sgp.jumio.com`

---

## Callback for ID Verification

An HTTP `POST` request is sent to your specified callback URL containing an `application/x-www-form-urlencoded` formatted string with the transaction result.

To specify a global callback URL in the Customer Portal, see Configuring Settings in the Customer Portal.

A callback URL can also be specified per transaction. See instructions for ID Verification Web v4, performNetverify, and our SDK for Android and iOS.

For Android/iOS: ID verification must be enabled to receive the callback.

### Parameters

Required items appear in **bold** type.

#### ID Verification Web

| User Journey State                      | Transaction State | Callback                                                                                                                                             |
| --------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not started                             | Pending => Failed | Transaction will be cleaned-up from pending to failed after the authorization token lifetime expires. Callback: Verification status `NO_ID_UPLOADED` |
| Drop off during first attempt           | Pending => Failed | Transaction will be finished 15 minutes after the last update. Callback: Verification status `NO_ID_UPLOADED`                                        |
| Drop off during second or third attempt | Done              | Transaction will be finished 15 minutes after the last update. Callback: Verification status `ERROR_NOT_READABLE_ID` with previous reject reason     |
| Finished                                | Done              | Callback: Verification status depends on the result                                                                                                  |

#### ID Verification Mobile (Android/iOS)

| User Journey State | Transaction State | Callback                                                                                                                               |
| ------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Drop off           | Pending => Failed | Transaction will be cleaned-up from pending to failed 15 minutes after the last update. Callback: Verification status `NO_ID_UPLOADED` |
| Finished           | Done              | ID verification will be performed. Callback: Verification status depends on the result (see table below)                               |

#### Parameters

The following parameters are posted to your callback URL for ID Verification Web, ID Verification API and ID Verification Mobile iOS/Android.

**_Required items appear in bold type._**

| Parameter                 | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Notes                                                                  |
| ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| callBackType              |             | NETVERIFYID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                        |
| jumioIdScanReference      | 36          | Jumio’s reference number for each transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                        |
| verificationStatus        |             | <ul><li>APPROVED_VERIFIED</li><li>DENIED_FRAUD</li><li>DENIED_UNSUPPORTED_ID_TYPE</li><li>DENIED_UNSUPPORTED_ID_COUNTRY</li><li>ERROR_NOT_READABLE_ID</li><li>NO_ID_UPLOADED</li></ul>                                                                                                                                                                                                                                                                                                                                       |                                                                        |
| idScanStatus              |             | SUCCESS if verificationStatus = APPROVED_VERIFIED, otherwise ERROR                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                                        |
| idScanSource              |             | <ul><li>WEB (NVW4 before capture method is selected)</li><li>WEB_CAM (NVW4 with camera capture)</li><li>WEB_UPLOAD (NVW4 with file upload)</li><li>API (performNetverify)</li><li>SDK (mobile)</li></ul>                                                                                                                                                                                                                                                                                                                     |                                                                        |
| idCheckDataPositions      |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idCheckDocumentValidation |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idCheckHologram           |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idCheckMRZcode            |             | OK for passports and supported ID cards if verificationStatus = APPROVED_VERIFIED and MRZ check is enabled otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                     | not returned for DEU, HKG, JPN, NLD, SGP, KOR if NV masking is enabled |
| idCheckMicroprint         |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idCheckSecurityFeatures   |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idCheckSignature          |             | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| transactionDate           |             | Timestamp (UTC) of the transaction creation format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                        |
| callbackDate              |             | Timestamp (UTC) of the callback creation format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                                        |
| identityVerification      |             | Identity verification as JSON object, ONLY if verificationStatus = APPROVED_VERIFIED                                                                                                                                                                                                                                                                                                                                                                                                                                         | activation required                                                    |
| idType                    |             | <ul><li>PASSPORT</li><li>DRIVING_LICENSE</li><li>ID_CARD</li><li>VISA</li></ul> Currently, Jumio only supports US and China visas in certain cases. Visas from other countries will be rejected as unsupported with idType = VISA                                                                                                                                                                                                                                                                                            |                                                                        |
| idSubtype                 | 255         | Possible subtypes if idType = ID_CARD:<ul><li>NATIONAL_ID</li><li>CONSULAR_ID</li><li>ELECTORAL_ID</li><li>RESIDENT_PERMIT_ID</li><li>TAX_ID</li><li>STUDENT_ID</li><li>PASSPORT_CARD_ID</li><li>MILITARY_ID</li><li>PUBLIC_SAFETY_ID</li><li>HEALTH_ID</li><li>OTHER_ID</li><li>VISA</li><li>UNKNOWN</li></ul>Possible subtypes if idType = DRIVING_LICENSE:<ul><li>REGULAR_DRIVING_LICENSE</li><li>LEARNING_DRIVING_LICENSE</li></ul>Possible subtypes if idType = PASSPORT:<ul><li>E_PASSPORT (only for mobile)</li></ul> |                                                                        |
| idCountry                 | 3           | <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                        |
| rejectReason              |             | Reject reason as JSON object if verificationStatus = DENIED_FRAUD or ERROR_NOT_READABLE_ID                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idScanImage               | 255         | URL to retrieve the image of the transaction (JPEG or PNG) if available                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                                        |
| idScanImageFace           | 255         | URL to retrieve the face image of the transaction (JPEG or PNG) if available                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                        |
| idScanImageBackside       | 255         | URL to retrieve the back side image of the transaction (JPEG or PNG) if available                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                                        |
| idNumber                  | 200         | Identification number of the document as available on the ID if enabled, otherwise if provided                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                        |
| idFirstName               | 200         | First name of the customer as available on the ID if enabled, otherwise if provided                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                                                        |
| idLastName                | 200         | Last name of the customer as available on the ID if enabled, otherwise if provided                                                                                                                                                                                                                                                                                                                                                                                                                                           | activation required for Chinese name extraction                        |
| idDob                     | 10          | Date of birth in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                        |
| idExpiry                  | 10          | Date of expiry in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                        |
| idUsState                 | 255         | See ISO 3166-2 codes or free text if not mapped                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                        |
| personalNumber            | 14          | Personal number of the document if idType = PASSPORT and if data available on the document                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                        |
| idAddress                 |             | Address as JSON object in RAW format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | activation required                                                    |
| merchantIdScanReference   | 100         | Your reference for each transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                                                        |
| merchantReportingCriteria | 100         | Your reporting criteria for each transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                        |
| customerId                | 100         | ID of the customer as provided                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                        |
| clientIp                  |             | IP address of the client in the format xxx.xxx.xxx.xxx                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                        |
| firstAttemptDate          |             | Timestamp (UTC) of the first transaction attempt format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                                                                                                                                                                                                                                                                                                                                                            |                                                                        |
| optionalData1             | 255         | Optional field of MRZ line 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                        |
| optionalData2             | 255         | Optional field of MRZ line 2                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                        |
| gender                    | 2           | <ul><li>M</li><li>F</li><li>X</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | activation required                                                    |
| presetCountry             | 3           | <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                        |
| presetIdType              |             | <ul><li>PASSPORT</li><li>DRIVING_LICENSE</li><li>ID_CARD</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                                        |
| dlCarPermission           | 255         | <ul><li>YES</li><li>NO</li><li>NOT_READABLE</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | activation required                                                    |
| nationality               | 3           | ISO 3166-1 alpha-3 country code (if MRZ contains nationality)                                                                                                                                                                                                                                                                                                                                                                                                                                                                | activation required                                                    |
| passportNumber            | 255         | Passport number if idType = VISA and additional extraction enabled                                                                                                                                                                                                                                                                                                                                                                                                                                                           | activation required                                                    |
| issuingAuthority          | 50          | Issuing authority of the document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | activation required                                                    |
| issuingDate               | 10          | Issuing date of the document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | activation required                                                    |
| issuingPlace              | 50          | Issuing place of the document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | activation required                                                    |
| livenessImages            |             | URLs to the liveness images of the transaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                        |
| facemap                   | 255         | URL to the facemap of the transaction if available                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | activation required                                                    |
| taxNumber                 | 255         | Tax number of the document. Also known as fiscalNumber in Italy.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | activation required                                                    |
| cpf                       | 255         | CPF number of the document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | activation required                                                    |
| registrationNumber        | 255         | Registration number of the document                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | activation required                                                    |
| mothersName               | 255         | Name of the document holder's mother                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | activation required                                                    |
| fathersName               | 255         | Name of the document holder's father                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | activation required                                                    |
| rgNumber                  | 255         | "General Registration" number for idCountry = BRA                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | activation required                                                    |
| voterIdNumber             | 255         | "Clave de elector" number for idCountry = MEX                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | activation required                                                    |
| issuingNumber             | 255         | "Numero de emission" number for idCountry = MEX                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | activation required                                                    |
| residentPermitType        |             | Permit type related to "Golden Visas" if idCountry = GBR                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | activation required                                                    |
| residentPermitRemarks     |             | Permit type related to "Golden Visas" if idCountry = GBR                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | activation required                                                    |
| disability                |             | <ul><li>YES</li><li>NO</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | activation required                                                    |

1 Transaction is declined as unsupported if the ID is not supported by Jumio, or not marked as accepted in your customer portal settings. 2 For ID types that are configured to support a separate scan of the front side and back side, there is a separate image of the front side (idScanImage) and the back side (idScanImageBackside). If Identity Verification is enabled, there is also a picture of the face (idScanImageFace). 3 Address recognition is performed for supported IDs, if enabled. Please check Supported documents for Address Extraction to see which supported documents. The address parameters are a part of the JSON object, if they are available on the ID. 4 Fields containing certain kinds of personally identifying information are not returned if NV masking is enabled for the Netherlands, Germany, or South Korea. See ID Verification masking for more information. 5 Liveness images are returned only for transactions containing Identity Verification submitted via the Android and iOS SDKs. The number of images can vary and may not be returned in chronological order. 6 If one of the values such as "day" is not included in the document it will also not be returned in the object.

#### Retrieving images

Use HTTP GET with Basic Authorization using your API token and secret as userid and password. Header: The following parameters are mandatory in the header section of your request.

- Accept: image/jpeg, image/png
- User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.

The TLS protocol is required during the TLS handshake (see Supported cipher suites) and we strongly recommend using the latest version.

#### Timestamp format

Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be

- Not included: YYYY-MM-DDThh:mm:ssZ
- 1 digit: YYYY-MM-DDThh:mm:ss.SZ
- 2 digits: YYYY-MM-DDThh:mm:ss.SSZ
- 3 digits: YYYY-MM-DDThh:mm:ss.SSSZ
  We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.

#### Supported documents for address extraction

| Country        | ID Card | Driving License | Passport | Callback Format |
| -------------- | ------- | --------------- | -------- | --------------- |
| Australia      | No      | Yes             | No       | RAW             |
| Bahrain        | No      | Yes             | No       | RAW             |
| Canada         | No      | Yes             | No       | RAW             |
| France         | Yes     | Yes             | Yes      | RAW             |
| Germany        | Yes     | No              | No       | RAW             |
| India          | Yes     | No              | No       | RAW             |
| Indonesia      | Yes     | No              | No       | RAW             |
| Ireland        | No      | Yes             | No       | RAW             |
| Malaysia       | Yes     | No              | No       | RAW             |
| Malta          | Yes     | Yes             | No       | RAW             |
| Mexico         | Yes     | No              | No       | RAW             |
| Peru           | Yes     | Yes             | No       | RAW             |
| Romania        | Yes     | No              | No       | RAW             |
| Singapore      | Yes     | No              | No       | RAW             |
| Spain          | Yes     | No              | No       | RAW             |
| United Kingdom | No      | Yes             | No       | RAW             |
| United States  | Yes     | Yes             | No       | RAW             |
| Italy          | Yes     | Yes             | Yes      | RAW             |

#### RAW address format

##### idAddress Object

| Parameter        | Max. Length | Description                                                                  |
| ---------------- | ----------- | ---------------------------------------------------------------------------- |
| line1            | 100         | Line item 1                                                                  |
| line2            | 100         | Line item 2                                                                  |
| line3            | 100         | Line item 3                                                                  |
| line4            | 100         | Line item 4                                                                  |
| line5            | 100         | Line item 5                                                                  |
| country          | 3           | Possible countries:<br/>• ISO 3166-1 alpha-3 country code<br/>• XKX (Kosovo) |
| postalCode       | 15          | Postal code                                                                  |
| city             | 64          | City                                                                         |
| subdivision      | 100         | Subdivision (Region, State, Province, Emirate, Department, ...)              |
| formattedAddress |             | Complete address in a formatted way                                          |

##### Reject reason

| Parameter                   | Type                     | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **rejectReasonCode**        | String                   | 5           | Code indicating why the verification was rejected. Possible values: see detailed codes below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **rejectReasonDescription** | String                   | 64          | Human-readable description of the reject reason. **Grouped by `verificationStatus`**: **DENIED_FRAUD**: `100 MANIPULATED_DOCUMENT`, `105 FRAUDSTER`, `106 FAKE`, `107 PHOTO_MISMATCH`, `108 MRZ_CHECK_FAILED`, `109 PUNCHED_DOCUMENT`, `110 CHIP_DATA_MANIPULATED (ePassport only)`, `111 MISMATCH_PRINTED_BARCODE_DATA`, `112 CHIP_MISSING`, `113 MISMATCHING_DATA_REPEATED_FACE`, `114 DIGITAL_MANIPULATION`, `115 MISMATCH_HRZ_MRZ_DATA`, `118 MISMATCH_FRONT_BACK` **ERROR_NOT_READABLE_ID**: `102 PHOTOCOPY_BLACK_WHITE`, `103 PHOTOCOPY_COLOR`, `104 DIGITAL_COPY`, `200 NOT_READABLE_DOCUMENT`, `201 NO_DOCUMENT`, `202 SAMPLE_DOCUMENT`, `206 MISSING_BACK`, `207 WRONG_DOCUMENT_PAGE`, `209 MISSING_SIGNATURE`, `210 CAMERA_BLACK_WHITE`, `211 DIFFERENT_PERSONS_SHOWN (multiple people in one image)`, `213 INVALID_WATERMARK`, `214 MISSING_FRONT`, `300 MANUAL_REJECTION` |
| **rejectReasonDetails**     | JSON object / JSON array | —           | Additional details about the reject reason. Returns a **JSON object** if only one reason applies, or a **JSON array** of objects if multiple reasons exist (e.g., `rejectReasonCode` = 100 or 200). See table below for structure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

1activation required

##### Reject reason details

| Parameter (rejectReasonDetails) | Type   | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **detailsCode**                 | String | 5           | Code indicating the specific reason detail. Possible values: see below.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **detailsDescription**          | String | 32          | Human-readable description of the detail. **Grouped by `rejectReasonCode`**: **100**: `1001 PHOTO`, `1002 DOCUMENT_NUMBER`, `1003 EXPIRY`, `1004 DOB`, `1005 NAME`, `1006 ADDRESS`, `1007 SECURITY_CHECKS`, `1008 SIGNATURE`, `1009 PERSONAL_NUMBER`, `10011 PLACE_OF_BIRTH`, `10012 GENDER`, `10013 DATE_OF_ISSUE` **200**: `2001 BLURRED`, `2002 BAD_QUALITY`, `2003 MISSING_PART_DOCUMENT`, `2004 HIDDEN_PART_DOCUMENT`, `2005 DAMAGED_DOCUMENT`, `2006 GLARE`, `2007 MISSING_MANDATORY_DATAPOINTS` |

##### Identity Verification

**_Required items appear in bold type._**

| Parameter (identityVerification) | Max. Length | Description                                                                                                                                                                                                                                                                                                |
| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **similarity**                   | 1           | Possible values: `MATCH`, `NO_MATCH`, `NOT_POSSIBLE` (not executed or bad quality of face on document)                                                                                                                                                                                                     |
| **validity**                     | 2           | Possible values: `TRUE`, `FALSE`                                                                                                                                                                                                                                                                           |
| **reason**                       |             | Provided if `validity = FALSE`. Possible values: `SELFIE_CROPPED_FROM_ID`, `ENTIRE_ID_USED_AS_SELFIE`, `MULTIPLE_PEOPLE`, `SELFIE_IS_SCREEN_PAPER_VIDEO`, `SELFIE_MANIPULATED`, `AGE_DIFFERENCE_TOO_BIG`, `NO_FACE_PRESENT`, `FACE_NOT_FULLY_VISIBLE`, `BAD_QUALITY`, `BLACK_AND_WHITE`, `LIVENESS_FAILED` |

1 Is the person on the selfie the same as the one on the document? 2 Is it a live person? 3 Potential reasons LIVENESS_FAILED:

- User tries to spoof the system
- User does not want to show his face at all but wants to complete the onboarding
- User does not look straight into the camera
- User does not finish the the Identity Verification process
- User has bad lighting conditions (too dark, too bright, reflections on face, not enough contrast, …)
- User is covering (parts) of his face with a scarf, hat, or something similar
- User is not able to align his face with the oval
- A different person is performing the Identity Verification in the second step than in the first one

##### Driver License Categories

**_Required items appear in bold type._**

| Parameter(dlCategories) | Max. Length | Description                                                                |
| ----------------------- | ----------- | -------------------------------------------------------------------------- |
| category                | 10          | String in Latin or Traditional Chinese characters                          |
| issueDate               |             | Issue date in the format YYYY-MM-DD                                        |
| expiryDate              |             | Date of expiry in the format YYYY-MM-DD as available on the driver license |
| isReadable              |             | Possible value: <ul><li>FALSE</li></ul>                                    |
| availability            |             | Possible values: <ul><li>yes</li><li>no</li><li>not readable</li></ul>     |

## ID Verification Masking

Extracting certain sensitive information from identity documents in the Netherlands, Germany, and South Korea is prohibited by law for customers with a business presence in those countries. These customers can elect to enable ID Verification masking to protect this sensitive data.

When masking is enabled for these countries, certain fields cannot be extracted and returned in the callback. The information contained in these fields is masked before the user's image is stored.

| Country     | Document       | Affected parameters (not returned in the callback)     |
| ----------- | -------------- | ------------------------------------------------------ |
| Denmark     | Passport       | personalNumber                                         |
| Germany     | Passport       | idCheckMRZcode, idNumber                               |
| Germany     | ID card        | idCheckMRZcode, idNumber                               |
| Hong Kong   | Passport       | idCheckMRZcode, idNumber                               |
| Hong Kong   | ID card        | idNumber                                               |
| Japan       | ID card        | idNumber                                               |
| Netherlands | Passport       | idCheckMRZcode, personalNumber                         |
| Netherlands | ID card        | idCheckMRZcode, personalNumber                         |
| Netherlands | Driver license | image is masked, no extracted data fields are affected |
| Singapore   | Passport       | idCheckMRZcode, idNumber                               |
| Singapore   | Driver license | idNumber                                               |
| Singapore   | ID card        | idNumber                                               |
| South Korea | Passport       | idCheckMRZcode, personalNumber                         |
| South Korea | ID card        | idNumber                                               |
| South Korea | Driver license | idNumber                                               |

### Sample Callbacks

**Sample callback (URL-encoded POST): Approved and verified**

`idExpiry=2022-12-31&idType=PASSPORT&idDob=1990-01-01&idCheckSignature=OK&idCheckDataPositions=OK&idCheckHologram=OK&idCheckMicroprint=OK&idCheckDocumentValidation=OK&idCountry=USA&idScanSource=SDK&idFirstName=FIRSTNAME&verificationStatus=APPROVED_VERIFIED&jumioIdScanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&personalNumber=N%2FA&merchantIdScanReference=YOURIDSCANREFERENCE&idCheckSecurityFeatures=OK&idCheckMRZcode=OK&idScanImage=https%3A%2F%2Fnetverify.com%2Frecognition%2Fv1%2Fidscan%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Ffront&callBackType=NETVERIFYID&clientIp=xxx.xxx.xxx.xxx&idLastName=LASTNAME&idAddress=%7B%22city%22%3A%22MIAMI%22%2C%22country%22%3A%22USA%22%2C%22formattedAddress%22%3A%22414+SOUTHWEST+AVE%2C+MIAMI%2C+FL%2C+33184%2C+USA%22%2C%22line1%22%3A%22414+SOUTHWEST+AVE%22%2C%22postalCode%22%3A%2233184%22%2C%22subdivision%22%3A%22FL%22%7D&idScanStatus=SUCCESS&identityVerification=%7B%22similarity%22%3A%22MATCH%22%2C%22validity%22%3Atrue%7D&idNumber=P1234`

**Sample callback (URL-encoded POST): Fraud**

`idType=PASSPORT&idCheckSignature=N%2FA&rejectReason=%7B%20%22rejectReasonCode%22%3A%22100%22%2C%20%22rejectReasonDescription%22%3A%22MANIPULATED_DOCUMENT%22%2C%20%22rejectReasonDetails%22%3A%20%5B%7B%20%22detailsCode%22%3A%20%221001%22%2C%20%22detailsDescription%22%3A%20%22PHOTO%22%20%7D%2C%7B%20%22detailsCode%22%3A%20%221004%22%2C%20%22detailsDescription%22%3A%20%22DOB%22%20%7D%5D%7D&idCheckDataPositions=N%2FA&idCheckHologram=N%2FA&idCheckMicroprint=N%2FA&idCheckDocumentValidation=N%2FA&idCountry=USA&idScanSource=SDK&verificationStatus=DENIED_FRAUD&jumioIdScanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&merchantIdScanReference=YOURSCANREFERENCE&idCheckSecurityFeatures=N%2FA&idCheckMRZcode=N%2FA&idScanImage=https%3A%2F%2Fnetverify.com%2Frecognition%2Fv1%2Fidscan%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Ffront&callBackType=NETVERIFYID&clientIp=xxx.xxx.xxx.xxx&idScanStatus=ERROR`

## Callback for Authentication

An HTTP POST request is sent to your specified callback URL containing an `application/x-www-form-urlencoded` formatted string with the transaction result.

To specify a global callback URL in the Customer Portal, see Configuring Settings in the Customer Portal.

A callback URL can also be specified per transaction in our Android and iOS SDK

Parameters

**_Required items appear in bold type._**

| Parameter                          | Type       | Max. Length | Description                                                                              |
| ---------------------------------- | ---------- | ----------- | ---------------------------------------------------------------------------------------- |
| **callbackDate**                   | string     |             | Timestamp of the callback in the format: YYYY-MM-DDThh:mm:ss.SSSZ                        |
| **transactionReference**           | string     | 36          | Jumio’s reference number for the Authentication transaction                              |
| **enrollmentTransactionReference** | string     | 36          | Jumio’s reference number of the enrollment transaction (ID)                              |
| **transactionResult**              | string     |             | Possible values: <ul><li>PASSED</li><li>FAILED</li><li>INVALID</li><li>EXPIRED</li></ul> |
| **transactionDate**                | string     |             | Timestamp of the transaction in the format: YYYY-MM-DDThh:mm:ss.SSSZ                     |
| **scanSource**                     | string     |             | Possible values: <ul><li>SDK</li><li>WEB</li></ul>                                       |
| **callBackType**                   | string     |             | NETVERIFY_AUTHENTICATION                                                                 |
| idScanImageFace                    | string     |             | URL to retrieve the face image of the transaction (JPEG or PNG) 1                        |
| livenessImages                     | JSON array |             | URLs to the liveness images of the transaction (JPEG or PNG) 1,2                         |
| userReference                      | string     |             | Your internal reference for the user                                                     |

1 Retrieve the images of the transaction. 2 The number of images can vary and may not be returned in chronological order.

### Retrieving Images

Use HTTP GET with Basic Authorization using your API token and secret, as userid and password. Header: The following parameters are mandatory in the header section of your request.

- Accept: image/jpeg, image/png
- User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.

The TLS protocol is required during the TLS handshake (see Supported cipher suites) and we strongly recommend using the latest version.

### Timestamp format

Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be

- Not included: YYYY-MM-DDThh:mm:ssZ
- 1 digit: YYYY-MM-DDThh:mm:ss.SZ
- 2 digits: YYYY-MM-DDThh:mm:ss.SSZ
- 3 digits: YYYY-MM-DDThh:mm:ss.SSSZ
  We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.

### Sample Callback

Sample callback (URL-encoded POST): Passed

`scanSource=SDK&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&enrollmentTransactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callBackType=NETVERIFY_AUTHENTICATION&livenessImages=%5B%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F1%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F2%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F3%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F4%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F5%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F6%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F7%22%5D&idScanImageFace=https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fface&callbackDate=2019-05-30T08%3A37%3A35.822Z&transactionDate=2019-05-29T08%3A37%3A24.344Z&transactionResult=PASSED `

## Callback for Document Verification

### Parameters

The following parameters are posted to your callback URL for Document Verification and Document Verification API.

**_Required items appear in bold type._**

| Parameter         | Type        | Max. Length | Description                                                             |
| ----------------- | ----------- | ----------- | ----------------------------------------------------------------------- |
| **scanReference** | String      | 36          | Jumio's reference number for each transaction                           |
| **timestamp**     | String      |             | Timestamp (UTC) of the response in the format: YYYY-MM-DDThh:mm:ss.SSSZ |
| **transaction**   | JSON object |             | Transaction related data, see table below                               |
| **document**      | JSON object |             | Document related data, see table below                                  |

#### Transaction

**_Required items appear in bold type._**

| Parameter                 | Type   | Max. Length | Description                                                                                                                                                      |
| ------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **date**                  | String |             | Timestamp (UTC) of the transaction creation, format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                                    |
| **status**                | String |             | Possible states: <ul><li>DONE</li><li>FAILED (if initialized acquisition is not successfully finalized within 15 minutes after creation/last update)</li></ul>   |
| **source**                | String |             | Possible values: <ul><li>DOC_UPLOAD (Document Verification)</li><li>DOC_API (Document Verification API)</li><li>DOC_SDK (Document Verification Mobile)</li></ul> |
| **merchantScanReference** | String | 255         | Your reference for each transaction                                                                                                                              |
| **customerId**            | String | 255         | ID of the customer                                                                                                                                               |
| merchantReportingCriteria | String | 255         | Your reporting criteria for each transaction                                                                                                                     |
| clientIp                  | String | 100         | IP address of the client if provided for the Document Verification API                                                                                           |

#### Document

**_Required items appear in bold type._**

| Parameter          | Type        | Max. Length | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status             | String      |             | Possible states: <ul><li>UPLOADED (default) 1</li><li>EXTRACTED (if supported document for data extraction provided) 2</li><li>DISCARDED (if no supported document for data extraction provided)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| country            | String      | 3           | Possible countries: <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| type               | String      |             | Possible types: <ul><li>CC (Credit card, front and back side)</li><li>BS (Bank statement, front side)</li><li>IC (Insurance card, front side)</li><li>UB (Utility bill, front side)</li><li>CAAP (Cash advance application, front and back side)</li><li>CRC (Corporate resolution certificate, front and back side)</li><li>CCS (Credit card statement, front and back side)</li><li>LAG (Lease agreement, front and back side)</li><li>LOAP (Loan application, front and back side)</li><li>MOAP (Mortgage application, front and back side)</li><li>TR (Tax return, front and back side)</li><li>VT (Vehicle title, front side)</li><li>VC (Voided check, front side)</li><li>STUC (Student card, front side)</li><li>HCC (Health care card, front side)</li><li>CB (Council bill, front side)</li><li>SENC (Seniors card, front side)</li><li>MEDC (Medicare card, front side)</li><li>BC (Birth certificate, front side)</li><li>WWCC (Working with children check, front side)</li><li>SS (Superannuation statement, front side)</li><li>TAC (Trade association card, front side)</li><li>SEL (School enrolment letter, front side)</li><li>PB (Phone bill, front side)</li><li>SSC (Social security card, front side)</li><li>CUSTOM (Custom document type)</li><li>OTHER (Other document type)</li></ul> |
| images             | JSON array  |             | URLs to the images of the transaction (JPEG or PNG) 3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| originalDocument   | String      |             | URL to the originally submitted document of the transaction (PDF) if available 3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| customDocumentCode | String      | 100         | Your custom document code (maintained in your Jumio customer portal) if type = CUSTOM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| extractedData      | JSON object |             | Extracted data if status = EXTRACTED, see Supported documents for Data Extraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

1 This also applies for document type CCS where no masking was needed as no full PAN is displayed. 2 If masking has been done, status will be always EXTRACTED as well. This applies to all documents uploaded with type CC, as well as to documents uploaded with type CCS where a ful PAN is displayed. 3 Retrieve the images of the transaction.

#### Retrieving Images

Use HTTP GET with Basic Authorization using your API token and secret, as userid and password. Header: The following parameters are mandatory in the header section of your request.

- Accept: image/jpeg, image/png
- User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues.
  The TLS protocol is required during the TLS handshake (see Supported cipher suites) and we strongly recommend using the latest version.

#### Timestamp format

Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be:

Not included: YYYY-MM-DDThh:mm:ssZ
1 digit: YYYY-MM-DDThh:mm:ss.SZ
2 digits: YYYY-MM-DDThh:mm:ss.SSZ
3 digits: YYYY-MM-DDThh:mm:ss.SSSZ
We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.

### Extracted Data

| Parameter          | Type        | Max. Length | Description                                                                 |
| ------------------ | ----------- | ----------- | --------------------------------------------------------------------------- |
| firstName          | String      | 255         | First name if readable                                                      |
| lastName           | String      | 255         | Last name if readable                                                       |
| name               | String      | 100         | Full name if readable                                                       |
| accountNumber      | String      | 34          | Bank account number of the customer from a bank statement                   |
| pan                | String      | 20          | Personal account number of credit card                                      |
| issueDate          | String      |             | Issue date in the format YYYY-MM-DD                                         |
| expiryDate         | String      |             | Date of expiry in the format YYYY-MM-DD                                     |
| ssn                | String      | 255         | Social security number if readable                                          |
| signatureAvailable | String      |             | true if signature available, otherwise false                                |
| swiftCode          | String      | 20          | BIC/SWIFT code                                                              |
| address            | JSON object |             | Address as JSON object in RAW format if status = EXTRACTED, see table below |

### RAW address format

| Parameter        | Max. Length | Description                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| line1            | 100         | Line item 1                                                                                             |
| line2            | 100         | Line item 2                                                                                             |
| line3            | 100         | Line item 3                                                                                             |
| line4            | 100         | Line item 4                                                                                             |
| line5            | 100         | Line item 5                                                                                             |
| countryCode      | 3           | Possible countries of residence: <ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul> |
| postalCode       | 15          | Postal code                                                                                             |
| city             | 64          | City                                                                                                    |
| subdivision      | 50          | Name of subdivision                                                                                     |
| formattedAddress |             | Complete address in a formatted way                                                                     |

### Supported documents for data extraction

The following data points will be extracted for all documents printed in a Latin-script character set, provided that a minimum of one of these data points are available for extraction. If the document does not meet these extraction criteria, only the document image will be saved — no data extraction will be performed.

| Type                           | Extracted data                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| BS (bank statement)            | <ul><li>name</li><li>issueDate</li><li>address</li><li>accountNumber</li><li>swiftCode</li></ul> |
| UB (utility bill)              | <ul><li>name</li><li>issueDate</li><li>address</li><li>dueDate</li></ul>                         |
| CCS (credit card statement)    | <ul><li>name</li><li>issueDate</li><li>address</li><li>cardNumberLastFourDigits</li></ul>        |
| OTHER (Other document type)    | <ul><li>name</li><li>issueDate</li><li>address</li></ul>                                         |
| CC (credit card) 1,3           | <ul><li>name</li><li>pan</li><li>expiryDate (currently returned as issueDate)</li></ul>          |
| SSC (Social Security card) 1,2 | <ul><li>firstName</li><li>lastName</li><li>ssn</li><li>signatureAvailable</li></ul>              |

1 For CC and SSC all data points need to be available for extraction. 2 USA only. 3 For CC date extraction format is MM/YY

### Sample Callbacks

Sample callback (URL-encoded POST): UPLOADED

`timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22AUT%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22UPLOADED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D `

Sample callback (URL-encoded POST): EXTRACTED

`timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22extractedData%22%3A%7B%22firstName%22%3A%22FIRSTNAME%22%2C%22lastName%22%3A%22LASTNAME%22%2C%22signatureAvailable%22%3Atrue%2C%22ssn%22%3A%22xxxxxxxxx%22%7D%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22EXTRACTED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D`

Sample callback (URL-encoded POST): DISCARDED

`timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22DISCARDED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D`

## ID Verification Retrieval API

If your server was not able to receive or process the callback, you can use the Retrieval API to retrieve the results of your transaction.

---

# ID Verification & ComplyAdvantage Screening Implementation Guide

https://documentation.jumio.ai/docs/Integrate/netVerifyv2/idVerification/complyAdvantageScreening

# ID Verification & ComplyAdvantage Screening Implementation Guide

This is a reference manual and configuration guide for the ComplyAdvantage PEPs/Sanctions Screening integration with ID Verification. It describes how to request a ComplyAdvantage account through Jumio, creating API keys through the ComplyAdvantage portal, setting up screening in the customer portal, and changes to the ID Verification APIs to include screening.

## Requesting a Jumio Screening Account

If you are interested in including PEPs/Sanctions screening with your ID Verification package, please contact your Jumio Account Manager.

When your discussions have concluded, your Account Manager will have your ComplyAdvantage account created.

## ComplyAdvantage portal setup

Once ComplyAdvantage creates your account, you'll receive a verification email, with a link, which will grant you access to your ComplyAdvantage customer portal.

The ComplyAdvantage customer portal will allow you to update new users, manage API keys and manage your watchlist.

### Creating API keys

API keys are used to allow access to ComplyAdvantage's APIs and to run searches. You can create as many as you want from the ComplyAdvantage portal and they can be deleted at any time, as an admin user.

Once you've logged into ComplyAdvantage's portal you will have a menu on the left side.

Under API, select API Keys

From this page, you will be able to manage all of the API keys that are associated with your ComplyAdvantage account.

To create a new API key, enter a New Key Label and click Create.

### Creating a screening profile

Next, you'll need to create a screening profile. Profiles are a collection of the various lists that you want to search against. You can choose which list you want to include in a profile based on your business. Examples could be based on geography or risk levels. There is no limit to the number of lists you can create.

(link to something to help them pick list)

To begin, select Search Profiles under Settings from the main page menu.

You can manage all of your search profiles from this page.

To create a new profile, click Add new search profile.

On this page, you will be asked to

Select search profile ID
Select source list by type and/or location
Select group

### Creating ID Verification Tag

For full functionality, you will want to enable the ID Verification tags. To do so, you will have to create a tag within the ComplyAdvantage portal.

From the main portal, you will need to navigate to Tags, under Settings on the left menu bar.

Enter "netverify-link" as the name of the tag and select "Tag: Name combination" for Case Management Display.

Save the new tag.

## Customer portal setup

After you finished setting up your ComplyAdvantage portal, you will need to setup your ID Verification portal for screening also.

After logging into your ID Verification portal, go to Settings.

Under Data settings, click on the Watchlist Screening tab. If this tab is not visible, please contact Jumio Support.

You will be required to enter your API Key and have the option to define a default search profile.

`Jumio`

Another optional setting is the Search enabled for approved IDs.

If enabled, this setting will make it so all transactions that are approved will be screened. Rejected documents will never be screened.

If you do not define the profile to screen against within the API call, transactions will be screened against the default profile which you can define within the portal.

Finally, you will want to turn on

## Include screening in ID Verification API

Finally, depending on which integrations you use, you will need to update your ID Verification APIs for all or select transactions which you want screening to occur.

If you've set your screening to search if approved by default within the portal, you do not have to make any changes to the API if you want all Approved/Verified transactions to be screened.

However, the portal setting can be overwritten in the API calls by including additional parameters.

### Web screening

The additionalChecks field must be included within the presets of the ID Verification Web v4 API call with the following, under watchlistScreening.

Additionally, userReference will be used to associate Jumio Screening with ID Verification transactions and must be included and populated in API calls.

More information regarding the ID Verification Web v4 can be found here: ID Verification Web Implementation Guide

| Field Name               | Values                                      |
| ------------------------ | ------------------------------------------- |
| enabledSearch (optional) | <ul><li>true</li><li>false</li></ul>        |
| searchProfile (optional) | string – Name of profile in ComplyAdvantage |

Sample Request Body

```
{
 "customerInternalReference": "transaction_1234",
 "userReference": "user_1234",
 "workflowId": 100,
 "presets": [
     {
       "index": 1,
       "country": "USA",
       "type": "DRIVING_LICENSE",
       "additionalChecks": {
          "watchlistScreening": {
              "enableSearch": "true",
              "searchProfile": "sanctions-only"
          }
       }
     }
 ],
 "locale": "en-GB"
}
```

### API screening

The additionalChecks field must be included within the body of the performNetverify API call with the following, under watchlistScreening.

Additionally, customerId will be used to associate Jumio Screening to ID Verification transactions and must be included and populated in API calls.

If end-user consent may apply to you, please make sure to obtain consent as mentioned on End-User Consent for Biometric Data in API.

More information regarding the ID Verification API can be found here: ID Verification API Implementation Guide

| Field Name               | Values                                      |
| ------------------------ | ------------------------------------------- |
| enabledSearch (optional) | <ul><li>true</li><li>false</li></ul>        |
| searchProfile (optional) | string – Name of profile in ComplyAdvantage |

Sample Request Body

```
{
   "merchantIdScanReference": "YOURSCANREFERENCE",
   "customerId": "customer_1234",
   "country": "USA",
   "idType": "DRIVING_LICENSE",
   "additionalChecks": {
      "watchlistScreening": {
           "enableSearch": "true",
           "searchProfile": "sanctions-only"
       }
   }
}
```

### How to review results

The results of the screening will be available from the callback, in the portal, or using the Retrieval API.

#### Callback with screening

The callback will only return the results of the screening search that was done as part of the transaction. Any other searches outside the transaction, either manual or with ComplyAdvantage API, will not be returned here.

The following fields may be additional to the original callback fields, if they apply to the search that was done.

More information regarding the callback can be found here: Callback Implementation Guide

| Field Name        | Values                                       |
| ----------------- | -------------------------------------------- |
| **searchStatus**  | string - DONE, NOT_DONE, ERROR               |
| searchId          | string – only when searchStatus = DONE       |
| searchReference   | string – only when searchStatus = DONE       |
| searchResults     | numeric – only when searchStatus = DONE      |
| searchResultsLink | string (URL) – only when searchStatus = DONE |
| searchDate        | timestamp – only when searchStatus = DONE    |

#### Full URL-encoded callback example

`idCheckMicroprint=OK&callBackType=NETVERIFYID&merchantIdScanReference=feb924fe-5377-4493-b660-8dc246c0a07a&idCheckDocumentValidation=OK&idLastName=MUSTERMANN&callbackDate=2018-10-25T13%3A43%3A21.131Z&idNumber=12345678&idCheckDataPositions=OK&merchantReportingCriteria=QA&customerId=98e59b44-aadf-4395-9982-36d07834f22c&idFirstName=KAL+UWE&firstAttemptDate=2018-10-25T13%3A43%3A11.411Z&idScanSource=API&idCheckMRZcode=N%2FA&idScanStatus=SUCCESS&idType=DRIVING_LICENSE&jumioIdScanReference=08680580-7b0c-498d-8715-07a9fe5ad123&additionalChecks=%7B%22watchlistScreening%22%3A%7B%22searchStatus%22%3A%22DONE%22%2C%22searchDate%22%3A%222018-10-25T14%3A43%3A20Z%22%2C%22searchId%22%3A%2281536971%22%2C%22searchReference%22%3A%221540475000-PyxBXf9K%22%2C%22searchResultUrl%22%3A%22https%3A%2F%2Fapp.complyadvantage.com%2Fpublic%2Fsearch%2F1540475000-PyxBXf9K%2Faf58b6eeda81%22%2C%22searchResults%22%3A0%7D%7D&verificationStatus=APPROVED_VERIFIED&idScanImage=https%3A%2F%2Fnetverify.test33.testlab.int.jumio.com%2Frecognition%2Fv1%2Fidscan%2F08680580-7b0c-498d-8715-07a9fe5ad123%2Ffront&identityVerification=%7B%7D&idDob=1984-08-20&transactionDate=2018-10-25T13%3A43%3A11.412Z&idCountry=AUT&idCheckSignature=OK&idCheckSecurityFeatures=OK&idCheckHologram=OK`

#### Retrieval API with screening

The Retrieval API will only return the screening results of the search that was done as part of the transaction. Any other searches outside the transaction, either manual or with ComplyAdvantage API, will not be returned here.

The following fields may be additional to the original callback fields, if they apply to the search that was done.

| Field Name        | Values                                       |
| ----------------- | -------------------------------------------- |
| searchStatus      | string - DONE, NOT_DONE, ERROR               |
| searchId          | string – only when searchStatus = DONE       |
| searchReference   | string – only when searchStatus = DONE       |
| searchResults     | numeric – only when searchStatus = DONE      |
| searchResultsLink | string (URL) – only when searchStatus = DONE |
| searchDate        | timestamp – only when searchStatus = DONE    |

**Full Retrieval API Response Body**

```
{
    "timestamp": "2018-10-25T13:53:17.050Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "document": {
        "type": "DRIVING_LICENSE",
        "dob": "1984-08-20",
        "firstName": "",
        "issuingCountry": "USA",
        "lastName": "",
        "number": "12345678",
        "status": "APPROVED_VERIFIED"
    },
    "transaction": {
        "customerId": "customer_1234",
        "date": "2018-10-25T13:43:11.412Z",
        "merchantScanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "source": "API",
        "status": "DONE"
    },
    "verification": {
        "additionalChecks": {
            "watchlistScreening": {
                "searchDate": "2018-10-25T14:43:20Z",
                "searchId": "12345678",
                "searchReference": "xxxxxxxxxx-xxxxxxxx",
                "searchResultUrl": "https://app.complyadvantage.com/public/search/xxxxxxxxxx-xxxxxxxx/12345678",
                "searchResults": "0",
                "searchStatus": "DONE"
            }
        },
        "identityVerification": null,
        "mrzCheck": "NOT_AVAILABLE"
    }
}
```

**Full Retrieval API Response Body without search**

```
{
  "timestamp": "2018-11-05T14:28:38.899Z",
  "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "document": {
    "type": "PASSPORT",
    "dob": "1956-10-11",
    "expiry": "2025-05-06",
    "firstName": "",
    "issuingCountry": "USA",
    "lastName": "",
    "number": "P12345678",
    "personalNumber": "123456789",
    "status": "APPROVED_VERIFIED"
  },
  "transaction": {
    "date": "2018-11-05T14:28:17.954Z",
    "merchantScanReference": "",
    "source": "API",
    "status": "DONE"
  },
  "verification": {
    "additionalChecks": {
      "watchlistScreening": {
        "searchStatus": "NOT_DONE"
      }
    },
    "identityVerification": null,
    "mrzCheck": "OK"
  }
}
```

### Ongoing Monitoring

This is an additional service that is offered that will notify you if your search appears in a list after the original search was executed.

For more information about including this in your contract, please contact your Jumio Account Manager.

If you have Ongoing Monitoring included in your contract, you have to turn on 'Auto monitor' in your ComplyAdvantage portal, additional settings can be found there as well.

Checkout [ComplyAdvantage](https://auth.complyadvantage.com/login?client_id=234l01qbmm69745r3uf75h44pl&redirect_uri=https%3A%2F%2Fapp.complyadvantage.com%2Foauth2%2Fidpresponse&response_type=code&scope=aws.cognito.signin.user.admin%20email%20openid%20profile&state=ajQu0W3qdcw%2BJ43i8n9whkhz6eJLuQq2yxs4nKnS2rAgO%2FTkqkxuCTF8INO1%2FhUtEn6ypFHjHS92Bd%2BqRUIc1cHueT0s4ofWx3jJlxmPMSOflxI5CiyQcXmkRsnBxWABMOae6iVlqoKaFhlNL2wcAaeu%2FSGBwRX92ibV9%2FoJkQn8Iiu4D%2BYe2AC9EQ1gMUu7C5oCj3CqLo9fhYzQxd79XsX8bVlN%2FI8SaqZPS%2F9maovT1jhY5e1KHw%3D%3D#/settings/monitor)

When monitoring is turned on, the transactions which have monitoring will be searched against the database and list each night. If a new entry is found, the admin users from the ComplyAdvantage portal will be notified through email.

---

# Introduction to v3

https://documentation.jumio.ai/docs/Integrate/V3/Introduction

:::note
This content applies to the legacy v3 products. Documentation for the current Jumio Platform is available at Jumio Documentation.
:::

The Jumio v3 (Legacy) Platform API allows you to manage your user journeys. It allows you to create and update accounts for your users, prompt them to provide data such as a photo ID and selfie, and get identity verification results in real time so you can complete their onboarding.

The v3 Platform API is user-based and highly flexible, allowing various workflows that can be easily combined into a single user journey. Each workflow defines a single transaction executing a series of specific tasks, such as data extraction and a liveness check. Multiple workflows can be executed on the same account. Your workflows can execute functionality from several Jumio products, including:

ID Verification: Is this photo ID valid?
Identity Verification: Is this person who they say they are?
The following diagram shows several possible workflows:

![](./images/v3workflow_overview.png)

Some functionalities described in this document might be unavailable, depending on the scope of your license with Jumio. Contact your Jumio Solutions Engineer if you have any questions.

## Implementation Steps:

Account Creation
Account Update
Data Acquisition
Finalization

## Authentication and Encryption

API calls are protected using either HTTP Basic Authentication or OAuth2.

⚠️ Never share your API token, API secret, or OAuth2 credentials with anyone — not even Jumio Support!
The Account Management Service initiates the acquisition process and returns:

either a JSON Web Token (JWT), which can be used to authenticate to the Jumio backend system to use with the SDK
or Redirect-URLs, which can be used to upload documents using the other channels
At the moment, your Basic Auth credentials are constructed using your API token as the User ID and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under:

Settings > API credentials > API Users

### OAuth2

Your new OAuth2 credentials are constructed using your API token as the Client ID and your API secret as the Client secret. You can view and manage your API token and secret in the Customer Portal under:

Settings > API credentials > OAuth2 Clients
Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation.

Access Token URL (OAuth2)
US: https://auth.amer-1.jumio.ai/oauth2/token
EU: https://auth.emea-1.jumio.ai/oauth2/token
SG: https://auth.apac-1.jumio.ai/oauth2/token
The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see supported cipher suites.

ℹ️ Calls with missing, incorrect or suspicious headers or parameter values will result in HTTP status code 400 Bad Request Error or 403 Forbidden

### Examples

Request Access Token

```
curl --location --request POST 'https://auth.amer-1.jumio.ai/oauth2/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-raw 'grant_type=client_credentials' \
    --basic --user CLIENT_ID:CLIENT_SECRET
```

Response

```
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

### Access Token Timeout

Your OAuth2 access token is valid for 60 minutes. After the token lifetime is expired, it is necessary to generate a new access token.

### Workflow Transaction Token Timeout

The token lifetime is set to 30 minutes per default. It can be configured via the Jumio Customer Portal and can be overwritten using the API call (tokenLifetime). Within this token lifetime the token can be used to initialize the SDK, API or Web journey.

As soon as the workflow (transaction) starts, a 15 minutes session timeout starts. For each action performed (capture image, upload image) the session timeout will reset, and the 15 minutes will start again.

## Account Creation

Create a new account for your end user by using the following API endpoint and below mentioned request headers and request body:

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

### Request Headers

The following fields are required in the header section of your Request

```
Accept: application/json
Content-Type: application/json
Content-Length: see RFC-7230
Authorization: see RFC6749
User-Agent: YourCompany YourApp/v1.0
```

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden

### Request Body

The body of your initiate API request allows you to:

provide your own internal tracking information for the user and transaction.
specify what user information is captured and by which method.
preset options to enhance the user journey.
Values set in your API request will override the corresponding settings configured in the Customer Portal.

(Mandatory parameters in bold.)

| Parameter                       | Type           | Max. Length | Notes                                                                                                                                                                                                          |
| ------------------------------- | -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **customerInternalReference**   | string         | 100         | Customer internal reference for linking the request in the customer backend (must not contain any PII)                                                                                                         |
| **workflowDefinition**          | object         | –           | Definition of the specific documents required to execute the workflow capabilities                                                                                                                             |
| **userConsent2**                | object         | –           | User consent required where facial recognition or biometric data processing is used. Possible values: See `userConsent`                                                                                        |
| workflowDefinition.key          | object         | –           | Key of the workflow definition to execute. See Workflow Definition Keys                                                                                                                                        |
| workflowDefinition.credentials  | array (object) | –           | Optional. Customize the acquiring and workflow process. See `workflowDefinition.credentials` for possible values                                                                                               |
| workflowDefinition.capabilities | object         | –           | Optional. Customize the acquiring and workflow process. See `workflowDefinition.capabilities` for possible values                                                                                              |
| userReference1                  | string         | 100         | Reference for the end user in the customer backend (must not contain any PII)                                                                                                                                  |
| reportingCriteria               | string         | 255         | Additional information provided by the customer for searching and aggregation purposes                                                                                                                         |
| callbackUrl                     | string         | 255         | Callback URL for this request. Overrides the callback URL set in the Customer Portal                                                                                                                           |
| tokenLifetime                   | string         | –           | Valid period unit: `s` (seconds), `m` (minutes), `h` (hours), `d` (days). Minimum: 5m, Maximum: 60d, Default: 30m. Overrides Authorization token lifetime in the Customer Portal. Example: `1d`, `30m`, `600s` |
| web                             | object         | –           | Parameters relevant only for the Web channel                                                                                                                                                                   |
| web.successUrl                  | string         | 255         | URL to redirect the end user after a successful web acquisition. Overrides success URL in the Customer Portal                                                                                                  |
| web.errorUrl                    | string         | 255         | URL to redirect the end user after a failed web acquisition. Overrides error URL in the Customer Portal                                                                                                        |
| web.locale                      | string         | 5           | Renders content in the specified language. Overrides default locale in the Customer Portal. See supported locale values                                                                                        |

1 Mandatory request parameter for Workflow 32: ID Verification, Identity Verification, Screening.. 2 Mandatory for End-User Consent even if the user is not based in USA.

#### Request workflowDefinition.credentials

| Parameter              | Type           | Max. Length | Notes                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | -------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| category               | string         | –           | Type of credential. Possible values: `ID`, `FACEMAP`, `DOCUMENT`, `SELFIE`                                                                                                                                                                                                                                                                                                    |
| country                | object         | –           | Defines the countries applicable for the workflow. Possible values: `country.predefinedType`, `country.values`                                                                                                                                                                                                                                                                |
| country.predefinedType | string         | –           | Determines how the country is presented to the end user. Possible values: `DEFINED` (default: end user cannot change), `RECOMMENDED` (preselected but user can change)                                                                                                                                                                                                        |
| country.values         | array (string) | –           | List of applicable countries. At least one ISO 3166-1 alpha-3 country code must be defined for the workflow. Example: `USA`, `BRA`, `DEU`                                                                                                                                                                                                                                     |
| type                   | object         | –           | Defines the credential type(s) used in the workflow. Possible values: `type.predefinedType`, `type.values`                                                                                                                                                                                                                                                                    |
| type.predefinedType    | object         | –           | Determines how the document type is presented to the end user. Possible values: `DEFINED` (default: user cannot change), `RECOMMENDED` (preselected but user can change)                                                                                                                                                                                                      |
| type.values            | array (string) | –           | List of credential types allowed for the workflow. Possible values: • If `category = ID`: `ID_CARD`, `DRIVING_LICENSE`, `PASSPORT`, `VISA` • If `category = FACEMAP`: `IPROOV_STANDARD` (Web + SDK only), `IPROOV_PREMIUM` (Workflow 3: ID & Identity Verification Web + SDK / Workflow 9: Authentication SDK / Workflow 16: Authentication On Premise SDK), `JUMIO_STANDARD` |

1 Web channel: Only supports predefined country and type when both are provided. Also only a single country and a single type must be specified, a list of presets is not supported for Web.

#### Request workflowDefinition.capabilities

| Parameter                               | Type   | Max. Length | Notes                                                                                                                    |
| --------------------------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| **watchlistScreening**                  | object | –           | Configuration options for the Watchlist Screening capability. Possible values: `watchlistScreening.additionalProperties` |
| watchlistScreening.additionalProperties | string | –           | Provide request options for the Watchlist Screening capability.                                                          |

#### Request userConsent

| Parameter            | Type   | Max. Length | Notes                                                                                                                                                                                                                                                                                 |
| -------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **userIp**           | string | –           | Current IP address of the end-user used during the verification.                                                                                                                                                                                                                      |
| **userLocation**     | object | –           | End-user location details. Possible values: `userLocation.country`, `userLocation.state`.                                                                                                                                                                                             |
| userLocation.country | string | 3           | Current country based on the end-user’s location during verification. Possible values: ISO 3166-1 alpha-3 country codes.                                                                                                                                                              |
| userLocation.state   | string | 100         | Current state/province as per end-user location. Applicable only in countries with states (e.g., USA, CAN, AUS). For USA, CAN, AUS: provide alpha-2 state code (without country & hyphen), e.g., IL (Illinois), NSW (New South Wales). For other countries, any string if applicable. |
| **consent**          | object | –           | End-user consent details. Possible values: `consent.obtained`, `consent.obtainedAt`.                                                                                                                                                                                                  |
| consent.obtained     | string | –           | Indicates whether end-user consent was obtained. Possible values: `yes` (consent given), `no` (consent not given), `na` (not applicable). Mandatory if `userLocation.country = USA`.                                                                                                  |
| consent.obtainedAt   | string | –           | UTC timestamp when consent was obtained. Format: `YYYY-MM-DDThh:mm:ss.SSSZ`. Mandatory if `consent.obtained = yes`.                                                                                                                                                                   |

1 Mandatory for End-User Consent even if the user is not based in USA. 2 Mandatory for End-User Consent if userLocation.country = USA / consent.obtained = yes

### Response

Unsuccessful requests will return HTTP status code 400 Bad Request, 401 Unauthorized, 403 Forbidden or 404 Not Found (in case of a failed update scenario) if the scan is not available.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

| Parameter                     | Type           | Notes                                                                                                                                             |
| ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| timestamp                     | string         | UTC timestamp of the response. Format: `YYYY-MM-DDThh:mm:ss.SSSZ`.                                                                                |
| account                       | object         | Account details. Possible values: `account.id`.                                                                                                   |
| account.id                    | string         | UUID of the account.                                                                                                                              |
| sdk                           | object         | SDK parameters (only relevant for SDK channel). Possible values: `sdk.token`.                                                                     |
| sdk.token                     | string         | JWT token for performing any SDK action.                                                                                                          |
| workflowExecution             | object         | Workflow execution details. Possible values: `workflowExecution.id`, `workflowExecution.credentials`.                                             |
| workflowExecution.id          | string         | UUID of the workflow.                                                                                                                             |
| workflowExecution.credentials | array (object) | Credential response objects. See `workflowExecution.credentials`.                                                                                 |
| web                           | object         | Web parameters (only relevant for WEB channel). Possible values: `web.href`, `web.successUrl`, `web.errorUrl`.                                    |
| web.href                      | string         | URL for accessing the workflow in the browser.                                                                                                    |
| web.successUrl                | string         | URL where the browser redirects the user after a successful web acquisition journey (defined in Customer Portal or overwritten in initiate call). |
| web.errorUrl                  | string         | URL where the browser redirects the user after a failed web acquisition journey (defined in Customer Portal or overwritten in initiate call).     |

#### esponse workflowExecution.credentials

| Parameter             | Type   | Notes                                                                                                                                                                     |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                    | string | UUID of the credential.                                                                                                                                                   |
| category              | string | Possible values: `ID`, `FACEMAP`, `DOCUMENT`, `SELFIE`.                                                                                                                   |
| country               | object | Define at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: ISO 3166-1 alpha-3 country code.                                        |
| type                  | object | Define the credential type codes. Possible values: `ID_CARD`, `DRIVING_LICENSE`, `PASSPORT`, `VISA`.                                                                      |
| allowedChannels       | array  | Channels supported to upload this credential. Possible values: `WEB`, `API`, `SDK`.                                                                                       |
| api                   | object | Available actions for API calls (some actions may be unavailable). Only relevant for the API channel. Possible values: `api.token`, `api.parts`, `api.workflowExecution`. |
| api.token             | string | JWT token for performing any API action. Only relevant for the API channel.                                                                                               |
| api.parts             | object | Href to manage parts of the credential. Possible values: `FRONT`, `BACK`, `FACE`, `FACEMAP`. Only relevant for the API channel.                                           |
| api.workflowExecution | string | Href to manage the acquisition and workflow processing. Only relevant for the API channel.                                                                                |

### Examples

Initiate Account

```
curl --location --request POST 'https://account.amer-1.jumio.ai/api/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 2,
            "credentials": [
                {
                  "category": "ID",
                  "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA", "CAN", "AUT", "GBR"]
                  },
                  "type": {
                    "predefinedType": "DEFINED",
                    "values": ["DRIVING_LICENSE", "ID_CARD"]
                  }  
                }
            ],
            "capabilities": {
              "watchlistScreening": {
                "additionalProperties": "string"
              }
            }
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE",
        "userConsent": {
            "userIp": "226.80.211.232",                    
            "userLocation": {
                "country": "USA",                       
                "state": "IL"                           
            },
             "consent": {
              "obtained": "yes",                        
              "obtainedAt": "2022-07-20T17:20:35.000Z"  

            }
        }
    }'
```

## Account Update

After you have created an account for an end user, you can use this API to update that account. You will use this API endpoint for every new workflow (transaction) you need to initialize for that end user.

Updating an account is very similar to creating one; the request headers and body are the same in both cases. The difference is that you pass the accountId to the endpoint and use PUT instead of POST.

### Request

HTTP Request Method: PUT

```
US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>
EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>
SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>
```

Request Headers
Please refer to Account Create section above.

Request Body
Please refer to Account Create section above.

Response
Please refer to Account Create section above.

#### Examples

Request

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer
YOUR_ACCESS_TOKEN' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_INTERNAL_REFERENCE",
    "workflowDefinition": {
        "key": 2,
        "credentials": [
            {
                "category": "FACEMAP",
                "type": {
                    "values": ["IPROOV_STANDARD", "JUMIO_STANDARD"]
                }
            },
            {
                "category": "ID",
                "type": {
                    "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                },
                "country": {
                    "values": ["USA", "CAN", "AUT"]
                }
            }
        ]
    },
    "userConsent": {
        "userIp": "226.80.211.232",
        "userLocation": {
            "country": "AUT"
        }
    }
}
```

#### Response

```
{
    "timestamp": "2021-05-28T09:17:50.240Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationTokenxxx&locale=es",
        "successUrl": "https://www.yourcompany.com/success",
        "errorUrl": "https://www.yourcompany.com/error"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Implementation Steps: Sequence Diagram

![](./images/implementation_steps_sequence_diagram.png)

## Workflow Descriptions

### Workflow Definition Keys

| Definition Key | Name                                              | Description                                                                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1              | ID Capture and Storage                            | Captures a government-issued ID document and stores the extracted data.                                                                                                                                                                                                               |
| 2              | ID Verification                                   | Verifies a government-issued ID document and returns: (a) whether the document is valid, and (b) the data extracted from the document.                                                                                                                                                |
| 3              | ID and Identity Verification                      | Verifies a photo ID document and returns: (a) whether the document is valid, and (b) the extracted data. Also compares the user’s face with the ID photo and performs a liveness check to confirm the person is physically present.                                                   |
| 5              | Similarity to Existing ID                         | Matches a user’s selfie to the face from a previously verified and stored ID document.                                                                                                                                                                                                |
| 6              | Standalone Liveness                               | Captures a user’s face to verify that the person is physically present and not presenting a photo or other spoofed image.                                                                                                                                                             |
| 9              | Authentication                                    | Compares a user’s facemap to an existing facemap captured during a previous workflow (for example, Workflow 3 or Workflow 6).                                                                                                                                                         |
| 16             | Authentication on Premise                         | Compares a user’s facemap to an existing facemap stored on the customer side. The facemap must have been captured during a previous workflow (for example, Workflow 3 or Workflow 6) and can be retrieved using the Retrieval API with the `validFaceMapForAuthentication` parameter. |
| 20             | Similarity of Two Images                          | Matches user photos across two IDs, two selfies, or a selfie and an ID photo to verify they belong to the same person.                                                                                                                                                                |
| 32             | ID Verification, Identity Verification, Screening | Verifies a photo ID document and returns: (a) whether the document is valid, and (b) extracted data. Also performs face comparison, liveness detection, and checks whether the user appears on any sanctions lists.                                                                   |

Workflows are specified using the key attribute in the workflowDefinition object:

```
"workflowDefinition": {
    "key": DEFINITION_KEY,
    "credentials": []
}
```

## End-User Consent for Biometric Data

To collect consent on Jumio’s behalf, you will need to incorporate certain explicit consent collection language and a link to Jumio’s Privacy Notice within your user consent flow before collection of end-user biometric data, if the end-user is located inside the United States.

The following is an example of how consent may be presented to the end-user, but you may use your own custom language as long as the required elements are present:

“By clicking “Start” you consent to Jumio collecting, processing, and sharing your personal information, which may include biometric data, pursuant to its Privacy Notice.”

### When to share consent parameters?

Every transaction which includes any product/workflow step in which biometrics are collected needs to have consent parameters adapted and populated. This means if Face match is enabled for your account, Liveness, or Authentication is used you will need to share consent parameters.

If your Privacy Policy and Terms & Conditions allowing continuous use of consent obtained from end-user on biometric data collection and processing the timestamp (consent.obtainedAt) should be when the original/updated consent was obtained.

If consent is not provided or other scenarios where consent needs to be resubmitted use our Account Update API to add the needed consent parameters.

⚠️ If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt) has to be updated accordingly.
Note: Until further notice Jumio will not perform any treatment based on the consent parameters. After a notice period business validation will be performed which could also lead to a rejection of the transaction, also providing additional consent specific error codes. The rejection will happen at the data acquisition step and not at the Account Create or Account Update stage. We will inform you separately on a specific date.

#### Which Jumio products collect biometrics?

| Jumio Product / Workflow Step | Biometric Component                                                                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Jumio Identity Verification   | Includes liveness detection and face matching. May also serve as the base facemap creation for future authentication workflows.                                       |
| Jumio Go                      | Includes liveness detection and face matching.                                                                                                                        |
| Authentication                | Creates a new facemap and compares it against an existing stored facemap.                                                                                             |
| ID Verification               | Includes face matching (if enabled for the account).                                                                                                                  |
| Jumio Video Verification      | Includes liveness detection and face matching.                                                                                                                        |
| Jumio Screening               | **ID Verification:** Includes face matching (if 1:n face match is enabled for the account). **Identity Verification:** Includes liveness detection and face matching. |

### Where to share consent parameters?

Within the consent area in the API request body.

Always mandatory: Populate the end-user IP address and end-user current location (userLocation.userIp,userLocation.country)
Mandatory if userLocation.country = USA: Populate the consent parameters (i.e., status, timestamp)
See examples for a sample request including the user consent parameters.

## Data Acquisition

SDK
This section illustrates how to implement the SDK.

After creating/updating a new account you will receive a sdk.token (JWT) for initializing the SDK. Use this token with your Android or iOS code.

#### Android

```
try {
  sdk = JumioSDK(this)

  // Set your access token
  sdk.token = "yourAccessToken"

  // Set the dataCenter, default is US
  sdk.dataCenter = jumioDataCenter

} catch (e1: PlatformNotSupportedException) {
    // Handle exceptions here
  } catch (e2: NullPointerException) {
    // Handle exceptions here
}
```

##### iOS

```
sdk = Jumio.SDK()

// Set your access token
sdk.token = "yourAccesToken"

// Set the dataCenter, default is US
sdk.dataCenter = jumioDataCenter
```

For more information on how to use the Jumio Mobile SDK please refer to our mobile guides for iOS and Android.

### API

This section illustrates how to implement the API.

After creating/updating a new account, you receive one or more specific redirect URL(s) to upload needed credentials (ID, facemap, document, selfie).

#### Request

Request Headers
The following fields are required in the header section of your Request

```
Accept: application/json
Content-Type: multipart/form-data
Content-Length: see RFC-7230
Authorization: see RFC6749
User-Agent: YourCompany YourApp/v1.0
```

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden
Request URL

Request URL
HTTP Request Method: POST

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`

Request Path Parameters

| Parameter           | Type   | Notes                                                                                          |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| accountId           | string | UUID of the account.                                                                           |
| workflowExecutionId | string | UUID of the workflow execution.                                                                |
| credentialsId       | string | UUID of the credential.                                                                        |
| classifier          | string | Defines the type of image being uploaded. Possible values: `FRONT`, `BACK`, `FACE`, `FACEMAP`. |

Request Body

| Key  | Value                                                                                           |
| ---- | ----------------------------------------------------------------------------------------------- |
| file | Supported formats: JPEG, PNG. Maximum file size: 10 MB. Maximum resolution: 8000 × 8000 pixels. |

#### Response

Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

Response Body

| Parameter                     | Type           | Notes                                                                                                                                           |
| ----------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| timestamp                     | string         | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                               |
| account                       | object         | Possible values: account.id                                                                                                                     |
| account.id                    | string         | UUID of the account                                                                                                                             |
| workflowExecution             | object         | Possible values: workflowExecution.id, workflowExecution.credentials                                                                            |
| workflowExecution.id          | string         | UUID of the workflow                                                                                                                            |
| workflowExecution.credentials | array (object) | Credential response. See workflowExecution.credentials                                                                                          |
| api                           | object         | Available actions for the API calls, actions can be omitted due to unavailability. Possible values: api.token, api.parts, api.workflowExecution |
| api.token                     | string         | JWT token for performing any action for API                                                                                                     |
| api.parts                     | object         | href to manage parts for the account credential. Possible values: FRONT, BACK, FACE, FACEMAP                                                    |
| api.workflowExecution         | string         | href to manage the acquisition and workflow processing                                                                                          |

#### Examples

```
{
    "timestamp": "2021-03-05T13:17:49.042Z",
    "account": {
        "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "workflowExecution": {
        "id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "api": {
        "token": "xxx",
        "parts": {
            "front": "https://api.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/FRONT",
            "back": "https://api.apac-1.jumio.ai/api/v1/accounts/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/BACK"
        },
        "workflowExecution": "https://api.apac-1.jumio.ai/api/v1/accounts/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}
```

When all data has been uploaded, be sure to finalize the workflow as described below.

#### Finalization

Once the user has provided their data, the workflow needs to be finalized. Finalization sends the data to Jumio for processing and cleans up the workflow. If no finalization call happens, the workflow will be cleaned up after the token or session expires (workflowExecution.status = SESSION_EXPIRED / TOKEN_EXPIRED).

HTTP Request Method: PUT

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`

##### Request Headers

The following fields are required in the header section of your Request

```
Accept: application/json
Content-Type: application/json
Content-Length: see RFC-7230
Authorization: see RFC6749
User-Agent: YourCompany YourApp/v1.0
```

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden

Request Path Parameters

| Parameter           | Type   | Note                 |
| ------------------- | ------ | -------------------- |
| accountId           | string | UUID of the account  |
| workflowExecutionId | string | UUID of the workflow |

#### Response

Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

| Parameter            | Type   | Note                                                              |
| -------------------- | ------ | ----------------------------------------------------------------- |
| timestamp            | string | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
| account              | object | Possible values: account.id                                       |
| account.id           | string | UUID of the account                                               |
| workflowExecution    | object | Possible values: workflowExectuion.id                             |
| workflowExecution.id | string | UUID of the workflow                                              |

#### Examples

Request

```
PUT
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: api.apac-1.jumio.ai
Authorization: Bearer xxx
Content-Length: 38
Content-Type: multipart/form-data;
```

Response

```
{
    "timestamp": "2021-02-25T11:55:41.347Z",
    "account": {
        "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "workflowExecution": {
        "id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}
```

### Web

This section illustrates how to implement the Web client.

#### Initiating

Use the Account Creation or Account Update API to initiate a Web workflow.

The following optional web-specific parameters can be included in the body of the initiate request.

ℹ️ You need to define a subdomain in your Customer Portal under Settings > Application Settings > Redirect > Domain Name Prefix in order to successfully generate a web.href.

##### Redirect pages

Use web.successUrl and web.errorUrl to specify how the end user will be redirected by the browser at the end of the web acquisition user journey.

If these parameters are not provided, and the values are not present in the Customer Portal settings, the end user will be shown a success or error page instead.

##### Languages

Parameter web.locale can be used to render the content of the client in the specified language.

Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country (where applicable).

| Value | Locale                     |
| ----- | -------------------------- |
| ar    | Arabic                     |
| bg    | Bulgarian                  |
| cs    | Czech                      |
| da    | Danish                     |
| de    | German                     |
| el    | Greek                      |
| en    | American English (default) |
| en-GB | British English            |
| es    | Spanish                    |
| es-MX | Mexican Spanish            |
| et    | Estonian                   |
| fi    | Finnish                    |
| fr    | French                     |
| he    | Hebrew                     |
| hr    | Croatian                   |
| hu    | Hungarian                  |
| hy    | Armenian                   |
| id    | Indonesian                 |
| it    | Italian                    |
| ja    | Japanese                   |
| ka    | Georgian                   |
| km    | Khmer                      |
| ko    | Korean                     |
| lt    | Lithuanian                 |
| ms    | Malay                      |
| nl    | Dutch                      |
| no    | Norwegian                  |
| pl    | Polish                     |
| pt    | Portuguese                 |
| pt-BR | Brazilian Portuguese       |
| ro    | Romanian                   |
| ru    | Russian                    |
| sk    | Slovak                     |
| sv    | Swedish                    |
| th    | Thai                       |
| tr    | Turkish                    |
| vi    | Vietnamese                 |
| zh-CN | Simplified Chinese         |
| zh-HK | Traditional Chinese        |

#### Displaying the Web Client

When you initiate the web client, the API returns the web.href that you use to display the web client to the end user. You can provide this URL in several ways:

Within an iFrame on your web page
As a link on your web page that opens a new browser tab or window
As a link shared securely with the end user
In a native webview

##### Embedding in an iFrame

If you want to embed ID Verification on your web page, place the iFrame tag in your HTML code where you want the client to appear. Use web.href as the value of the iFrame src attribute.

⚠️ The allow="camera" attribute must be included to enable the camera for image capture in supported browsers.
⚠️ If you are nesting the iFrame in another iFrame, the allow="camera" attribute must be added to every iFrame.
⚠️ Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
⚠️ Camera capture is only possible within an iFrame when the containing page is served securely over https.

**Width and Height**
We recommend adhering to the responsive breaking points in the table below.

| Size class | Width    | Height   |
| ---------- | -------- | -------- |
| Large      | ≥ 900 px | ≥ 710 px |
| Medium     | 640 px   | 660 px   |
| Small      | 560 px   | 600 px   |
| X-Small    | ≤ 480 px | ≤ 535 px |

When specifying the width and height of your iFrame, you may prefer to use percentage values so that the iFrame behaves responsively on your page.

⚠️ The ID Verification Web client itself will responsively fill the iFrame that it is loaded into.

**Biometric Face Capture**
⚠️ The allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen iFrame attributes must be included to enable biometric face capture in supported browsers.
⚠️ If you are nesting the iFrame in another iFrame, the allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen attribute must be added to every iFrame.
⚠️ Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
⚠️ Camera capture is only possible within an iFrame when the containing page is served securely over https.
⚠️ Biometric Face Capture is not possible within an iFrame on incognito mode.

**Example HTML**

**_Absolute sizing example_**

`<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="930" height="750" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>`

**_Responsive sizing example_**

`<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>`

**_Biometric face capture example_**

`<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>`

##### Optional iFrame logging

When the ID Verification client is embedded in an iFrame1, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success event is received).

Events include data that allows the containing page to identify which ID Verification transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the ID Verification Web client in this notification is represented as JSON in the data string property of the listener method's event argument. Parsing this JSON string results in an object with the properties described below.

All data is encoded with UTF-8.

1 This functionality is not available for instances of ID Verification running in a standalone window or tab.

##### event.data object

Required items appear in bold type.

| Property                       | Type        | Description                                                                                                                                                                   |
| ------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **accountId**                  | string      | UUID of the account                                                                                                                                                           |
| **authorizationToken**         | string      | Authorization token, valid for a specified duration                                                                                                                           |
| **workflowExecutionId**        | string      | UUID of the workflow                                                                                                                                                          |
| **customerInternalReference1** | string      | Internal reference for a request to link it in the customer backend. It must not contain Personally Identifiable Information (PII) or sensitive data such as e-mail addresses |
| **eventType**                  | integer     | Type of event that has occurred. Possible values: 510 (application state-change)                                                                                              |
| **dateTime**                   | string      | UTC timestamp of the event in the browser. Format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                                                   |
| **payload**                    | JSON object | Information specific to the event generated (see event.data.payload object)                                                                                                   |

##### event.data.payload object

Required items appear in bold type.

| Name      | Type        | Description                                                                                                                                                                          |
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **value** | string      | Possible values: loaded (ID Verification loaded in the user's browser), success (Images were accepted for verification), error (Verification could not be completed due to an error) |
| metainfo  | JSON object | Additional meta-information for error events (see metainfo object)                                                                                                                   |

##### event.data.payload.metainfo object

Required items appear in bold type.

| Property | Type    | Description                                                 |
| -------- | ------- | ----------------------------------------------------------- |
| code     | integer | Only present if payload.value = error. See errorCode values |

##### Example iFrame logging code

```
function receiveMessage(event) {
    var data = window.JSON.parse(event.data);
  console.log('ID Verification Web was loaded in an iframe.');
  console.log('auth-token:', data.authorizationToken);
  console.log('event-type:', data.eventType);
  console.log('date-time:', data.dateTime);
  console.log('workflow-execution-id:', data.workflowExecutionId);
  console.log('account-id:', data.accountId);
  console.log('customer-internal-reference:', data.customerInternalReference);
  console.log('value:', data.payload.value);
  console.log('metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);
```

**Using a Native WebView**
ID Verification Web can be embedded within a WebView in your native mobile application.

See Supported Environments > Native WebView for information about support on Android and iOS.

#### Android

This sections illustrates how to embed ID Verification Web in a native Android WebView.

##### Permissions and Settings

Make sure that the required permissions are granted.

- android.permission.INTERNET - for remote resources access
- android.permission.CAMERA - for camera capture
- android.permission.READ_EXTERNAL_STORAGE - for upload functionality
  The following settings are required for the native WebView for Android.

Enable javaScriptEnabled - tells the WebView to enable JavaScript execution

- Allow allowFileAccess - enables file access within WebView
- Allow allowFileAccessFromFileUrls - sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from other file scheme URLs
- Allow allowUniversalAccessFromFileUrls - sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin
- Allow allowContentAccess - enables content URL access within WebView
- Allow javaScriptCanOpenWindowsAutomatically - tells JavaScript to open windows automatically
- Enable domStorageEnabled - sets whether the DOM storage API is enabled
- Do not allow mediaPlaybackRequiresUserGesture - sets whether the WebView requires a user gesture to play media

##### Embedding the Required Script

To allow Jumio to identify the user runtime environment, you will need to embed a required script that sets flag **NVW_WEBVIEW** to true to interact with the webview window object. For details, see the sample code below.

##### Optional postMessage communication

You can handle messages from the ID Verification Web Client using the same method as described in Optional iFrame Logging.

You will need to register a postMessage handler and put the relevant code sections in the PostMessageHandler class as in the example below.

##### Sample code

**_AndroidManifest.xml example_**

```
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.jumio.nvw4">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    ...
</manifest>
```

**_build.gradle example_**

```
dependencies {
    implementation 'androidx.appcompat:appcompat:1.2.0-beta01'
    implementation 'androidx.webkit:webkit:1.2.0'
    ...
}
```

**_WebViewFragment.kt example_**

```
class WebviewFragment : Fragment() {

    companion object {
        var TAG: String = "NVW4"
        var PERMISSION_REQUEST_CODE: Int = 1000
        private var mUploadMessage: ValueCallback<Uri?>? = null
        var uploadMessage: ValueCallback<Array<Uri>>? = null
        const val REQUEST_SELECT_FILE = 1002
        private const val FILECHOOSER_RESULTCODE = 1003

        private var _binding: FragmentWebviewBinding? = null
        private val binding get() = _binding!!


        //Inject javascript code here that is executed after the page is loaded
        val injectFunction = """
        function () {
            window['__NVW_WEBVIEW__'] = {
            isAndroid: true
            }
        }
        """.trimIndent()

        private var mFilePathCallback: ValueCallback<Array<Uri>>? = null

        fun newInstance(url: String): WebviewFragment {
            val fragment = WebviewFragment()

            val args = Bundle()
            args.putString("url", url)
            fragment.arguments = args

            return fragment
        }
    }

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        _binding = FragmentWebviewBinding.inflate(inflater, container, false)
        return binding.root
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        WebView.setWebContentsDebuggingEnabled(true)

        binding.webview.settings.javaScriptEnabled = true
        binding.webview.settings.allowFileAccessFromFileURLs = true
        binding.webview.settings.allowFileAccess = true
        binding.webview.settings.allowContentAccess = true
        binding.webview.settings.allowUniversalAccessFromFileURLs = true
        binding.webview.settings.javaScriptCanOpenWindowsAutomatically = true
        binding.webview.settings.mediaPlaybackRequiresUserGesture = false
        binding.webview.settings.domStorageEnabled = true

        binding.webview.addJavascriptInterface(PostMessageHandler(), "__NVW_WEBVIEW_HANDLER__")

        binding.webview.webChromeClient = object : WebChromeClientFullScreen() {

            // Grant permissions for cam
            @TargetApi(Build.VERSION_CODES.M)
            override fun onPermissionRequest(request: PermissionRequest) {
                activity?.runOnUiThread {
                    if ("android.webkit.resource.VIDEO_CAPTURE" == request.resources[0]) {
                        if (ContextCompat.checkSelfPermission(
                                activity!!,
                                Manifest.permission.CAMERA
                            ) == PackageManager.PERMISSION_GRANTED
                        ) {
                            Log.d(
                                TAG,
                                String.format(
                                    "PERMISSION REQUEST %s GRANTED",
                                    request.origin.toString()
                                )
                            )
                            request.grant(request.resources)
                        } else {
                            ActivityCompat.requestPermissions(
                                activity!!,
                                arrayOf(
                                    Manifest.permission.CAMERA,
                                    Manifest.permission.READ_EXTERNAL_STORAGE
                                ),
                                PERMISSION_REQUEST_CODE
                            )
                        }
                    }
                }
            }

            // For Lollipop 5.0+ Devices
            @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
            override fun onShowFileChooser(
                mWebView: WebView?,
                filePathCallback: ValueCallback<Array<Uri>>?,
                fileChooserParams: FileChooserParams
            ): Boolean {
                if (uploadMessage != null) {
                    uploadMessage!!.onReceiveValue(null)
                    uploadMessage = null
                }
                try {
                    uploadMessage = filePathCallback
                    val intent = fileChooserParams.createIntent()
                    intent.type = "image/*"
                    try {
                        startActivityForResult(intent, REQUEST_SELECT_FILE)
                    } catch (e: ActivityNotFoundException) {
                        uploadMessage = null
                        Toast.makeText(
                            activity?.applicationContext,
                            "Cannot Open File Chooser",
                            Toast.LENGTH_LONG
                        ).show()
                        return false
                    }
                    return true
                } catch (e: ActivityNotFoundException) {
                    uploadMessage = null
                    Toast.makeText(
                        activity?.applicationContext,
                        "Cannot Open File Chooser",
                        Toast.LENGTH_LONG
                    ).show()
                    return false
                }
            }

            private fun openFileChooser(uploadMsg: ValueCallback<Uri?>) {
                mUploadMessage = uploadMsg
                val i = Intent(Intent.ACTION_GET_CONTENT)
                i.addCategory(Intent.CATEGORY_OPENABLE)
                i.type = "image/*"
                startActivityForResult(
                    Intent.createChooser(i, "File Chooser"),
                    FILECHOOSER_RESULTCODE
                )
            }

            override fun onConsoleMessage(consoleMessage: ConsoleMessage): Boolean {
                Log.d(TAG, consoleMessage.message())
                return true
            }

            override fun getDefaultVideoPoster(): Bitmap {
                return Bitmap.createBitmap(10, 10, Bitmap.Config.ARGB_8888)
            }
        }

        binding.webview.webViewClient = object : WebViewClient() {

            override fun onReceivedError(
                view: WebView?,
                errorCode: Int,
                description: String?,
                failingUrl: String?
            ) {
                Toast.makeText(activity, description, Toast.LENGTH_SHORT).show()
            }

            override fun onReceivedSslError(
                view: WebView?,
                handler: SslErrorHandler?,
                error: SslError?
            ) {
                handler?.proceed()
            }

            override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
                // Put your javascript function that you want to execute here
                binding.webview.loadUrl("javascript:($injectFunction)()")
            }
        }

        binding.webview.loadUrl(arguments?.get("url") as String)
    }

    override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            if (requestCode == REQUEST_SELECT_FILE) {
                if (uploadMessage == null)
                    return
                uploadMessage!!.onReceiveValue(
                    WebChromeClient.FileChooserParams.parseResult(
                        resultCode,
                        intent
                    )
                )
                uploadMessage = null
            }
        } else if (requestCode == FILECHOOSER_RESULTCODE) {
            if (null == mUploadMessage)
                return
            val result =
                if (intent == null || resultCode != AppCompatActivity.RESULT_OK) null else intent.data
            mUploadMessage!!.onReceiveValue(result)
            mUploadMessage = null
        } else {
            Toast.makeText(
                activity?.applicationContext,
                "Failed to Upload Image",
                Toast.LENGTH_LONG
            ).show()
        }
        super.onActivityResult(requestCode, resultCode, intent)
    }

    class PostMessageHandler {
        @JavascriptInterface
        fun postMessage(json: String?, transferList: String?): Boolean {
            /*
                There we're handling messages from NVW4 client, its the same as for iFrame logging;
                More details can be found here:
                https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
            */
            Log.d(TAG, "postMessage triggered, json: " + json.toString())
            return true
        }
    }

        /**
         * Custom WebChromClient to handle iProov full screen requirement
         * More details can be found here:
         * https://github.com/iProov/android/wiki/Java-WebView
         */
    open inner class WebChromeClientFullScreen : WebChromeClient() {
        private var customView: View? = null
        private var customViewCallback: CustomViewCallback? = null
        private var originalOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
        private var originalVisibility = View.INVISIBLE

        /**
         * Callback will tell the host application that the current page would
         * like to show a custom View in a particular orientation
         */
        override fun onShowCustomView(view: View, callback: CustomViewCallback) {
            //If we have custom view, that means that we are already in full screen, and need to go to original state
            if (customView != null) {
                onHideCustomView()
                return
            }
            //going full screen
            customView = view
            //We need to store there parameters, so we can restore app state, after we exit full screen mode
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                originalVisibility = activity?.window?.decorView?.visibility!!
                (activity?.window?.decorView as FrameLayout).addView(
                    customView,
                    FrameLayout.LayoutParams(-1, -1)
                )
                activity?.window?.setDecorFitsSystemWindows(false)
            } else {
                originalVisibility = activity?.window?.decorView?.windowSystemUiVisibility!!
                (activity?.window?.decorView as FrameLayout).addView(
                    customView,
                    FrameLayout.LayoutParams(-1, -1)
                )
                activity?.window?.decorView?.systemUiVisibility =
                    3846 or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
            }
            originalOrientation = activity?.requestedOrientation!!
        }

        /**
         * Callback will tell the host application that the current page exited full screen mode,
         * and the app has to hide custom view.
         */
        override fun onHideCustomView() {
            (activity?.window?.decorView as FrameLayout).removeView(
                customView
            )
            customView = null
            //Restoring app state, as it was before we go to full screen
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                activity?.window?.setDecorFitsSystemWindows(true)
            } else {
                activity?.window?.decorView?.systemUiVisibility = originalVisibility
            }
            activity?.requestedOrientation = originalOrientation
            if (customViewCallback != null) customViewCallback!!.onCustomViewHidden()
            customViewCallback = null
        }
    }

```

##### Use of iProov

Please be aware that if iProov is included in your workflow, it is necessary to extend WebChromeClient class to implement a custom view, in order to handle certain iProov full screen requirements.

See WebViewFragment.kt code sample above, specifically WebChromeClientFullScreen inner class.

**Sample App**

Check out our Sample App for the Native Android WebView

##### iOS

Jumio supports two types of webview for iOS:

**Safari WebView**
| Pros | Cons |
| ------------------------------------------- | ------------------------------------- |
| Access to the camera during ID and Identity | No optional postMessage communication |
| Fewer integration steps | Fewer options for troubleshooting |

**Native iOS WebView**
| Pros | Cons |
| ---------------------------------- | ------------------------------------------- |
| Optional postMessage communication | Image upload only (no access to the camera) |
| Better options for troubleshooting | More integration steps |

Safari WebView
This section illustrates how to embed ID Verification Web in a Safari View Controller.

Permissions and Settings
Make sure that camera permissions are granted.

Sample code
ViewController.swift example

```
import AVFoundation
import SafariServices
import UIKit
​
class ViewController: UIViewController {

    @IBAction func loadButton(_ sender: Any) {
        checkCameraPermission()
        let url: String = "https://www.jumio.com/"
        showSafariVC(inputText)
    }

    // present SFSafariViewController
    private func showSafariVC(_ stringURL: String) {
        guard let URL = URL(string: stringURL) else {
            return
        }
​
        let safariVC = SFSafariViewController(url: URL)
        present(safariVC, animated: true)
    }

    func safariViewControllerDidFinish(_ safariVC: SFSafariViewController) {
        safariVC.dismiss(animated: true, completion: nil)
    }

    // ask for camera permissions
    func checkCameraPermission() {
        AVCaptureDevice.requestAccess(for: .video) { (granted) in
            if !granted {
                print("Camera permission denied")
            }
        }
    }
}
```

##### Sample App

Check out our Sample App for the iOS Safari WebView

##### Native iOS WebView

This section illustrates how to embed ID Verification Web in a native iOS WebView.

##### Permissions and Settings

No specific permissions are needed as we cannot access the camera due to native WebView limitations for iOS.

##### Embedding the Required Script

To allow Jumio to identify the user runtime environment, you will need to embed a required script that sets flag **NVW_WEBVIEW** to true to interact with the webview window object. For details, see the sample code below.

##### Optional postMessage communication

You can handle messages from the ID Verification Web Client using the same method as described in Optional iFrame Logging.

Register a postMessage handler and put the relevant code sections in the userContentController function as shown below.

##### Sample code

ViewController.swift example

```
class ViewController: UIViewController {
    @IBOutlet weak var webView: WKWebView!
​
    override func viewDidLoad() {
        super.viewDidLoad()
        webView.navigationDelegate = self;
​
        /**
         *  Registering handler for postMessage communication (iFrame logging equivalent - optional)
         */
        webView.configuration.userContentController.add(self, name: "__NVW_WEBVIEW_HANDLER__")
​
        webView.load( URLRequest("<<NVW4 SCAN REF LINK>>"));
    }
}
​
extension ViewController: WKNavigationDelegate {
    /**
     *  Embedding script at very beginning, before NVW4 initialize (important)
     */
    func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) {
        /**
         *  Necessary integration step - embedding script
         */
        self.webView?.evaluteJavaScript("(function() { window['__NVW_WEBVIEW__'] = true })()") { _, error in
            if let error = error {
                print("ERROR while evaluating javascript \(error)") // error handling whenever executing script fails
            }
            print("executed injected javascript")
        };
    }
}
​
extension ViewController: WKScriptMessageHandler {
    /**
     *  PostMessage handler for iframe logging equivalent (optional)
     */
    func userContentController(_ userController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "__NVW_WEBVIEW_HANDLER__", let messageBody = message.body as? String {
            /*
    *  See iFrame logging:
    *  https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
            */
        }
    }
}
```

Sample App
Check out our [Sample App for the Native iOS WebView](https://github.com/Jumio/mobile-webview/tree/master/ios/WebView-Pilot)

#### After the User Journey

At the end of the web acquisition user journey, the following query parameters are appended by the web client to the success or error URL before the end user is redirected by the browser.
**_Required items appear in bold type._**

| Name                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **accountId**                 | UUID of the account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **workflowExecutionId**       | UUID of the workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **acquisitionStatus**         | Possible values: SUCCESS, ERROR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **customerInternalReference** | Customer internal reference for a request to link it in the customer backend                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| errorCode                     | Predefined list of error codes, only appended to errorUrl when acquisitionStatus is ERROR. Possible values: 9100 (Error occurred on our server), 9200 (Authorization token missing, invalid, or expired), 9210 (Session expired after the user journey started), 9300 (Error occurred transmitting image to our server), 9400 (Error occurred during verification step), 9800 (User has no network connection), 9801 (Unexpected error occurred in the client), 9810 (Problem while communicating with our server), 9820 (File upload not enabled and camera unavailable), 9821 (The biometric face capture process failed, e.g. issue with iProov), 9822 (Browser does not support camera), 9835 (No acceptable submission in 3 attempts), 9836 (Authentication Failure) |

#### Supported Environments

Jumio offers guaranteed support for ID Verification on the following browsers and the latest major version of each operating system.

##### Desktop

| Browser         | Major version        | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
| --------------- | -------------------- | ---------------- | --------------------- | ----------------------- | ------------------------------- |
| Google Chrome   | current + 1 previous | Windows + Mac    | X                     | X                       | X                               |
| Mozilla Firefox | current + 1 previous | Windows + Mac    | X                     | X                       | X                               |
| Apple Safari    | current              | Mac              | X                     | X                       | X                               |
| Microsoft Edge  | current              | Windows          | X                     | X                       | X                               |

##### Mobile

| Browser name     | Major browser version | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
| ---------------- | --------------------- | ---------------- | --------------------- | ----------------------- | ------------------------------- |
| Google Chrome    | current               | Android          | X                     | X                       | X                               |
| Samsung Internet | current               | Android          | X                     | X                       | X                               |
| Apple Safari     | current               | iOS              | X                     | X                       | X¹                              |

1Fullscreen functionality during capture only supported for iPads. iPhone process works, but fullscreen is limited and capture may be less accurate.

##### Native WebView

| Operating system       | Major version        | Supports image upload | Supports camera capture | Supports biometric face capture |
| ---------------------- | -------------------- | --------------------- | ----------------------- | ------------------------------- |
| Native Android WebView | current + 1 previous | X                     | X                       | X                               |
| Native iOS WebView¹    | current + 1 previous | X                     |                         |                                 |
| iOS Safari WebView     | current + 1 previous | X                     | X                       | X                               |

1If you are using a native WebView for iOS you will need to enable image upload to allow the end user to finish the user journey.

### Callback

The callback is the authoritative answer from Jumio. Specify a callback URL (for constraints see Configuring Settings in the Customer Portal) to automatically receive the result for each transaction.

To specify a global callback URL in the Customer Portal, see Configuring Settings in the Customer Portal.

A callback URL can also be specified per account, see instructions in sections Account Creation and Account Update.

#### Best Practices

Use callbacks to check if a workflow has finished processing.
Once Jumio has sent the callback, save it on your side and send back a 200 OK response.
Afterwards, to retrieve transaction details or images, use the Retrieval API.

#### Jumio Callback IP Addresses

Allowlist the following IP addresses for callbacks, and use them to verify that the callback originated from Jumio.

US Data Center:

34.202.241.227
34.226.103.119
34.226.254.127
52.52.51.178
52.53.95.123
54.67.101.173
Use the hostname callback.jumio.com to look up the most current IP addresses.

EU Data Center:

34.253.41.236
35.157.27.193
52.48.0.25
52.57.194.92
52.58.113.86
52.209.180.134
Use the hostname callback.lon.jumio.com to look up the most current IP addresses.

SGP Data Center:

3.0.109.121
52.76.184.73
52.77.102.92
Use the hostname callback.core-sgp.jumio.com to look up the most current IP addresses.

#### Callback Parameters

An HTTP POST request is sent to your specified callback URL containing an application/json formatted string with the transaction result.

| Parameter                       | Type   | Notes                                                             |
| ------------------------------- | ------ | ----------------------------------------------------------------- |
| callbackSentAt                  | string | Timestamp of the callback in the format: YYYY-MM-DDThh:mm:ss.SSSZ |
| userReference                   | string | User reference (if set in initiate call)                          |
| workflowExecution               | object | Possible values: workflowExecution.id, workflowExecution.href     |
| workflowExecution.id            | string | UUID of the workflow                                              |
| workflowExecution.href          | sting  | URL to retrieve workflow details                                  |
| workflowExecution.definitionKey | string | Key of the workflow definition you executed. See supported keys   |
| workflowExecution.status        | string | Possible values: PROCESSED, SESSION_EXPIRED, TOKEN_EXPIRED        |
| account                         | object | Possible values: account.id, account.href                         |
| account.id                      |        | UUID of the account                                               |
| account.href                    |        | URL to retrieve account details                                   |

Examples

```
{
  "callbackSentAt":"2021-01-21T14:55:01.917Z",
  "workflowExecution":{
    "id":"22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "definitionKey":"3",
    "status":"PROCESSED"
},
  "account":{
    "id":"11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}
```

### Retrieval

The Retrieval API allows you to get information from a transaction, including the transaction status, workflow details, and images.

#### Best Practices

Before retrieving transaction data, make sure the transaction is complete.
Waiting for the callback using the Callback API is recommended.
Alternatively, transaction status can also be retrieved using the Retrieval Status API.
If the transaction status is PROCESSED, retrieve details and image(s) once. If the transaction status is SESSION_EXPIRED or TOKEN_EXPIRED, the transaction has been unsuccessful.
Maximum of 10 consecutive retrieval attempts after successful image acquisition.
Request timings recommendations:
40, 60, 100, 160, 240, 340, 460, 600, 760, 940 seconds
You are also allowed to set your own definition.

#### Request

Request Headers
The following fields are required in the header section of your request:

Accept: application/json
Content-Type: application/json
Content-Length: see RFC-7230
Authorization: see RFC6749
User-Agent: YourCompany YourApp/v1.0

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden

#### Available Retrieval APIs

This section describes the Retrieval APIs: Status, Workflow Details, and Images.

##### Get Status

HTTP Request Method: GET

`US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status`
`EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status`
`SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status`

**Status Request Path Parameters**

| Parameter           | Type   | Note                 |
| ------------------- | ------ | -------------------- |
| accountId           | string | UUID of the account  |
| workflowExecutionId | string | UUID of the workflow |

**Status Response**

Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

| Parameter                       | Type   | Note                                                                                                                     |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| account                         | object | Possible values: account.id, account.href                                                                                |
| account.id                      | string | UUID of the account                                                                                                      |
| account.href                    | string | URL to retrieve account details                                                                                          |
| workflowExecution               | object | Possible values: workflowExecution.id, workflowExecution.href, workflowExecution.definitionKey, workflowExecution.status |
| workflowExecution.id            | string | UUID of the workflow                                                                                                     |
| workflowExecution.href          | string | URL to retrieve workflow details                                                                                         |
| workflowExecution.definitionKey | string | Key of the workflow definition which you executed. See supported keys                                                    |
| workflowExecution.status        | string | Possible values: INITIATED, ACQUIRED, PROCESSED, SESSION_EXPIRED, TOKEN_EXPIRED                                          |

#### Examples

```
{
    "account": {
        "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "href": "https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "workflowExecution": {
        "id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "href": "https://retrieval.apac-1.jumio.ai/api/v1/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "definitionKey": "2",
        "status": "PROCESSED"
    }
}
```

#### Get Workflow Details

HTTP Request Method: GET

`US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`

**Workflow Request Path Parameters**

| Parameter           | Type   | Note                 |
| ------------------- | ------ | -------------------- |
| accountId           | string | UUID of the account  |
| workflowExecutionId | string | UUID of the workflow |

**Workflow Execution Response**
Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

| Parameter                          | Type           | Note                                                                                                                              |
| ---------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| createdAt                          | string         | Timestamp (UTC) of the creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                 |
| startedAt                          | string         | Timestamp (UTC) of the start. Format: YYYY-MM-DDThh:mm:ss.SSSZ                                                                    |
| completedAt                        | string         | Timestamp (UTC) of the completion. Format: YYYY-MM-DDThh:mm:ss.SSSZ                                                               |
| account                            | object         | Possible values: account.id                                                                                                       |
| account.id                         | string         | UUID of the account                                                                                                               |
| workflow                           | object         | Possible values: workflow.id, workflow.status, workflow.definitionKey, workflow.userReference, workflow.customerInternalReference |
| workflow.id                        | string         | UUID of the workflow                                                                                                              |
| workflow.status                    | string         | Possible values: INITIATED, ACQUIRED, PROCESSED, SESSION_EXPIRED, TOKEN_EXPIRED                                                   |
| workflow.definitionKey             | string         | See supported keys                                                                                                                |
| workflow.userReference             | string         | Customer internal reference for a request to link it in the customer backend (must not contain any PII)                           |
| workflow.customerInternalReference | string         | Reference for the end user in the customer backend (must not contain any PII)                                                     |
| credentials                        | array (object) | See credentials                                                                                                                   |
| capabilities                       | object         | See capabilities                                                                                                                  |

**credentials**

| Parameter        | Type   | Note                                             |
| ---------------- | ------ | ------------------------------------------------ |
| id               | string | UUID of the credentials                          |
| category         | string | ID                                               |
| parts            | object | Possible values: parts.classifier, parts.href    |
| parts.classifier | string | Possible values: FRONT, BACK, FACE               |
| parts.href       | string | href to manage parts for the account credentials |

**capabilities**
Since workflow execution consists of a chain of multiple capability executions (usability, extraction, liveness, ...), some have dependencies between them and need the result of previous executions.

This means that some capabilities should not be executed if any of the previous capabilities were not successful because they were REJECTED or NOT_EXECUTED. If, for example, usability has passed, but imageChecks got rejected with the reason DIGITAL_COPY, the consequent extraction and dataChecks cannot be executed because of PRECONDITION_NOT_FULFILLED. The precondition in this case would be to successfully pass imageChecks.

##### Capability execution dependencies

usability --> imageChecks --> extraction --> dataChecks
usability --> liveness
usability --> similarity
usability --> authentication
usability --> imageChecks --> extraction --> watchlistScreening
usability --> imageChecks --> extraction --> addressValidation
usability --> imageChecks --> extraction --> proofOfResidency
usability --> imageChecks --> extraction --> drivingLicenseVerification

| Parameter                  | Type           | Note                           | Dependency                         |
| -------------------------- | -------------- | ------------------------------ | ---------------------------------- |
| usability                  | array (object) | See usability                  | none                               |
| liveness                   | array (object) | See liveness                   | usability                          |
| similarity                 | array (object) | See similarity                 | usability                          |
| authentication             | array (object) | See authentication             | usability                          |
| imageChecks                | array (object) | See imageChecks                | usability                          |
| extraction                 | array (object) | See extraction                 | usability, imageChecks             |
| dataChecks                 | array (object) | See dataChecks                 | usability, imageChecks, extraction |
| watchlistScreening         | array (object) | See watchlistScreening         | usability, imageChecks, extraction |
| addressValidation          | array (object) | See addressValidation          | usability, imageChecks, extraction |
| proofOfResidency           | array (object) | See proofOfResidency           | usability, imageChecks, extraction |
| drivingLicenseVerification | array (object) | See drivingLicenseVerification | usability, imageChecks, extraction |

##### capabilities.usability

**Dependency: none**

| Parameter              | Type   | Note                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| credentials            | object |                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| credentials.id         | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| credentials.category   | string | Possible values: ID, FACEMAP, DOCUMENT, SELFIE                                                                                                                                                                                                                                                                                                                                                                                                                   |
| decision               | object |                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| decision.type          | string | Possible values: NOT_EXECUTED, PASSED, REJECTED, WARNING                                                                                                                                                                                                                                                                                                                                                                                                         |
| decision.details       | object |                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| decision.details.label | string | if decision.type = NOT_EXECUTED: TECHNICAL_ERROR, NOT_UPLOADED. if decision.type = PASSED: OK. if decision.type = REJECTED: BAD_QUALITY, BLURRED1, BAD_QUALITY_IMAGE1, PART_OF_DOCUMENT_MISSING1, PART_OF_DOCUMENT_HIDDEN1, DAMAGED_DOCUMENT1, GLARE1, MISSING_MANDATORY_DATAPOINTS1, BLACK_WHITE, MISSING_PAGE, MISSING_SIGNATURE, NOT_A_DOCUMENT, PHOTOCOPY. if decision.type = WARNING: LIVENESS_UNDETERMINED, UNSUPPORTED_COUNTRY, UNSUPPORTED_DOCUMENT_TYPE |

. 1 Will be added in the week of January 30, 2023.

##### capabilities.similarity

**Dependency:usability**

| Parameter                     | Type    | Note                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                            | string  | UUID of the capability                                                                                                                                                                                                                                                                                                                                    |
| credentials                   | object  |                                                                                                                                                                                                                                                                                                                                                           |
| credentials.id                | string  | UUID of the credentials                                                                                                                                                                                                                                                                                                                                   |
| credentials.category          | string  | Possible values: ID, FACEMAP, DOCUMENT, SELFIE                                                                                                                                                                                                                                                                                                            |
| decision                      | object  |                                                                                                                                                                                                                                                                                                                                                           |
| decision.type                 | string  | Possible values: NOT_EXECUTED, PASSED, REJECTED, WARNING                                                                                                                                                                                                                                                                                                  |
| decision.details              | object  |                                                                                                                                                                                                                                                                                                                                                           |
| decision.details.label        | string  | If decision.type = REJECTED: LIVENESS_UNDETERMINED, ID_USED_AS_SELFIE, MULTIPLE_PEOPLE, DIGITAL_COPY, PHOTOCOPY, MANIPULATED, NO_FACE_PRESENT, FACE_NOT_FULLY_VISIBLE, BLACK_WHITE. If decision.type = PASSED: OK. If decision.type = WARNING: AGE_DIFFERENCE, BAD_QUALITY. If decision.type = NOT_EXECUTED: PRECONDITION_NOT_FULFILLED, TECHNICAL_ERROR. |
| data                          | object  |                                                                                                                                                                                                                                                                                                                                                           |
| data.type                     | string  | Possible values: IPROOV_STANDARD (Web + SDK channel only), IPROOV_PREMIUM (Workflow 3: ID and Identity Verification – Web + SDK channel only; Workflow 9: Authentication – SDK only; Workflow 16: Authentication on Premise – SDK only), JUMIO_STANDARD                                                                                                   |
| data.predictedAge             | integer | Predicted age according to the selfie. Example: 28                                                                                                                                                                                                                                                                                                        |
| data.ageConfidenceRange       | string  | Age range we are confident the selfie age is within. Example: 25-34                                                                                                                                                                                                                                                                                       |
| validFaceMapForAuthentication | string  | Href to manage facemap                                                                                                                                                                                                                                                                                                                                    |

##### capabilities.authentication

**Dependency:usability**

| Parameter                     | Type    | Note                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                            | string  | UUID of the capability                                                                                                                                                                                                                                                                                                                                    |
| credentials                   | object  |                                                                                                                                                                                                                                                                                                                                                           |
| credentials.id                | string  | UUID of the credentials                                                                                                                                                                                                                                                                                                                                   |
| credentials.category          | string  | Possible values: ID, FACEMAP, DOCUMENT, SELFIE                                                                                                                                                                                                                                                                                                            |
| decision                      | object  |                                                                                                                                                                                                                                                                                                                                                           |
| decision.type                 | string  | Possible values: NOT_EXECUTED, PASSED, REJECTED, WARNING                                                                                                                                                                                                                                                                                                  |
| decision.details              | object  |                                                                                                                                                                                                                                                                                                                                                           |
| decision.details.label        | string  | If decision.type = REJECTED: LIVENESS_UNDETERMINED, ID_USED_AS_SELFIE, MULTIPLE_PEOPLE, DIGITAL_COPY, PHOTOCOPY, MANIPULATED, NO_FACE_PRESENT, FACE_NOT_FULLY_VISIBLE, BLACK_WHITE. If decision.type = PASSED: OK. If decision.type = WARNING: AGE_DIFFERENCE, BAD_QUALITY. If decision.type = NOT_EXECUTED: PRECONDITION_NOT_FULFILLED, TECHNICAL_ERROR. |
| data                          | object  |                                                                                                                                                                                                                                                                                                                                                           |
| data.type                     | string  | Possible values: IPROOV_STANDARD (Web + SDK channel only), IPROOV_PREMIUM (Workflow 3: ID and Identity Verification – Web + SDK channel only; Workflow 9: Authentication – SDK only; Workflow 16: Authentication on Premise – SDK only), JUMIO_STANDARD                                                                                                   |
| data.predictedAge             | integer | Predicted age according to the selfie. Example: 28                                                                                                                                                                                                                                                                                                        |
| data.ageConfidenceRange       | string  | Age range we are confident the selfie age is within. Example: 25-34                                                                                                                                                                                                                                                                                       |
| validFaceMapForAuthentication | string  | Href to manage facemap                                                                                                                                                                                                                                                                                                                                    |

##### capabilities.imageChecks

**Dependency:usability**

| Parameter                | Type   | Description                                                                                 |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------- |
| `id`                     | string | UUID of the capability.                                                                     |
| `credentials`            | object | Information about the credentials used for this capability.                                 |
| `credentials.id`         | string | UUID of the credentials.                                                                    |
| `credentials.category`   | string | Category of the credential. Possible values: `ID`, `FACEMAP`, `DOCUMENT`, `SELFIE`.         |
| `decision`               | object | Contains the result of the capability evaluation.                                           |
| `decision.type`          | string | Overall decision outcome. Possible values: `NOT_EXECUTED`, `PASSED`, `REJECTED`, `WARNING`. |
| `decision.details`       | object | Provides additional details about the decision.                                             |
| `decision.details.label` | string | Detailed decision reason based on `decision.type` (see below).                              |
| `data`                   | object | Additional capability-specific data. See `imageChecks.data` for structure.                  |

---

**Decision Details Mapping**

If `decision.type = NOT_EXECUTED`

Possible `decision.details.label` values:

- `PRECONDITION_NOT_FULFILLED`
- `TECHNICAL_ERROR`

---

If `decision.type = PASSED`

- `OK`

---

If `decision.type = REJECTED`

- `DIGITAL_COPY`
- `WATERMARK`
- `MANIPULATED_DOCUMENT`
- `MANIPULATED_DOCUMENT_PHOTO1`
- `MANIPULATED_DOCUMENT_EXPIRY1`
- `MANIPULATED_DOCUMENT_NAME1`
- `MANIPULATED_DOCUMENT_ADDRESS1`
- `MANIPULATED_DOCUMENT_SECURITY_CHECKS1`
- `MANIPULATED_DOCUMENT_SIGNATURE1`
- `MANIPULATED_DOCUMENT_PERSONAL_NUMBER1`
- `MANIPULATED_DOCUMENT_PLACE_OF_BIRTH1`
- `MANIPULATED_DOCUMENT_GENDER1`
- `MANIPULATED_DOCUMENT_ISSUING_DATE1`
- `OTHER_REJECTION`
- `GHOST_IMAGE_DIFFERENT`
- `PUNCHED`
- `SAMPLE`
- `FAKE`
- `CHIP_MISSING`
- `DIGITAL_MANIPULATION`
- `MISMATCH_FRONT_BACK`

---

If `decision.type = WARNING`

- `DIFFERENT_PERSON`
- `REPEATED_FACE`
  _(Same face with same data occurs multiple times — potential opening of multiple accounts.)_

. 1 Will be added in the week of January 30, 2023.

##### capabilities.imageChecks.data

| Parameter                          | Type           | Description                                                                                                    |
| ---------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| data.faceSearchFindings            | object         | Result of the 1:N face search performed against faces from previous transactions.                              |
| data.faceSearchFindings.status     | string         | Status of the face search execution. Possible values: DONE, PENDING, ERROR.                                    |
| data.faceSearchFindings.findings   | array (string) | List of workflow IDs where a face (from the ID document or Selfie) matches a face from a previous transaction. |
| data.faceSearchFindings.findings[] | string         | UUID of the matching workflow.                                                                                 |

##### capabilities.extraction

**Dependencies:usability, imageChecks**

| Parameter              | Type   | Description                                                                                                                                          |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability.                                                                                                                              |
| credentials            | object | Credential information related to the capability execution.                                                                                          |
| credentials.id         | string | UUID of the credentials.                                                                                                                             |
| credentials.category   | string | Type of credential used. Possible values: ID, FACEMAP, DOCUMENT, SELFIE.                                                                             |
| decision               | object | Result of the capability evaluation.                                                                                                                 |
| decision.type          | string | Overall decision outcome. Possible values: NOT_EXECUTED, PASSED.                                                                                     |
| decision.details       | object | Additional information about the decision outcome.                                                                                                   |
| decision.details.label | string | Detailed decision label. <br/><br/>If decision.type = NOT_EXECUTED: PRECONDITION_NOT_FULFILLED, TECHNICAL_ERROR. <br/>If decision.type = PASSED: OK. |
| data                   | object | Contains capability-specific result data. See extraction.data section for details.                                                                   |

##### capabilities.extraction.data

| Parameter                         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data.type                         | string  | Document type. Possible values:<ul><li>PASSPORT</li><li>DRIVING_LICENSE</li><li>ID_CARD</li><li>VISA</li><li>UNSUPPORTED</li></ul>                                                                                                                                                                                                                                                                                                                                                                                               |
| data.subType                      | string  | Document subtype.<ul><li>If data.type = ID_CARD:<ul><li>NATIONAL_ID</li><li>CONSULAR_ID</li><li>ELECTORAL_ID</li><li>RESIDENT_PERMIT_ID</li><li>TAX_ID</li><li>STUDENT_ID</li><li>PASSPORT_CARD_ID</li><li>MILITARY_ID</li><li>PUBLIC_SAFETY_ID</li><li>HEALTH_ID</li><li>OTHER_ID</li><li>VISA</li><li>UNKNOWN</li></ul></li><li>If data.type = DRIVING_LICENSE:<ul><li>REGULAR_DRIVING_LICENSE</li><li>LEARNING_DRIVING_LICENSE</li></ul></li><li>If data.type = PASSPORT:<ul><li>E_PASSPORT (mobile only)</li></ul></li></ul> |
| data.issuingCountry               | string  | Country code in ISO 3166-1 alpha-3 format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| data.firstName                    | string  | First name as shown on the ID (if enabled), otherwise as provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| data.lastName                     | string  | Last name as shown on the ID (if enabled), otherwise as provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| data.dateOfBirth                  | string  | Date of birth in format YYYY-MM-DD (if enabled), otherwise as provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| data.expiryDate                   | string  | Expiry date in format YYYY-MM-DD (if enabled), otherwise as provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| data.issuingDate                  | string  | Issuing date in format YYYY-MM-DD (if enabled), otherwise as provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| data.state                        | string  | State or region code.<ul><li>US: last two characters of ISO 3166-2</li><li>AU: last 2–3 characters of ISO 3166-2</li><li>CA: last two characters of ISO 3166-2</li><li>ISO 3166-1 country name</li><li>XKX (Kosovo)</li><li>Free text if mapping is not possible</li></ul>                                                                                                                                                                                                                                                       |
| data.personalNumber               | string  | Personal number (if type = PASSPORT and available). Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| data.optionalMrzField1            | string  | Optional MRZ field (line 1).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data.optionalMrzField2            | string  | Optional MRZ field (line 2).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data.address                      | object  | Extracted address information. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.issuingAuthority             | string  | Issuing authority of the document. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| data.issuingPlace                 | string  | Issuing place of the document. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.curp                         | string  | CURP (Mexico). Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.gender                       | string  | Gender. Possible values:<ul><li>M</li><li>F</li><li>X</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| data.nationality                  | string  | Nationality (ISO 3166-1 alpha-3). Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| data.placeOfBirth                 | string  | Place of birth of the document holder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| data.taxNumber                    | string  | Tax number.<ul><li>If country = ITA and subtype = HEALTH_ID or TAX_ID. Also known as `fiscalNumber` in Italy.</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                              |
| data.cpf                          | string  | CPF number. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| data.registrationNumber           | string  | Registration number. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| data.mothersName                  | string  | Mother’s name. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.fathersName                  | string  | Father’s name. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.personalIdentificationNumber | string  | Personal identification number. Activation required.<ul><li>GEO + PASSPORT</li><li>COL + ID_CARD</li><li>LTU + DRIVING_LICENSE</li><li>TUR + ID_CARD, DRIVING_LICENSE</li><li>ROU + ID_CARD, DRIVING_LICENSE</li></ul>                                                                                                                                                                                                                                                                                                           |
| data.rgNumber                     | string  | “General Registration” number.<ul><li>If country = BRA</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data.dlCategories                 | array   | Driving license categories.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| data.voterIdNumber                | string  | Voter ID number.<ul><li>If country = MEX</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| data.issuingNumber                | string  | Issuing number.<ul><li>If country = MEX</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| data.passportNumber               | string  | Passport number.<ul><li>If type = VISA</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data.durationOfStay               | string  | Duration of stay.<ul><li>If type = VISA</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| data.numberOfEntries              | string  | Number of entries.<ul><li>If type = VISA</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| data.visaCategory                 | string  | Visa category.<ul><li>If type = VISA</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| data.dni                          | string  | DNI number.<ul><li>If country = ESP and subtype = NATIONAL_ID</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                              |
| data.pesel                        | string  | PESEL number.<ul><li>If country = POL</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| data.expiryDateParts              | object  | Structured expiry date.<ul><li>year (YYYY)</li><li>month (MM)</li><li>day (DD)</li></ul>Example: `{"year":"2022","month":"08","day":"31"}`                                                                                                                                                                                                                                                                                                                                                                                       |
| data.dateOfBirthParts             | object  | Structured date of birth.<ul><li>year (YYYY)</li><li>month (MM)</li><li>day (DD)</li></ul>Example: `{"year":"2022","month":"08","day":"31"}`                                                                                                                                                                                                                                                                                                                                                                                     |
| data.issuingDateParts             | object  | Structured issuing date.<ul><li>year (YYYY)</li><li>month (MM)</li><li>day (DD)</li></ul>Example: `{"year":"2022","month":"08","day":"31"} `                                                                                                                                                                                                                                                                                                                                                                                     |
| data.laborIdentificationNumber    | string  | CUIL number.<ul><li>If country = ARG</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| data.documentCopy                 | string  | Ejemplar number.<ul><li>If country = ARG</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| data.residentPermitType           | string  | Permit type related to “Golden Visas”.<ul><li>If country = GBR</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                             |
| data.residentPermitRemarks        | string  | Permit remarks related to “Golden Visas”.<ul><li>If country = GBR</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                          |
| data.documentIdentificationNumber | string  | Document Identification Number. Activation required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| data.citizenship                  | string  | Citizenship.<ul><li>If country = IDN</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| data.maritalStatus                | string  | Marital status.<ul><li>If country = IDN</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| data.religion                     | string  | Religion.<ul><li>If country = IDN, MYS</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data.currentAge                   | integer | Calculated age (current date − extracted date of birth). Example: 30.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| data.lastNameAtBirth              | string  | Last name at birth.<ul><li>If country = SLO</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| data.remarks                      | string  | Special remarks or titles.<ul><li>If country = SLO</li><li>Example: "Mgr"</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                  |
| data.disability                   | string  | Indicates whether at least one disability icon is present.<ul><li>If country = BHR</li><li>Possible values: YES, NO</li><li>Activation required</li></ul>                                                                                                                                                                                                                                                                                                                                                                        |

1 If one of the values such as "day" is not included in the document it will also not be returned in the object. For examples and additional details, refer to our Knowledge Base.

##### capabilities.extraction.data.address

| Parameter        | Type   | Description                                                                         |
| ---------------- | ------ | ----------------------------------------------------------------------------------- |
| line1            | string | Line item 1.                                                                        |
| line2            | string | Line item 2.                                                                        |
| line3            | string | Line item 3.                                                                        |
| line4            | string | Line item 4.                                                                        |
| line5            | string | Line item 5.                                                                        |
| country          | string | Country code.<ul><li>ISO 3166-1 alpha-3 country code</li><li>XKX (Kosovo)</li></ul> |
| postalCode       | string | Postal code.                                                                        |
| subdivision      | string | Subdivision (Region, State, Province, Emirate, Department, etc.).                   |
| city             | string | City.                                                                               |
| formattedAddress | string | Complete formatted address.                                                         |

##### capabilities.dataChecks

**Dependencies:usability, imageChecks, extraction**

| Parameter              | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| credentials            | object | Credential information related to the capability execution.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| credentials.id         | string | UUID of the credentials.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| credentials.category   | string | Credential category.<ul><li>ID</li><li>FACEMAP</li><li>DOCUMENT</li><li>SELFIE</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                       |
| decision               | object | Result of the capability evaluation.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| decision.type          | string | Overall decision outcome.<ul><li>NOT_EXECUTED</li><li>PASSED</li><li>REJECTED</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                        |
| decision.details       | object | Additional information about the decision outcome.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| decision.details.label | string | Detailed decision label.<ul><li>If decision.type = NOT_EXECUTED:<ul><li>PRECONDITION_NOT_FULFILLED</li><li>TECHNICAL_ERROR</li></ul></li><li>If decision.type = PASSED:<ul><li>OK</li></ul></li><li>If decision.type = REJECTED:<ul><li>NFC_CERTIFICATE</li><li>MISMATCHING_DATAPOINTS</li><li>MRZ_CHECKSUM</li><li>MISMATCHING_DATA_REPEATED_FACE (same face occurs multiple times with different data – high possibility of fraud attempt)</li><li>MISMATCH_HRZ_MRZ_DATA</li></ul></li></ul> |

##### capabilities.watchlistScreening

**Dependencies:usability, imageChecks, extraction**

| Parameter              | Type   | Description                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability                                                                                                                                                                                                                                                                                                                                                                  |
| credentials            | object | Credential information                                                                                                                                                                                                                                                                                                                                                                  |
| credentials.id         | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                                                                 |
| credentials.category   | string | Possible values:<ul><li>ID</li><li>FACEMAP</li><li>DOCUMENT</li><li>SELFIE</li></ul>                                                                                                                                                                                                                                                                                                    |
| decision               | object | Decision result                                                                                                                                                                                                                                                                                                                                                                         |
| decision.type          | string | Possible values:<ul><li>NOT_EXECUTED</li><li>PASSED</li><li>WARNING</li></ul>                                                                                                                                                                                                                                                                                                           |
| decision.details       | object | Additional decision details                                                                                                                                                                                                                                                                                                                                                             |
| decision.details.label | string | <ul><li>If decision.type = NOT_EXECUTED:<ul><li>NOT_ENOUGH_DATA</li><li>VALIDATION_FAILED</li><li>INVALID_MERCHANT_SETTINGS</li><li>TECHNICAL_ERROR</li><li>EXTRACTION_NOT_DONE</li><li>NO_VALID_ID_CREDENTIAL</li><li>PRECONDITION_NOT_FULFILLED</li></ul></li><li>If decision.type = PASSED:<ul><li>OK</li></ul></li><li>If decision.type = WARNING:<ul><li>ALERT</li></ul></li></ul> |
| data                   | object | See watchlistScreening.data                                                                                                                                                                                                                                                                                                                                                             |

##### capabilities.watchlistScreening.data

**Dependencies:usability, imageChecks, extraction**

| Parameter       | Type    | Description                                                                        |
| --------------- | ------- | ---------------------------------------------------------------------------------- |
| searchDate      | string  | Timestamp (UTC) of the response.<ul><li>Format: YYYY-MM-DDThh:mm:ss.SSSZ</li></ul> |
| searchStatus    | string  | Possible values:<ul><li>DONE</li><li>NOT_DONE</li><li>ERROR</li></ul>              |
| searchId        | string  | Returned only if searchStatus = DONE                                               |
| searchReference | string  | Returned only if searchStatus = DONE                                               |
| searchResultUrl | string  | Returned only if searchStatus = DONE                                               |
| searchResults   | integer | Returned only if searchStatus = DONE                                               |

##### capabilities.addressValidation

| Parameter              | Type   | Description                                                                                                                                                                                                                                                                                                                                             |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability                                                                                                                                                                                                                                                                                                                                  |
| credentials            | object | Credential information                                                                                                                                                                                                                                                                                                                                  |
| credentials.id         | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                                 |
| credentials.category   | string | Possible values:<ul><li>ID</li><li>FACEMAP</li><li>DOCUMENT</li><li>SELFIE</li></ul>                                                                                                                                                                                                                                                                    |
| decision               | object | Decision result                                                                                                                                                                                                                                                                                                                                         |
| decision.type          | string | Possible values:<ul><li>NOT_EXECUTED</li><li>PASSED</li><li>REJECTED</li><li>WARNING</li></ul>                                                                                                                                                                                                                                                          |
| decision.details       | object | Additional decision details                                                                                                                                                                                                                                                                                                                             |
| decision.details.label | string | <ul><li>If decision.type = NOT_EXECUTED:<ul><li>NOT_ENOUGH_DATA</li><li>TECHNICAL_ERROR</li><li>UNSUPPORTED_COUNTRY</li><li>PRECONDITION_NOT_FULFILLED</li></ul></li><li>If decision.type = PASSED:<ul><li>OK</li></ul></li><li>If decision.type = REJECTED:<ul><li>DENY</li></ul></li><li>If decision.type = WARNING:<ul><li>ALERT</li></ul></li></ul> |

##### capabilities.proofOfResidency

**Dependencies: usability, imageChecks, extraction**

| Parameter              | Type   | Description                                                                                                                                                                                                                                                                                                                                             |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability                                                                                                                                                                                                                                                                                                                                  |
| credentials            | object | Credential information                                                                                                                                                                                                                                                                                                                                  |
| credentials.id         | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                                 |
| credentials.category   | string | Possible values:<ul><li>ID</li><li>FACEMAP</li><li>DOCUMENT</li><li>SELFIE</li></ul>                                                                                                                                                                                                                                                                    |
| decision               | object | Decision result                                                                                                                                                                                                                                                                                                                                         |
| decision.type          | string | Possible values:<ul><li>NOT_EXECUTED</li><li>PASSED</li><li>REJECTED</li><li>WARNING</li></ul>                                                                                                                                                                                                                                                          |
| decision.details       | object | Additional decision details                                                                                                                                                                                                                                                                                                                             |
| decision.details.label | string | <ul><li>If decision.type = NOT_EXECUTED:<ul><li>NOT_ENOUGH_DATA</li><li>TECHNICAL_ERROR</li><li>UNSUPPORTED_COUNTRY</li><li>PRECONDITION_NOT_FULFILLED</li></ul></li><li>If decision.type = PASSED:<ul><li>OK</li></ul></li><li>If decision.type = REJECTED:<ul><li>DENY</li></ul></li><li>If decision.type = WARNING:<ul><li>ALERT</li></ul></li></ul> |

##### capabilities.drivingLicenseVerification

**Dependencies:usability, imageChecks, extraction**

| Parameter              | Type   | Description                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                     | string | UUID of the capability                                                                                                                                                                                                                                                                                                                                                              |
| credentials            | object | Credential information                                                                                                                                                                                                                                                                                                                                                              |
| credentials.id         | string | UUID of the credentials                                                                                                                                                                                                                                                                                                                                                             |
| credentials.category   | string | Possible values:<ul><li>ID</li><li>FACEMAP</li><li>DOCUMENT</li><li>SELFIE</li></ul>                                                                                                                                                                                                                                                                                                |
| decision               | object | Decision result                                                                                                                                                                                                                                                                                                                                                                     |
| decision.type          | string | Possible values:<ul><li>NOT_EXECUTED</li><li>PASSED</li><li>REJECTED</li><li>WARNING</li></ul>                                                                                                                                                                                                                                                                                      |
| decision.details       | object | Additional decision details                                                                                                                                                                                                                                                                                                                                                         |
| decision.details.label | string | <ul><li>If decision.type = NOT_EXECUTED:<ul><li>TECHNICAL_ERROR</li><li>UNSUPPORTED_COUNTRY</li><li>UNSUPPORTED_STATE</li><li>PRECONDITION_NOT_FULFILLED</li><li>VALIDATION_FAILED</li></ul></li><li>If decision.type = PASSED:<ul><li>OK</li></ul></li><li>If decision.type = REJECTED:<ul><li>DENY</li></ul></li><li>If decision.type = WARNING:<ul><li>ALERT</li></ul></li></ul> |

##### Examples

**Request**

```
GET
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
```

**Response**

```
{
    "workflow": {
        "id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "PROCESSED",
        "definitionKey": "10003"
    },
    "account": {
        "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "createdAt": "2021-03-12T15:47:17.234Z",
    "startedAt": "2021-03-12T15:49:32.202Z",
    "completedAt": "2021-03-12T15:49:33.421Z",
    "credentials": [
        {
            "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/FRONT"
                }
            ]
        }
    ],
    "capabilities": {
        "extraction": [
            {
                "id": "1a11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "PASSPORT",
                    "subType": "E_PASSPORT",
                    "firstName": "JANE",
                    "lastName": "DOE",
                    "dateOfBirth": "1990-01-01",
                    "expiryDate": "2023-12-01",
                    "issuingDate": "2014-01-01",
                    "documentNumber": "xxxxxxxx",
                    "personalNumber": "<<<<<<<<<<<<<<",
                    "address": {
                        "country": "AUT",
                        "formattedAddress": "AUT"
                    }
                }
            }
        ],
        "dataChecks": [
            {
                "id": "1b11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ],
        "imageChecks": [
            {
                "id": "1c11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ],
        "usability": [
            {
                "id": "1d11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
            {
                "id": "1f11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "44444444-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "1g11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "credentials": [
                    {
                        "id": "55555555-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
        "watchlistScreening": [
             {
                     "id": "1411111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     "credentials": [
                         {
                             "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                             "category": "ID"
                         }
                     ],
                     "decision": {
                         "type": "PASSED",
                         "details": {
                             "label": "OK"
                         }
                     },
                     "data": {
                      "searchDate": "2021-07-15T10:44:11.000Z",
                      "searchId": "12345678",
                      "searchReference": "1626345851-xxxxxx",
                      "searchResultUrl": "https://app.xxx.com/public/search/123456XXC-xxxx/xxxccc",
                      "searchResults": 0,
                      "searchStatus": "SUCCESS"
                    }
                 }
             ],
          “addressValidation”: [
              {
                     "id": "1511111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     "credentials": [
                         {
                             "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                             "category": "ID"
                         }
                     ],
                     "decision": {
                         "type": "PASSED",
                         "details": {
                             "label": "OK"
                         }
                     },
            }
          ],
          “proofOfResidency”: [
           {
                     "id": "1611111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     "credentials": [
                         {
                             "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                             "category": "ID"
                         }
                     ],
                     "decision": {
                         "type": "PASSED",
                         "details": {
                             "label": "OK"
                         }
                     },
            }
          ],
          "drivingLicenseVerification": [
          {
                     "id": "1711111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     "credentials": [
                         {
                             "id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                             "category": "ID"
                         }
                     ],
                     "decision": {
                         "type": "PASSED",
                         "details": {
                             "label": "OK"
                         }
                     },
            }
         ]
         }
     }
```

#### Get Images

HTTP Request Method: GET

`US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>`
`EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>`
`SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>`

##### Request

Image Request Path Parameters

| Parameter    | Type   | Description                                                                       |
| ------------ | ------ | --------------------------------------------------------------------------------- |
| accountId    | string | UUID of the account                                                               |
| credentialId | string | UUID of the credential                                                            |
| classifier   | string | Possible values:<ul><li>FRONT</li><li>BACK</li><li>FACE</li><li>FACEMAP</li></ul> |

#### Image Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, has been deleted, or does not contain the image you requested. Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

#### Examples

Request

```
GET
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentialsId/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
```

### Health Check

Use this API to check the status of the Jumio services.

#### Request

Request Headers
The following fields are required in the header section of your request:

Accept: application/json
User-Agent: YourCompany YourApp/v1.0

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden

#### Get Health Check

HTTP Request Method: GET

US: https://status.amer-1.jumio.ai
EU: https://status.emea-1.jumio.ai
SG: https://status.apac-1.jumio.ai

##### Health Check Response Parameters

| Parameter          | Type   | Description                                                                                                                                                                           |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status             | string | Overall system status.<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                              |
| details            | object | Component-level status details.<ul><li>details.api</li><li>details.callback</li><li>details.mobile</li><li>details.processing</li><li>details.retrieval</li><li>details.web</li></ul> |
| details.api        | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |
| details.callback   | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |
| details.mobile     | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |
| details.processing | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |
| details.retrieval  | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |
| details.web        | string | Possible values:<ul><li>UP</li><li>DEGRADED</li><li>DOWN</li></ul>                                                                                                                    |

Examples

#### Request

```
> curl https://status.apac-1.jumio.ai
```

##### Response

```
{
  "status":"UP"
}

//

{
  "status":"DEGRADED",
  "details": {
    "mobile":"DEGRADED",
    "callback":"DEGRADED"
  }
}

//

{
  "status":"DOWN",
  "details": {
    "retrieval": "DOWN",
    "callback": "DOWN",
    "api":"DOWN"
  }
}
```

### Deletion

Use this API to delete accounts or workflows.

#### Usage

Request
Request Headers
The following fields are required in the header section of your request:

Accept: application/json
Authorization: see RFC6749
User-Agent: YourCompany YourApp/v1.0

⚠️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code 403 Forbidden

#### Available Deletion APIs

Account Deletion
Deletes the account and all related workflows to the account specified by accountId.

HTTP Request Method: DELETE

```
US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>
EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>
SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>
```

##### Account Deletion Request Path Parameter

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| accountId | string | UUID of the account |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction record.

#### Workflow Deletion

Deletes the workflow specified by workflowExecutionId.

HTTP Request Method: DELETE

```
US: https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
EU: https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
SG: https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
```

##### Workflow Deletion Request Path Parameters

| Parameter           | Type   | Description                    |
| ------------------- | ------ | ------------------------------ |
| accountId           | string | UUID of the account            |
| workflowExecutionId | string | UUID of the workflow execution |

#### Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction workflow.

#### Example

**Request**

```
DELETE
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
```

---

# v3 Workflow Descriptions

https://documentation.jumio.ai/docs/Integrate/V3/workflowDescriptions

# v3 Workflow Descriptions

Workflows are specified using the key attribute in the workflowDefinition object:

```
"workflowDefinition": {
    "key": DEFINITION_KEY,
    "credentials": []
}
```

## Workflow 1: ID Capture and Storage

This workflow captures a government-issued ID document and stores the extracted data.

**Required Credentials** - ID
**Stored credentials** - ID

### Prerequisites

Allowed channels: API, SDK, WEB

### Capabilities

In order of dependency:

usability --> extraction

### Example

#### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

**Request:**

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 1,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE"
    }'
```

**Response:**

```
{
    "timestamp": "2021-09-21T12:39:12.131Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationTokenxxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 2,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE"
    }'
```

Response:

```
{
    "timestamp": "2021-09-21T12:39:12.131Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationTokenxxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

## Workflow 2: ID Verification

This workflow verifies a government-issued ID document and returns a. whether that document is valid, and b. data extracted from that document.

![](./images/workflow2.png)

### Workflow 2: Details

![](./images/workflow_2_details.png)

### Required Credentials

ID

### Stored Credentials

ID

### Prerequisites

Allowed channels: API, SDK, WEB

### Capabilities

In order of dependency:

usability --> imageChecks --> extraction --> dataChecks

### Example

#### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

##### Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 2,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    },
                    "country": {
                        "values": ["USA", "CAN", "AUT", "GBR"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE"
    }'
```

##### Response:

```
{
    "timestamp": "2021-05-28T09:17:50.240Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationTokenxxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

##### Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 2,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    },
                    "country": {
                        "values": ["USA", "CAN", "AUT", "GBR"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE"
    }'
```

##### Response:

```
{
    "timestamp": "2021-02-16T16:03:10.466Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=de"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.apac-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.apac-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.apac-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

Please also refer to Account Update section.

## Workflow 3: ID and Identity Verification

This workflow verifies a photo ID document and returns a. whether that document is valid, and b. data extracted from that document. It also compares the user's face with the photo on the ID and performs a liveness check to ensure the person is physically present.

![Workflow 3 Overview](./images/workflow_3.png)

### Required Credentials

ID
Selfie
Facemap

### Stored Credentials

ID
Selfie
Facemap

### Prerequisites

Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
Allowed channels: SDK, WEB, API
Obtain End-User Consent for Biometric Data

### Capabilities

In order of dependency:

usability --> imageChecks --> extraction --> dataChecks
usability --> liveness
usability --> similarity

#### Example

#### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 3,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    },
                    "country": {
                        "values": ["USA", "CAN", "AUT", "GBR"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE",
        "userConsent": {
            "userIp": "192.168.0.1",
            "userLocation": {
                "country": "USA",
                "state": "IL"
            },
             "consent": {
              "obtained": "yes",
              "obtainedAt": "2022-07-20T17:20:35.000Z"

            }
        }
    }'
```

Response:

```
{
    "timestamp": "2021-05-19T14:55:08.187Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ]
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-cccccccccccc",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

##### Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 3,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    },
                    "country": {
                        "values": ["USA", "CAN", "AUT", "GBR"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE"
    }'
```

##### Response:

```
{
    "timestamp": "2021-05-19T14:55:08.187Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ]
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-cccccccccccc",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

## Workflow 5: Similarity to Existing ID

This workflow matches a selfie of a user to the face of a document holder of a stored ID document that has already been verified.

![Workflow 5 Overview](./images/workflow_5.png)

### Required Credentials

ID (already on file)
Selfie

### Stored Credentials

ID
Selfie

### Prerequisites

ID already on file (workflowExecution.credentials.id)
Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
Account already exists, `<accountId>` available
Allowed channels: API
Obtain End-User Consent for Biometric Data

### Capabilities

In order of dependency:

usability --> similarity

#### Example

##### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

Request:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "123",
    "workflowDefinition": {
        "key": 5,
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID"
            },
            {
                "category": "SELFIE"
            }
        ]
    },
    "userConsent": {
        "userIp": "192.168.0.1",
        "userLocation": {
            "country": "USA",
            "state": "IL"
        },
         "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-07-20T17:20:35.000Z"

        }
    }
}'
```

Response:

```
{
    "timestamp":"2021-05-14T13:58:13.285Z",
    "account":{
        "id":"11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution":{
        "id":"22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials":[
            {
                "id":"33333333-3333-3333-aaaaaaaaaaaa",
                "category":"ID",
                "allowedChannels":[]
            },
            {
            "id":"33333333-3333-3333-bbbbbbbbbbbb",
            "category":"SELFIE",
            "allowedChannels":["API"],
            "api":
                {
                    "token":"xxx",
                    "parts":
                        {
                            "face":"https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                        },
                    "workflowExecution":"https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

### Upload Face

HTTP Request Method: POST

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`

#### Request Path Parameters:

| Parameter           | Type   | Description             |
| ------------------- | ------ | ----------------------- |
| accountId           | string | UUID of the account     |
| workflowExecutionId | string | UUID of the workflow    |
| credentialsId       | string | UUID of the credentials |

#### Request Body:

| Key  | Value                                                                                                                   |
| ---- | ----------------------------------------------------------------------------------------------------------------------- |
| file | <ul><li>Supported formats: JPEG, PNG</li><li>Maximum file size: 10 MB</li><li>Maximum resolution: 8000 x 8000</li></ul> |

#### Request:

```
curl --location --request POST 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer xxx' \
--form 'file=@"/J:/User/2020-03-01/faces/selfie.jpg"'
```

#### Response:

```
{
    "timestamp": "2021-05-14T14:09:57.266Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    },
    "api": {
        "token": "xxx",
        "parts": {
            "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
        },
        "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

### Finalize

HTTP Request Method: PUT

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`

#### Request:

```
curl --location --request PUT 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx'
```

#### Response:

```
{
    "timestamp": "2021-05-14T14:12:30.562Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

### Retrieval

Please refer to Available Retrieval APIs.

## Workflow 6: Standalone Liveness

This workflow captures a user's face to verify that the person is physically present and not presenting a photo or other fake as their selfie.

![Workflow 6 Overview](./images/workflow_6.png)

### Required Credentials

Selfie
Facemap

### Stored Credentials

Selfie
Facemap

### Prerequisites

Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
Allowed channels: SDK, API
Obtain End-User Consent for Biometric Data

### Capabilities

In order of dependency:

usability --> liveness

### Example

### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

Request:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 6,
        "credentials": []
    },
    "userConsent": {
        "userIp": "192.168.0.1",
        "userLocation": {
            "country": "USA",
            "state": "IL"
        },
         "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-07-20T17:20:35.000Z"

        }
    }
}'
```

Response:

```
{
    "timestamp": "2021-05-19T15:11:18.072Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

Request:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 6,
        "credentials": []
    }
}'
```

Response:

```
{
    "timestamp": "2021-05-19T15:11:18.072Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK",
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

## Workflow 9: Authentication

This workflow compares the facemap of a user to an already existing facemap that has already been captured.

The existing facemap must have been acquired during a previous workflow, e.g. Workflow 3 or Workflow 6.

![Workflow 9 Overview](./images/workflow_9.png)

### Required Credentials

Selfie
Facemap

### Stored Credentials

Selfie
Facemap

### Prerequisites

- Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
- Account already exists, `<accountId>` available
- Facemap already on file, acquired through previous workflow
- Allowed channels: SDK, WEB
- Obtain End-User Consent for Biometric Data
  ⚠️ If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt) has to be updated accordingly.

### Capabilities

(In order of dependency)

usability --> authentication

### Example

Initiate Account Update
HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`
Request:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 9
    },
    "userConsent": {
        "userIp": "192.168.0.1",
        "userLocation": {
            "country": "USA",
            "state": "IL"
        },
         "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-07-20T17:20:35.000Z"

        }
    }
}'
```

Response:

```
{
    "timestamp": "2021-05-19T15:28:15.711Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-cccccccccccc",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            }
        ]
    }
}
```

## Workflow 16: Authentication on Premise

This workflow compares the facemap of a user to an existing facemap that was previously captured and is stored on the customer side.

The existing facemap must have been acquired during a previous workflow, e.g. Workflow 3 or Workflow 6, and can be retrieved with the Retrieval API using the validFaceMapForAuthentication parameter.

![Workflow 16 Overview](./images/workflow_16.png)

### Required Credentials

Selfie
Facemap

### Stored Credentials

Selfie
Facemap

### Prerequisites

Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
Facemap on premise must be enabled for your account.
Account already exists, `<accountId>` available
Facemap already on file (customer-side), acquired through previous workflow.
Allowed channels: SDK, WEB
Obtain End-User Consent for Biometric Data
⚠️ If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt) has to be updated accordingly.

### Capabilities

In order of dependency:

usability --> authentication

### Example

#### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

Request:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 16
    },
    "userConsent": {
        "userIp": "192.168.0.1",
        "userLocation": {
            "country": "USA",
            "state": "IL"
        },
         "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-07-20T17:20:35.000Z"

        }
    }
}'
```

Response:

```
{
    "timestamp": "2021-05-19T15:34:30.408Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=es"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "FACEMAP",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "facemap": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FACEMAP"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "33333333-3333-3333-cccccccccccc",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            }
        ]
    }
}
```

#### Upload Facemap

HTTP Request Method: POST

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACEMAP`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACEMAP`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACEMAP`

##### Request Path Parameters:

| Parameter           | Type   | Description             |
| ------------------- | ------ | ----------------------- |
| accountId           | string | UUID of the account     |
| workflowExecutionId | string | UUID of the workflow    |
| credentialsId       | string | UUID of the credentials |

##### Request Body:

| Key  | Value                                   |
| ---- | --------------------------------------- |
| file | <ul><li>Supported format: BIN</li></ul> |

##### Request:

```
curl --location --request POST 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FACEMAP' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer xxx' \
--form 'file=@"/J:/User/2020-03-01/faces/facemap.bin"'
```

Response:

```
{
    "timestamp": "2021-05-20T14:25:21.355Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    },
    "api": {
        "token": "xxx",
        "parts": {
            "facemap": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FACEMAP"
        },
        "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

ℹ️ After successful facemap upload, a new user journey can be performed for the purposes of comparing the uploaded facemap with the face of the current user, using the channels SDK or WEB. For details refer to Initiate Account Update

##### Retrieval

Please refer to Available Retrieval APIs.

## Workflow 20: Similarity of Two Images

This workflow either matches the user photos on two IDs, two user selfies or a user's selfie with the photo on the ID to verify they are the same person.

![Workflow 20 Overview](./images/workflow_20.png)

### Required Credentials

Selfie
ID

### Stored Credentials

Selfie
ID

### Prerequisites

Allowed channels: API
Obtain End-User Consent for Biometric Data

### Capabilities

In order of dependency:

usability --> similarity

### Example

#### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts

#### Request ID / Selfie:

```
curl --location --request POST 'https://account.amer-1.jumio.ai/api/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20
    },
    "userConsent": {
        "userIp": "192.168.0.1",
        "userLocation": {
            "country": "USA",
            "state": "IL"
        },
         "consent": {
          "obtained": "yes",
          "obtainedAt": "2022-07-20T17:20:35.000Z"

        }
    }
}'
```

#### Request ID / ID:

```
curl --location --request POST 'https://account.amer-1.jumio.ai/api/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20,
        "credentials": [
            {"category":"ID"},
            {"category":"ID"}
        ]
    }
}'
```

#### Request Selfie / Selfie:

```
curl --location --request POST 'https://account.amer-1.jumio.ai/api/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20,
        "credentials": [
            {"category":"SELFIE"},
            {"category":"SELFIE"}
        ]
    }
}'
```

#### Response ID / Selfie:

```
{
    "timestamp": "2021-05-21T14:52:37.815Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Response ID / ID:

```
{
    "timestamp": "2021-09-03T10:17:24.806Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Response Selfie / Selfie:

```
{
    "timestamp": "2021-09-03T10:17:24.806Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

### Initiate Account Update

HTTP Request Method: PUT

`US: https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>`
`EU: https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>`
`SG: https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>`

#### Request ID / Selfie:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20
    }
}'
```

#### Request ID / ID:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20,
        "credentials": [
            {"category":"ID"},
            {"category":"ID"}
        ]
    }
}'
```

#### Request Selfie / Selfie:

```
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer xxx' \
--data-raw '{
    "customerInternalReference": "CUSTOMER_REFERENCE",
    "workflowDefinition": {
        "key": 20,
        "credentials": [
            {"category":"SELFIE"},
            {"category":"SELFIE"}
        ]
    }
}'
```

#### Response ID / Selfie:

```
{
    "timestamp": "2021-05-21T14:52:37.815Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Response ID / ID:

```
{
    "timestamp": "2021-09-03T10:17:24.806Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "ID",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Response Selfie / Selfie:

```
{
    "timestamp": "2021-09-03T10:17:24.806Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "API"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            }
        ]
    }
}
```

#### Upload Document

HTTP Request Method: POST

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>`

##### Request Path Parameters:

| Parameter           | Type   | Description                                          |
| ------------------- | ------ | ---------------------------------------------------- |
| accountId           | string | UUID of the account                                  |
| workflowExecutionId | string | UUID of the workflow                                 |
| credentialsId       | string | UUID of the credentials                              |
| classifier          | string | Possible values:<ul><li>FRONT</li><li>BACK</li></ul> |

##### Request Body:

| Key  | Value                                                                                                                   |
| ---- | ----------------------------------------------------------------------------------------------------------------------- |
| file | <ul><li>Supported formats: JPEG, PNG</li><li>Maximum file size: 10 MB</li><li>Maximum resolution: 8000 × 8000</li></ul> |

##### Request:

```
curl --location --request POST 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer xxx' \
--form 'file=@"/J:/User/2020-03-01/faces/front.jpg"'
```

##### Response:

```
{
    "timestamp": "2021-05-24T08:07:29.511Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    },
    "api": {
        "token": "xxx",
        "parts": {
            "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
            "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
        },
        "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

#### Upload Face

HTTP Request Method: POST

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/FACE`

##### Request Path Parameters:

| Parameter           | Type   | Description             |
| ------------------- | ------ | ----------------------- |
| accountId           | string | UUID of the account     |
| workflowExecutionId | string | UUID of the workflow    |
| credentialsId       | string | UUID of the credentials |

##### Request Body:

| Key  | Value                                                                                                                   |
| ---- | ----------------------------------------------------------------------------------------------------------------------- |
| file | <ul><li>Supported formats: JPEG, PNG</li><li>Maximum file size: 10 MB</li><li>Maximum resolution: 8000 × 8000</li></ul> |

##### Request

```
curl --location --request POST 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: xxx' \
--form 'file=@"/J:/User/2020-03-01/faces/face.jpg"
```

##### Response

```
{
    "timestamp": "2021-05-24T08:15:55.269Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    },
    "api": {
        "token": "xxx",
        "parts": {
            "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
        },
        "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

#### Finalize

HTTP Request Method: PUT

`US: https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`EU: https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`
`SG: https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>`

##### Request:

```
curl --location --request PUT 'https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa' \
--header 'User-Agent: User Demo' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx'
```

##### Response:

```
{
    "timestamp": "2021-05-24T08:20:31.344Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa"
    }
}
```

## Workflow 32: ID Verification, Identity Verification, Screening

This workflow verifies a photo ID document and returns a. whether that document is valid, and b. data extracted from that document. It also compares the user's face with the photo on the ID and performs a liveness check to ensure the person is physically present. Checks if user is part of any sanctions list using Comply Advantage.

![Workflow 32 Overview](./images/workflow_32.png)

### Required Credentials

ID
Selfie
Facemap

### Stored Credentials

ID
Selfie
Facemap

### Prerequisites

Identity Verification must be enabled for your account. (Contact your Jumio account manager for activation.)
Screening must be enabled for your account. (Contact your Jumio account manager for activation.)
Screening must be set up for your Customer Portal (see Comply Advantantage Portal Setup)
Allowed channels: API, SDK, WEB
Obtain End-User Consent for Biometric Data

### Capabilities

In order of dependency:

usability --> imageChecks --> extraction --> dataChecks
usability --> liveness
usability --> imageChecks --> extraction --> watchlistScreening

### Example

#### Initiate Account Creation

HTTP Request Method: POST

US: https://account.amer-1.jumio.ai/api/v1/accounts
EU: https://account.emea-1.jumio.ai/api/v1/accounts
SG: https://account.apac-1.jumio.ai/api/v1/accounts
⚠️ userReference is required to be defined in the initiate for WF32 in order for Screening to work.

#### Request:

```
curl --request POST --location 'https://account.amer-1.jumio.ai/api/v1/accounts' \
    --header 'Content-Type: application/json' \
    --header 'User-Agent: User Demo' \
    --header 'Authorization: Bearer
    YOUR_ACCESS_TOKEN' \
    --data-raw '{
        "customerInternalReference": "CUSTOMER_REFERENCE",
        "workflowDefinition": {
            "key": 32,
            "credentials": [
                {
                    "category": "ID",
                    "type": {
                        "values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
                    },
                    "country": {
                        "values": ["USA", "CAN", "AUT", "GBR"]
                    }
                }
            ]
        },
        "callbackUrl": "YOUR_CALLBACK_URL",
        "userReference": "YOUR_USER_REFERENCE",
        "userConsent": {
            "userIp": "192.168.0.1",
            "userLocation": {
                "country": "USA",
                "state": "IL"
            },
             "consent": {
              "obtained": "yes",
              "obtainedAt": "2022-07-20T17:20:35.000Z"

            }
        }
    }'
```

#### Response:

```
{
    "timestamp": "2021-08-20T11:36:34.005Z",
    "account": {
        "id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
    },
    "web": {
        "href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationToken=xxx&locale=de"
    },
    "sdk": {
        "token": "xxx"
    },
    "workflowExecution": {
        "id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
        "credentials": [
            {
                "id": "33333333-3333-3333-aaaaaaaaaaaa",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                      "front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
                      "back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-bbbbbbbbbbbb",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "xxx",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
                }
            },
            {
                "id": "33333333-3333-3333-cccccccccccc",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            }
        ]
    }
}
```

## Retrieval

Refer to Data Acquistion section for more information on available channels (API, SDK, WEB).
Use our Retrieval API to retrieve account data and/or data acquired during a workflow.

---

# Credential Types

https://documentation.jumio.ai/docs/references/credentials/

# Types

The documents, scanned images, or prepared data that are evaluated by a Jumio workflow are called Credentials. Each Jumio capability specifies the Credential(s) it can evaluate. The required credentials for each capability that is invoked by a workflow must be uploaded to the end-user accountClosed prior to initiating the workflow.

The following topics describe the types of Credentials that are currently supported:

<ul>
<li> [ID](#id) </li>
<li> [Selfie](#selfie) </li>
<li> [Facemap](#facemap) </li>
<li> [Document](#document) </li>
<li> [Data](#data) </li>
</ul>

## ID

ID is a government-issued identification document such as a passport, identification card, or a driver's license.

The list of ID types that your integration supports, as well as a list of the IDs that Jumio supports is available from the Jumio Portal by logging in as an Administrator and going to,

**_Settings > Identity Verification > Accepted IDs_** and **_Settings > Identity Verification > Supported IDs_**.

For additional information see [Accepted IDs](../../portals/settings/IDVSettings#accepted-ids) and [Supported IDs](../../portals/settings/IDVSettings#supported-ids).

Depending on the type of ID either just a FRONT image or both FRONT and BACK images may be required. If your integration uses the Web Client or the mobile SDKs the customer journeyClosed will guide the end user to provide the required parts.

### Enable Brazilian Digital Driver’s License Support

To use the "API" channel to process Brazilian PDFs, you must first contact the [Jumio support team](https://www.jumio.com/contact/support/) to enable the Brazilian PDF driver's license functionality. Once this functionality is enabled, you can initiate the account following the specified process.

The workflow requires the Credentials array, if you upload Credentials via REST API calls. It’s also used to:

```
"credentials": [
    {
        "category": "ID",
        "country": {
            "predefinedType": "DEFINED",
            "values": [
                "BRA"
            ]
        },
        "type": {
            "predefinedType": "DEFINED",
            "values": [
                "DRIVING_LICENSE"
            ]
        }
    }
]
```

:::note
The Brazilian Digital Driving License is an official, government-issued document used to verify a driver’s identity and driving eligibility in Brazil. It is available in a digital format, which includes a QR code for easy verification and enhanced security.

- #### [Brazilian Digital Driving License QR Code Validation](../credentials/QRCode)
- #### [Brazilian Digital Driving License QR Code + Biometric Validation](../credentials/QRCode_Biometric)
  :::

## Selfie

Selfie is an image of the end user. It is uploaded and stored as a single FACE part. If your integration uses the Web Client or the mobile SDKs the [customer journey](/docs/references/glossaries#customer-journey) will guide the end user to provide the Selfie. Your integration can also upload an image using the API.

## Facemap

Facemap is a unique Credential that is made up of several images of the end user taken in rapid succession. Unlike other types of Credentials a FACEMAP cannot be uploaded directly through the API. If your integration uses the Jumio Web Client or SDKs with a workflow that evaluates a FACEMAP, the FACEMAP will be created and uploaded along with the SELFIE as the end user completes the customer journeyClosed.

The Facemap is evaluated by the [Liveness](../capabilities/liveness) capability to ensure that the end user who is completing the customer journey is a living person.

:::tip
If for any reason the FACEMAP cannot be created, the Liveness capability will evaluate the SELFIE instead.
:::

While you cannot upload a FACEMAP through the APIs you can access and download the images that comprise the FACEMAP from the retrieval APIs, checkout [Workflow Credentials](/docs/developer-resources/retrieval#workflow-credentials).

:::tip
The [Authentication On-Premises](../../references/servicesAndworkflow/standardService/authenticationOnPremises) service supports downloading and uploading a binary version of a Facemap. Using it requires additional configuration for your tenant. The binary format is not supported for other uses.
:::

## Document

Images or PDF copies of documents such as bank statements, utility bills, or insurance cards can be used to identity an end user. Workflows that accept a DOCUMENT Credential pass it to the [Extraction](../capabilities/extraction) capability. A successful extraction requires at least one of the following values:

- Name
- Issue Date
- Address

Work with your Jumio Account Representative to identify and configure the DOCUMENT types you intend to support, and the fields you expect to be extracted.

Uploads are restricted to JPEG, PNG or PDF file types totaling 15MB in size. Credit card uploads are limited to 2 images or PDF pages, and all other document types are limited to 30 images or PDF pages.

### Specifying the DOCUMENT in the Account Request

When using a workflow that requires a DOCUMENT Credential, the request body to the Account API (see [this](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts)) must include a Credential node with DOCUMENT as the category value. It must have also include country and type fields, each with exactly one value in it. If any of these conditions are not met, the request will result in validation errors.

For example, to request the standalone Doc Proof workflow (10026) with a bank statement (code: BS):

```
{
    "customerInternalReference":"postman-tomg-call2",
    "callbackUrl":"https://enxduej0n1fgwkv.m.pipedream.net",
    "workflowDefinition":{
        "key": 10026,
        "credentials": [
            {
                "category": "DOCUMENT",
                "country": {
                    "predefinedType": "DEFINED",
                    "values": ["USA"]
                },
                "type": {
                    "predefinedType": "DEFINED",
                    "values": ["BS"]
                }
            }
        ]
    },
    "userReference": "postman-tomg",
    "tokenLifetime": "10m"
}
```

### Supported Documents

These document types are supported for upload and data extraction. Other document types may be available, and custom documents may be added. Consult your Jumio SE for details about specific document types.

:::tip
Custom codes you have added must be unique, and must not be the reserved keywords CUSTOM or OTHER.
:::

<details>

- BC (Birth certificate)
- HCC (Health care card)
- IC (Insurance card)
- MEDC (Medicare card)
- SEL (School enrolment letter)
- SENC (Seniors card)
- SSC (Social security card)
- STUC (Student card)
- WWCC (Working with children check)
- BS (Bank statement)
- CCS (Credit card statement)
- CRC (Corporate resolution certificate)
- LAG (Lease agreement)
- LOAP (Loan application)
- MOAP (Mortgage application)
- SS (Superannuation statement)
- TAC (Trade association card)
- TR (Tax return)
- VC (Voided check)
- CB (Council bill)
- PB (Phone bill)
- UB (Utility bill)
- VT (Vehicle title)

</details>

## Data

Data is used to upload values for data fields that are required by a capability or risk signal in a workflow, but are not extracted from another Credential such as an [ID](../credentials/#id) or [Document](../credentials/#document).
For example, many [Risk Signals](../riskSignals/overviewRiskSignals) may be called using standalone workflows that do not include other capabilities such as Extraction, and do not require any other credentials. In these cases, the data required by the risk signal is first uploaded as prepared data, using the REST API. Using prepared data is only supported by the [REST APIs for Credential Acquisition](/docs/developer-resources/API/) integration channel.

When your API request to create or update an account specifies a workflow that supports uploading prepared data the response body will include a Credential object with a category value of DATA and a api.parts.prepared_data URL to the parametrized endpoint for uploading the data. The object also includes the api.token value for authorizing the upload request.

```
      "credentials": [
         ...
         {
            "id": "be032ae5-07ea-417b-b7e5-9ef6c3e68132",
            "category": "DATA",
            "label": "DATA",
            "allowedChannels": [
               "API"
            ],
            "api": {
               "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOQ4CMQxA0bukxlI2JzYdoqLlBomXboACCRDi7gxzA9qv99_Bnod72IfUIyOXxrn1EnZhiJx07T5NFZWgmHaoiAgzJQes0-NI3hTtxzdcErWRWgeVLFALKUxhAuvMRHlibLzih9s_XM7mq15ex-tyG5fXL21_F1KJ7FATGtTcHZh8giUfGHXOnGP4fAHVKVVI4wAAAA.IADgEkiZhlQkGbG3N-u-FNO7ECPzS2dJ9qLkOJG7WMaTDGemnWsk57iGZugFN-0VrT2U9L0m3UzqscTPJw__Yw",
               "parts": {
                  "prepared_data": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069/credentials/be032ae5-07ea-417b-b7e5-9ef6c3e68132/parts/PREPARED_DATA"
               },
               "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/fbedd5d8-3ed7-4555-b11f-54bf0a1f6d5e/workflow-executions/3186a167-dc2c-438d-bc98-e799882b5069"
            }
         }
         ...
```

Also checkout:

- [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts)
- [Prepared Data API Reference](/docs/developer-resources/API/credentials#tag/Credentials)

:::tip
Depending on the workflow, uploading prepared data may be either optional or mandatory. Also, specific fields and values may be either optional or mandatory.
:::

### Example Data Upload Request Body

Data is uploaded by making a POST request to the prepared_data URL from the account response. The request uses Bearer Token authentication with the token from the account response.

The body of the request is a JSON object with the desired or required values. For example:

```
{
    "firstName": "John",
    "middleName": "",
    "lastName": "Smith",
    "dateOfBirth": "1972-11-16",
    "socialSecurityNumber": "123456789",
    "email": "email@gmail.com",
    "phoneNumber": "+15031234567",
    "personalNumber": "",
    "address": {
        "line1": "12345 SW Address Ln",
        "postalCode": "97201",
        "city": "Portland",
        "subdivision": "OR",
        "country": "USA"
    },
    "id": {
        "idNumber": "057033812",
        "type": "DRIVING_LICENSE",
        "issuingDate": "2021-01-22",
        "expiryDate": "2026-01-22"
    }
}
```

:::info
To prevent SQL/XML injection threats the character set `[^<>"/;`%{}|] ` is not allowed in the prepared data body values for these keys: firstName, lastName, middleName, paternalSurname , maternalSurname ,email, phoneNumber.
:::

### Supported Fields

Not all values are required for all requests. Refer the documentation for specific [risk signals](../riskSignals/overviewRiskSignals) for details on required values and formats.

### Field Details Table

<details>

| Field                  | Type             | Example               | Description                                            |
| ---------------------- | ---------------- | --------------------- | ------------------------------------------------------ |
| `suffix`               | `string`         | Mr, Mrs, Ms           | Title or suffix of the subject.                        |
| `firstName`            | `string`         | John                  | First name of the subject.                             |
| `middleName`           | `string`         | Percival              | Middle name of the subject.                            |
| `lastName`             | `string`         | Smith                 | Last name of the subject.                              |
| `sex`                  | `string`         | M                     | Gender of ID subject. M for male and F for female.     |
| `dateOfBirth`          | `string($date)`  | 1972-11-16            | Date of birth in ISO 8601 date format.                 |
| `socialSecurityNumber` | `string`         | 123456789             | USA SSN of the subject.                                |
| `nationality`          | `string`         | USA                   | Nationality of the subject.                            |
| `email`                | `string($email)` | john.smith@mymail.com | Primary email address of the subject.                  |
| `phoneNumber`          | `string`         | +2134445678           | Primary phone number of the subject in E.164 format.   |
| `phoneNumber2`         | `string`         | +3109992939           | Alternate phone number of the subject in E.164 format. |
| `personalNumber`       | `string`         |                       | For Brazil, this will be the CPF number.               |
| `address`              | `Object`         |                       | Primary address for the subject.                       |
| `address.line1`        | `string`         | 12345 SW Address Ln   | Line 1 of the address.                                 |
| `address.line2`        | `string`         | Suite 707             | Line 2 of the address.                                 |
| `address.city`         | `string`         | Portland              | City of residence as it appears on the ID.             |
| `address.postalCode`   | `string`         | 97201                 | Postal or zip code.                                    |
| `address.subdivision`  | `string`         | OR                    | City subdivision of residence as it appears on the ID. |
| `address.country`      | `string`         | USA                   | Country in ISO-3166-1 Alpha-3 or Alpha-2 Code format.  |
| `id`                   | `Object`         |                       | Document data.                                         |
| `id.idNumber`          | `string`         | 057033812             | Primary ID number on the identity document.            |
| `id.Type`              | `string`         | DRIVING_LICENSE       | Type of identity document.                             |
| `id.subType`           | `string`         |                       | Sub-type of identity document.                         |
| `id.issuingDate`       | `string`         | 2021-01-22            | Date the document was issued.                          |
| `id.expiryDate`        | `string`         | 2026-01-22            | Date the document will expire.                         |

</details>

---

# Glossary

https://documentation.jumio.ai/docs/references/glossaries

# Glossary

## customer

A company or other organization that pays to use Jumio’s products and services to help keep fraudsters and financial criminals off of their platform.

## tenant

A secure, isolated environment for a customer. Each tenant includes its own configuration, users, and transactions. A tenant belongs to a customer. A customer can have multiple tenants.

## user

An individual working for a Jumio customer who is using Jumio products and services to create, configure, and maintain business applications. A user belongs to at least one tenant that belongs to the customer.

## end user

A person who is a customer, patient, constituent, or client of a Jumio customer and who participates in the “customer journey” as part of their interaction with the Jumio customer.

## role

A set of permissions that define what a user can see and do in the Jumio Portal.

## group

A named set of roles. A user belongs to at least one group and has all of the permissions defined by each role in the group or groups to which he or she belongs.

## Jumio Portal

The Jumio website is where users log in to perform the tasks associated with their assigned role(s).

## account

A grouping of credentials and transactions associated with an end user.

## credential

A form of identification that is associated with an account. Jumio currently supports these types of credentials:
Government ID; Selfie; Facemap; Document; Data, which can be either Prepared Data or Device Data.

## transaction

An executed business process that is associated with an account. The transaction applies credentials for the account to a workflow and contains the decision rendered by the workflow.

## customer journey

The end-user experience for uploading required credentials. Customers can integrate the Jumio Web Client and/or SDKs into their apps, or implement the customer journey themselves and use Jumio APIs to upload credentials and initiate transactions.

## service

An identity verification service provided by Jumio that evaluates a set of credentials and renders a decision. A service is invoked by a workflow. A workflow can invoke a single service or a sequence of services and/or risk signals.

## risk signal

Risk signals are additional third-party services that can be invoked by a workflow. They are typically used to augment the standard services and provide extra assurance for determining the end user’s fraud risk.

## workflow

A workflow is a business process definition that calls a Jumio service or sequence of services and/or risk signals. Each transaction executes a workflow.

## capability

A low-level business process that implements all or part of a service or risk signal. Individual capabilities provide the reasons for determining the transaction decision.

## decision

Each transaction renders a decision about the credentials that were evaluated. The decision includes one of the following values: PASSED, WARNING, REJECTED. It also includes a risk score. The value is based on the score.

## Mobile SDK

The Jumio mobile SDK is one of the channels through which your company can integrate with Jumio. The mobile SDK can be embedded in iOS or Android apps to allow your end users to upload credentials and trigger workflows that evaluate the credentials.

## web client

The Jumio web client is one of the channels through which your company can integrate with Jumio. The web client can be embedded in a web application to allow your end users to upload credentials and trigger workflows that evaluate the credentials.

## REST API

The Jumio REST application programming interface (API) is one of the channels through which your company can integrate with Jumio. Your applications can call the REST API directly for uploading credentials and finalizing the workflow.

## risk score

A numeric value calculated for a capability or workflow indicates the level of fraud risk associated with the evaluated credentials.

## supporting data

Data is uploaded in addition to an ID or document that helps identify the end user. These are typically values such as a phone number or email address that cannot be extracted from the ID.

---

# Capabilities

https://documentation.jumio.ai/docs/references/capabilities/

# What are Capabilities ?

Jumio transactions execute workflows that pass a set of credentials associated with an end-user account to a sequence of capabilities. Each capability evaluates one or more types of credentials and renders a decision about each credential or credential part that it evaluates, along with supporting details about the decision.

This guide provides information on current Jumio capabilities that may be called by a workflow. For each capability there is information about:

- Dependencies on other capabilities.
- Prerequisites for using the capability (if any)
- Supported credential types.
- The textual labels that may be returned to support the decision.
- Other data that is returned (if any)

This information is intended to help with interpreting transaction results, whether they are viewed in the portal or obtained programmatically by [calling Retrieval APIs](../../developer-resources/retrieval#calling-retrieval-apis).

**Example Response JSON**

Calling the workflow details API returns an array of JSON objects, with an object for each capability that was called by the workflow. The following example shows the JSON object for the usability capability. The object contains an array with a JSON object for each credential that was evaluated by the capability, along with the decision that was rendered and the supporting details.

```
"usability": [
           {
               "id": "97d9c80d-7f5c-4036-92c7-4942aaf79a65",
               "credentials": [
                   {
                       "id": "f203a9d4-31d7-4241-811e-35c68dc7a513",
                       "category": "ID"
                   }
               ],
               "decision": {
                   "type": "PASSED",
                   "details": {
                       "label": "OK"
                   }
               }
           },
           {
               "id": "61428d14-76d4-4e39-9f0e-2195543dbae8",
               "credentials": [
                   {
                       "id": "0d502495-f6e6-4bd1-bb01-cac81e2692cc",
                       "category": "SELFIE"
                   }
               ],
               "decision": {
                   "type": "PASSED",
                   "details": {
                       "label": "OK"
                   }
               }
           },
           {
               "id": "887a0687-9b81-4607-93e2-d0285c41655d",
               "credentials": [
                   {
                       "id": "5799456a-7db3-4aca-bbff-f7b4f904de52",
                       "category": "FACEMAP"
                   }
               ],
               "decision": {
                   "type": "PASSED",
                   "details": {
                       "label": "OK"
                   }
               }
           }
       ]

```

## Capability Execution Dependencies

Workflow execution consists of a chain of multiple capability executions (usability, extraction, image checks, …) with some capabilities requiring the results of those executed earlier in the chain.

Because of these dependencies, some capabilities should not be executed if any of the previous ones were not successful because they were REJECTED or NOT_EXECUTED.

If, for example, usability has passed, but extraction got rejected with the reason TECHNICAL_ERROR, the consequent imageChecks and dataChecks cannot be executed because of PRECONDITION_NOT_FULFILLED. The precondition in this case would be to successfully pass extraction.

:::tip
In some cases values may be uploaded as a part of a DATA credential, rather than being extracted from an ID or DOCUMENT. In those situations the dependencies listed below may not apply.
:::

### Current Dependencies

| Capability         | Depends On                          |
| ------------------ | ----------------------------------- |
| **Usability**      | None                                |
| **Extraction**     | Usability, Classification           |
| **Image Checks**   | Usability, Extraction               |
| **Data Checks**    | Usability, Extraction, Image Checks |
| **Liveness**       | Usability                           |
| **Similarity**     | Usability\*                         |
| **Authentication** | Liveness                            |
| **CTR**            | Usability, Extraction, Image Checks |

( Similarity\* - Usability is required only for face detectability. )

## How Jumio Handles Results?

Across all capabilities, Jumio uses a consistent set of result types:

- **Fail (REJECTED):** Used for fundamental quality issues, errors, or to indicate evidence of potential fraud.
- **Warning:** Indicates moderate or borderline issues where there is some risk or uncertainty, but not strong enough for an outright rejection. Examples include low-confidence data mismatches, ID documents nearing expiry, repeated users, or an unsupported document type.

Together, these help Jumio determine whether to **pass, warn,** or **fail** a transaction for various credential types (ID, selfie/face map, similarity checks, etc.).

---

# Usability

https://documentation.jumio.ai/docs/references/capabilities/usability

Usability checks are performed to ensure that the images captured of the government issued [ID](../credentials/#id) or [Document](../credentials/#document) are of sufficient quality to increase the likelihood of correctly completing the workflow execution.

## Dependencies

This capability has **no dependencies** on other capabilities.

## Supported Credentials

- [ID](../../references/credentials/#id)
- [Document](../../references/credentials/#document)
- [Selfie](../../references/credentials/#selfie)

## Usability Checks (Image Quality)

Jumio verifies if the submitted ID images are of acceptable quality and format for verification. Outcomes include:

- **PASSED (OK):** The image quality is sufficient for processing.
- **WARNING:** For example, the ID document submitted is from an unsupported country or document type.
- **REJECTED:** Issues such as the image is blurry, missing a page, has glare, is partly obscured, is over/under exposed, or the ID is not complete or is damaged, etc.

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Decision Details Labels

:::tip
Some labels may only be returned for specific credential types. An "**X**" in the column for the credential type indicates that **the label may be returned**.
:::

| **Decision Type** | **Label**                      | **ID** | **Document** | **Description**                                                                                                                                                  |
| ----------------- | ------------------------------ | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NOT_EXECUTED      | TECHNICAL_ERROR                | X      | X            | An error prevented execution.                                                                                                                                    |
| NOT_EXECUTED      | NOT_UPLOADED                   | X      | X            | The image was not uploaded.                                                                                                                                      |
| PASSED            | OK                             | X      | X            | The images of the ID document are of sufficient quality to complete the transaction.                                                                             |
| REJECTED          | BLACK_WHITE                    | X      |              | Black and white images are not supported.                                                                                                                        |
| REJECTED          | MISSING_SIGNATURE              | X      |              | No signature detected.                                                                                                                                           |
| REJECTED          | MISSING_PAGE                   | X      |              | The front and back pages of the document were required, but the user uploaded only one of them.                                                                  |
| REJECTED          | NOT_A_DOCUMENT                 | X      | X            | The image is not a recognized document.                                                                                                                          |
| REJECTED          | BAD_QUALITY_IMAGE              | X      | X            | The image is of insufficient quality for processing.                                                                                                             |
| REJECTED          | BLURRED                        | X      |              | Blurry image.                                                                                                                                                    |
| REJECTED          | GLARE                          | X      |              | The ID is obscured by glare.                                                                                                                                     |
| REJECTED          | PART_OF_DOCUMENT_MISSING       | X      |              | Part of the document was excluded from the image.                                                                                                                |
| REJECTED          | PART_OF_DOCUMENT_HIDDEN        | X      |              | Part of the ID is hidden from view in the uploaded image.                                                                                                        |
| REJECTED          | DAMAGED_DOCUMENT               | X      |              | The document is damaged to the extent that the data is difficult to extract or the security features are difficult to check.                                     |
| REJECTED          | MISSING_MANDATORY_DATAPOINTS   | X      | X            | One or more of the key data fields, such as First Name, Last Name or DOB, cannot be extracted. This rejection reason will only happen for Jumio Go transactions. |
| REJECTED          | DOCUMENT_CONTENT_NOT_SUPPORTED |        | X            | Only used for Document credentials, when the document content does not conform to the type specified in the account request.                                     |
| REJECTED          | DIGITAL_COPY                   | X      |              | ID image is of a screen.                                                                                                                                         |
| WARNING           | UNSUPPORTED_COUNTRY            | X      |              | The document was issued by a country that is not configured for your organization.                                                                               |
| WARNING           | UNSUPPORTED_DOCUMENT_TYPE      | X      |              | The document type is not supported.                                                                                                                              |
| REJECTED          | PHOTOCOPY                      | X       | X           |The document in the image is a photocopy and not the original document

---

# Extraction

https://documentation.jumio.ai/docs/references/capabilities/extraction

# Extraction

Extracts data values from the ID image(s) or DOCUMENT images. Extraction can be fully automated, handled manually by humans, or may be a hybrid of automated and manual processes, depending on the document type and the Jumio products you have purchased. For example, if you have purchased Jumio GO, the process is completely automated.

The Extraction capability automatically rotates and crops the ID image(s) to improve data extraction accuracy. Multiple methods of data extraction are utilized including barcode scanning, reading the MRZ, and OCR.

The data fields that are extracted vary by document type, country, and configuration options.

### Dependency

- [Usability](/docs/references/capabilities/usability)

### Supported Credentials

- [ID](../../references/credentials/#id) see Data Extracted from [ID Types](../capabilities/extraction#data-extracted-from-id-types)
- [Document](../../references/credentials/#document) see Data Extracted from [DOCUMENT Types](../../references/capabilities/extraction#data-extracted-from-document-types)

:::note
If an eIDAS digital ID is used instead of a physical ID, the system does not have access to the ID face, meaning a face comparison cannot be performed. Additionally, the data points returned may differ when using an eIDAS digital ID.
:::

## nfcValidationResult Label

:::note
NFC Read-Only scanning is disabled per default. Please contact the [Jumio Support](https://support.jumio.com/s/) if you would like to change this setting.
:::

**nfcValidationResult**, indicates the detailed validation result of NFC data received from the Mobile SDK. For documents where NFC extraction is possible, the parameter nfcValidationResult is returned. Possible values include:

| **Status**              | **Description**                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **READ_VALIDATED**      | NFC data was successfully read and validated.                                                                                                       |
| **READ_ONLY**           | NFC data was read, but validation was not possible.                                                                                                 |
| **VALIDATION_FAILED**   | NFC data was read, but validation failed.                                                                                                           |
| **SKIPPED**             | The user intentionally skipped the NFC process.                                                                                                     |
| **SKIPPED_MAX_RETRIES** | The NFC process was skipped after reaching the maximum retry limit.                                                                                 |
| **TECHNICAL_ERROR**     | An unrecoverable error occurred, such as an authentication failure.                                                                                 |
| **READER_UNAVAILABLE**  | The device does not support NFC scanning.                                                                                                           |
| **COUNTRY_UNAVAILABLE** | NFC data could not be validated because no certificates are available for the document’s issuing country (applies only if `READ_ONLY` is disabled). |

## Decision Details Labels

| **Decision Type** | **Label**                  | **Description**                                                                |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------ |
| NOT_EXECUTED      | PRECONDITION_NOT_FULFILLED | Required data from another capability is not available.                        |
| NOT_EXECUTED      | TECHNICAL_ERROR            | An error prevented execution.                                                  |
| PASSED            | OK                         | All required data values were successfully extracted from the image of the ID. |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Data Extracted from ID Types

For almost all government-issued ID document types a successful extraction must include:

- first name

- last name

- date of birth

- document number

- expiry date

Other values may be extracted, depending on the type and country of the ID. The following table shows some common values. Consult with your Jumio Account Representative to verify that the IDs and fields for your use case are supported.

<details>
    <summary> Table </summary>
| **Key**        | **Type**       | **Description**                         |
| -------------- | -------------- | --------------------------------------- |
| firstName      | string         | ID holder's first name.                 |
| lastName       | string         | ID holder's last name.                  |
| dateOfBirth    | string(\$date) | The ID holder's date of birth.          |
| documentNumber | string         | The value that identifies the document. |
| expiryDate     | string(\$date) | Date the ID expires.                    |

**Additional Fields**

| **Key**                      | **Type**                                                                                               | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address                      | object (see [Address](../capabilities/extraction#address))                                             | The ID holder's address.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| additionalLanguage           | object (see [Additional Language](../capabilities/extraction#additional-language))                     | If enabled for your tenant, additional fields may be extracted and returned in the native language of the ID.                                                                                                                                                                                                                                                                                                                                                           |
| company                      | string                                                                                                 | The company the card holder is working at.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| cpf                          | string                                                                                                 | The Cadastro de Pessoas Fisicas (CPF) number extracted from the ID document (Brazilian IDs only).                                                                                                                                                                                                                                                                                                                                                                       |
| curp                         | string                                                                                                 | The Clave Única de Registro de Población (CURP) identity code for Mexican documents.                                                                                                                                                                                                                                                                                                                                                                                    |
| currentAge                   | string                                                                                                 | Current age, calculated based on the date of birth or the date of birth parts field (if currentAge calculation is enabled).                                                                                                                                                                                                                                                                                                                                             |
| dlCategories                 | array of objects (see [Driving License Category](../capabilities/extraction#driving-license-category)) | Data points used to determine whether the holder of the license is allowed to drive a specific vehicle.                                                                                                                                                                                                                                                                                                                                                                 |
| dni                          | string                                                                                                 | DNI as available on the ID if `idCountry = ESP` and `idSubtype = NATIONAL_ID`.                                                                                                                                                                                                                                                                                                                                                                                          |
| dueDate                      | string                                                                                                 | Due date in `YYYY-MM-DD` format.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| durationOfStay               | string                                                                                                 | Duration of stay if `idType = VISA` and additional extraction for Visa enabled.                                                                                                                                                                                                                                                                                                                                                                                         |
| gender                       | string                                                                                                 | The ID holder's gender: `M` or `F`.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| issuingAuthority             | string                                                                                                 | Issuing authority of the document.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| issuingCountry               | string                                                                                                 | The country that issued the document (ISO 3166-1 alpha-3 country code, e.g., USA, AUT, DEU).                                                                                                                                                                                                                                                                                                                                                                            |
| issuingDate                  | string(\$date)                                                                                         | Date the ID was issued.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| issuingNumber                | string                                                                                                 | "Numero de emission" number for `idCountry = MEX` (if extraction is enabled).                                                                                                                                                                                                                                                                                                                                                                                           |
| issuingPlace                 | string                                                                                                 | Issuing place of the document.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| mrz                          | object (see [MRZ](../capabilities/extraction#mrz-lines))                                               | Lines from the MRZ (machine readable zone).                                                                                                                                                                                                                                                                                                                                                                                                                             |
| nationality                  | string                                                                                                 | Nationality of the document holder (ISO 3166-1 alpha-3 country code).                                                                                                                                                                                                                                                                                                                                                                                                   |
| occupation                   | string                                                                                                 | The occupation of the card holder.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| optionalMrzField1            | string                                                                                                 | Optional field of MRZ line 1.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| optionalMrzField2            | string                                                                                                 | Optional field of MRZ line 2.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| passportNumber               | string                                                                                                 | Passport number if `idType = VISA` and additional extraction for Visa enabled.                                                                                                                                                                                                                                                                                                                                                                                          |
| personalIdentificationNumber | string                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| personalNumber               | string                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| pesel                        | string                                                                                                 | The ID holder's PESEL number (Polish IDs only).                                                                                                                                                                                                                                                                                                                                                                                                                         |
| placeOfBirth                 | string                                                                                                 | The ID holder's place of birth (city, town, region, or country).                                                                                                                                                                                                                                                                                                                                                                                                        |
| registrationNumber           | string                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| rgNumber                     | string                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| signatureAvailable           | boolean                                                                                                | Whether a signature is present for the ID type (`true` or `false`).                                                                                                                                                                                                                                                                                                                                                                                                     |
| state                        | string                                                                                                 | State/country information (ISO 3166 or free text).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| streetNumber                 | string                                                                                                 | Part of Arabic addresses, represents the number of a street as part of the address.                                                                                                                                                                                                                                                                                                                                                                                     |
| subType                      | string                                                                                                 | Possible subtypes based on type (`NATIONAL_ID` `CONSULAR_ID` `ELECTORAL_ID` `RESIDENT_PERMIT_ID` `TAX_ID` `STUDENT_ID` `PASSPORT_CARD_ID` `MILITARY_ID` `PUBLIC_SAFETY_ID` `HEALTH_ID` `OTHER_ID` `VISA` `UNKNOWN` `MULTI_PURPOSE_ID` `PROFESSIONAL_ID` `PUBLIC_SAFETY_ID` `CITIZENSHIP_ID` `SERVICES_ID` `SOCIAL_SECURITY_ID`). Possible values if type = DRIVING_LICENSE include: `REGULAR_DRIVING_LICENSE` `LEARNING_DRIVING_LICENSE` `DIGITAL_DRIVING_LICENSE_PDF`. |
| type                         | string                                                                                                 | Possible values: `PASSPORT`, `DRIVING_LICENSE`, `ID_CARD`, `VISA`, `UNSUPPORTED`, `DIGITAL_IDENTITY`.                                                                                                                                                                                                                                                                                                                                                                   |
| visaCategory                 | string                                                                                                 | Visa category if `idType = VISA` and additional extraction for Visa enabled.                                                                                                                                                                                                                                                                                                                                                                                            |
| taxNumber                    | string                                                                                                 | A tax number field (NIF, TIN, etc.) stores a government-issued identifier used to track individuals or entities for taxation and financial compliance. Also known as `fiscalNumber` in Italy.                                                                                                                                                                                                                                                                           |

</details>

### Address

| **Key**              | **Type** | **Description**                                                                                                                     |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **buildingNumber**   | string   | Part of Arabic addresses (on KWT IDs), represents the building number as part of the address                                        |
| **city**             | string   | City                                                                                                                                |
| **country**          | string   | Possible values: <br /> - [ISO 3166-1 alpha-3 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) <br /> - XKK (Kosovo) |
| **districtNumber**   | string   | Part of Arabic addresses, represents the number of a district as part of the address                                                |
| **floorNumber**      | string   | Part of Arabic addresses (on KWT IDs), represents the floor number as part of the address                                           |
| **formattedAddress** | string   | Complete address in a formatted way                                                                                                 |
| **line1**            | string   | Line item 1                                                                                                                         |
| **line2**            | string   | Line item 2                                                                                                                         |
| **line3**            | string   | Line item 3                                                                                                                         |
| **line4**            | string   | Line item 4                                                                                                                         |
| **line5**            | string   | Line item 5                                                                                                                         |
| **postalCode**       | string   | Postal code                                                                                                                         |
| **subdivision**      | string   | Subdivision (Region, State, Province, Emirate, Department, …)                                                                       |
| **unit**             | string   | Part of Arabic addresses (on KWT IDs), represents the unit as part of the address                                                   |

### Additional Language

The additionalLanguage fields returned will vary by country, ID type, and subtype. Contact Jumio Support if you require additional information.

| Key            | Type   | Description                                                                                                   |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| firstName      | string | ID holder's first name as displayed on the ID.                                                                |
| lastName       | string | ID holder's last name as displayed on the ID.                                                                 |
| address        | object | Contains the same fields as [Address](../capabilities/extraction#address); values are as displayed on the ID. |
| dateOfBirth    | string | ID holder's date of birth as displayed on the ID. The value is a string, not a formatted date.                |
| documentNumber | string | ID document number as displayed on the ID.                                                                    |
| employer       | string | ID holder's employer as displayed on the ID.                                                                  |
| expiryDate     | string | ID expiration date as displayed on the ID. The value is a string, not a formatted date.                       |
| fathersName    | string | ID holder's father's name as displayed on the ID.                                                             |
| gender         | string | ID holder's gender as displayed on the ID.                                                                    |
| issuingDate    | string | Date the ID was issued, as displayed on the ID. The value is a string, not a formatted date.                  |
| issuingPlace   | string | Place the ID was issued, as displayed on the ID.                                                              |
| language       | string | The [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the ID language.       |
| maritalStatus  | string | ID holder's marital status as displayed on the ID.                                                            |
| nationality    | string | ID holder's nationality as displayed on the ID.                                                               |
| placeOfBirth   | string | ID holder's place of birth as displayed on the ID.                                                            |
| profession     | string | ID holder's profession as displayed on the ID.                                                                |
| religion       | string | ID holder's religion as displayed on the ID.                                                                  |

### Driving License Category

| Key          | Type   | Description                                                                   |
| ------------ | ------ | ----------------------------------------------------------------------------- |
| category     | string |                                                                               |
| issueDate    | string | Date in `YYYY-MM-DD` format                                                   |
| expiryDate   | string | Date in `YYYY-MM-DD` format                                                   |
| isReadable   | string | A `TRUE` or `FALSE` value indicating whether the license was readable or not. |
| availability | string |                                                                               |

### MRZ Lines

| Key   | Type   | Description                          |
| ----- | ------ | ------------------------------------ |
| line1 | string | First line in the MRZ.               |
| line2 | string | Second line in the MRZ.              |
| line3 | string | Third line in the MRZ, if available. |

## Data Extracted from DOCUMENT Types

Work with your Jumio Account Representative to identify and configure the DOCUMENT types you intend to support, and the fields you expect to be extracted.

A successful extraction requires at least one of the attributes being extracted, with the exception of credit cards (where the PAN number and expiry date are mandatory) and USA Social Security Card (where all attributes are mandatory).

For the following specific document types, additional data will be extracted:
| Document Type | Extracted Data |
|-------------------------------------|--------------------------------------------------------------------------------------------------|
| **BS (Bank Statement)** | `lastName`\*, `issuingDate`, `address`, `accountNumber`, `swiftCode` |
| **CC (Credit Card)** | `lastName`\*, `panNumber`, `monthYearExpiry` |
| **UB (Utility Bill)** | `lastName`\*, `issuingDate`, `address`, `dueDate` |
| **CCS (Credit Card Statement)** | `lastName`\*, `issuingDate`, `address`, `cardNumberLastFourDigits` |
| **SSC (Social Security Card, USA)** | `firstName`, `lastName`, `socialSecurityNumber`, `signatureAvailable` |
| **BC (Birth Certificate)** | `lastName`\*, `issuingDate`, `address`, `dateOfBirth` |
| **All other document types** | `lastName`\*, `issuingDate`, `address` |

:::note
\*The complete name will be retrieved within this attribute.
:::

---

# Image Checks

https://documentation.jumio.ai/docs/references/capabilities/image-checks

# Image Checks

The ID document image(s) undergo a combination of automated image checks.

### Dependencies

- [Usability](/docs/references/capabilities/usability)
- [Extraction](/docs/references/capabilities/extraction)

### Supported Credentials

- [ID](../../references/credentials/#id)
- [Selfie](../../references/credentials/#selfie)
- [Document](../../references/credentials/#document)

## Image Checks (Visual / Image-Based Analysis)

These checks validate whether the uploaded ID image meets the required authenticity standards. Outcomes include:

- **PASSED** (OK): The image passes all checks.

- **WARNING**: Concerns that aren’t grounds for a complete fail but warrant attention, such as ower confidence evidence of an image manipulation of the text.

- **REJECTED**: Strong signs of potential fraud, e.g., fake/counterfeit ID, digital screen or paper copy, synthetic holder signature, misaligned layout or format, or evidence of physical or digital manipulation of the portrait photo or text.

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Decision Details Labels

:::tip
Some labels may only be returned for specific credential types. An "X" in the column for the credential type indicates that the label may be returned.
:::

<div style={{ overflowX: 'auto' }}>
| Decision Type | Label | ID | Document | Description |
|--------------|------------------------------------|---|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| NOT_EXECUTED | PRECONDITION_NOT_FULFILLED | X | X | Required data from another capability is not available. |
| NOT_EXECUTED | TECHNICAL_ERROR | X | X | An error prevented execution. |
| PASSED | OK | X | X | The images of the ID document passed all image checks. |
| REJECTED | FAILED | X |  | The images of the ID document did not pass all image checks. |
| REJECTED | WATERMARK | X |  | The image of the ID contains a watermark (e.g., "Sample"). |
| REJECTED | OTHER_REJECTION | X |  | The image of the ID was rejected for a reason that does not fall under the other decision labels. |
| REJECTED | GHOST_IMAGE_DIFFERENT | X |  | There is a mismatch between the ID's main image and ghost image. |
| REJECTED | PUNCHED | X |  | The ID has been hole-punched. |
| REJECTED | SAMPLE | X | X | The ID is a known sample document. |
| REJECTED | FAKE | X |  | The ID is fake. Possible reasons include:<ul><li>The ID is a well-known fake.</li><li>The image is available on the public internet.</li></ul> |
| REJECTED | CHIP_MISSING | X |  | The ID has a missing chip. |
| REJECTED | DIGITAL_MANIPULATION | X |  | The image of the ID was manipulated before being uploaded. |
| REJECTED | MISMATCH_FRONT_BACK | X |  | The country shown on the front of the ID does not match the one shown on the back. |
| REJECTED | MANIPULATED_DOCUMENT | X | X | The ID shows a physically superimposed photo or text. **Note:** In most cases one of the more detailed labels shown below will be returned. |
| REJECTED | MANIPULATED_DOCUMENT_PHOTO | X |  | The ID shows a physically superimposed photo or text. |
| REJECTED | MANIPULATED_DOCUMENT_DOCUMENT_NUMBER | X |  | The document number on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_EXPIRY | X |  | The expiration date on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_DOB | X |  | The date of birth on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_NAME | X |  | The name on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_ADDRESS | X |  | The address on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_SECURITY_CHECKS | X |  | A back-office agent reviewed the scan and rejected it based on an issue with the security features. For example:<ul><li>The background microprint or pattern does not match the sample image.</li><li>A logo or image is missing or not inline with the sample.</li></ul> |
| REJECTED | MANIPULATED_DOCUMENT_SIGNATURE | X |  | The signature on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_PERSONAL_NUMBER | X |  | The personal number on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_PLACE_OF_BIRTH | X |  | The place of birth on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_GENDER | X |  | The gender on the ID shows visible physical or digital manipulations. |
| REJECTED | MANIPULATED_DOCUMENT_ISSUING_DATE | X |  | The issue date on the ID shows visible physical or digital manipulations. |
| WARNING | DIFFERENT_PERSON | X |  | When the user submits an image that includes both a face and an ID, the face does not match the person on the ID. |
| WARNING | REPEATED_FACE | X |  | The same face has been seen in a previous transaction, indicating that the same end user may have opened multiple accounts. The Image Checks capability includes a 1:n face matching feature based on facial biometrics. The face, either from the image extracted from the ID credential or from the Selfie, is compared to the other faces that have been seen in transactions for the tenant. If a match is found, the transaction decision depends on whether or not the personal data is the same in the matching transactions.<ul><li>If the data is the same a WARNING is returned, and the UUIDs of the matching transactions are returned in the data.faceSearchFindings.findings array.</li><li>If the data is not the same, the transaction will be REJECTED, and a label of MISMATCHING_DATA_REPEATED_FACE will be included in the [Data Checks](../capabilities/data-checks) capability.</li></ul> |
| WARNING | GHOST_IMAGE_QUALITY_INSUFFICIENT | X |  | The ghost image is too faded for our models to confidently determine if it is available. |
| REJECTED | LOOKUPS_HIGH_RISK_FACE | X |  | A face match was confirmed as fraud by Jumio’s internal quality review or based on the transaction status set via the Jumio Portal. |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
</div>
## Data

| Key                                 | Type             | Description                                                                                                  |
| ----------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `faceSearchFindings.status`         | string           | Possible values: <ul><li>DONE</li> <li>PENDING</li> <li>ERROR</li></ul>                                      |
| `faceSearchFindings.findings`       | array of strings | A face (on the ID or Selfie) is matching with another face (on the ID or Selfie) from a previous transaction |
| `faceSearchFindings.findings.items` | string           | UUID of the transaction                                                                                      |

---

# Data Checks

https://documentation.jumio.ai/docs/references/capabilities/data-checks

# Data Checks

After the data is extracted from the ID image(s), a number of fraud checks are applied to the data.

### Dependencies

- [Usability](/docs/references/capabilities/usability)
- [Extraction](/docs/references/capabilities/extraction)
- [Image Checks](/docs/references/capabilities/image-checks)

### Supported Credentials

- [ID](../../references/credentials/#id)

## Data Checks (Post-Extraction Validity and Fraud Checks)

Jumio applies several validity and fraud-related checks after classifying the document type and extracting data from the ID image. These checks result in one of several statuses:

- **PASSED** (OK): No validation failures or potential fraud detected.

- **WARNING**: Issues like document nearing or past expiration, medium-risk IP/device lookups, minor data mismatches, or a minor data field validation failure.

- **REJECTED** (Fail): Serious fraud flags such as high-risk lookups, mismatching data with a repeated face, significantly mismatching data, or major data field validation failure.

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Decision Details Labels

| Decision Type | Label                                        | Description                                                                                                                                                                                                            |
| ------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED                   | Required data from another capability is not available.                                                                                                                                                                |
| NOT_EXECUTED  | TECHNICAL_ERROR                              | An error prevented execution.                                                                                                                                                                                          |
| PASSED        | OK                                           | Fraud was not detected during the analysis of the data extracted from the ID image.                                                                                                                                    |
| WARNING       | DOCUMENT_EXPIRY_WITHIN_CONFIGURED_LIMIT      | The document is nearing its expiration date.                                                                                                                                                                           |
| REJECTED      | HIGH_FRAUD_RISK                              | There is a high probability of fraud.                                                                                                                                                                                  |
| REJECTED      | NFC_CERTIFICATE                              | There is a mismatch between the data extracted from the microchip on the passport and the data extracted from the document using OCR. This rejection reason only applies to transactions using NFC on a mobile device. |
| REJECTED      | MISMATCHING_DATAPOINTS                       | There is a mismatch between different occurrences of a repeating datapoint on a document. For example, the data extracted from the barcode does not match the printed data extracted from the ID.                      |
| REJECTED      | MRZ_CHECKSUM                                 | The machine-readable zone (MRZ) checksum has an unexpected value.                                                                                                                                                      |
| REJECTED      | MISMATCHING_DATA_REPEATED_FACE               | The ID or selfie matches a previously uploaded selfie or ID but the corresponding personal data does not match.                                                                                                        |
| REJECTED      | CUSTOMER_FEEDBACK                            | The ID data matches the data from a previous transaction that was labeled as fraud via the [transaction feedback](https://documentation.jumio.ai/docs/developer-resources/bestPractices/provide-feedback) feature.     |
| REJECTED      | ID_DATA_MISMATCH                             | A significant mismatch between instances of a data field is detected.                                                                                                                                                  |
| REJECTED      | LOOKUPS_HIGH_RISK_SAME_DATA                  | The ID document matches with at least one past rejected transaction                                                                                                                                                    |
| REJECTED      | LOOKUPS_HIGH_RISK_SAME_FACE_MISMATCHING_DATA | The ID or selfie matches a previously uploaded selfie or ID with mismatching data                                                                                                                                      |
| REJECTED      | LOOKUPS_HIGH_RISK_DEVICE                     | The device data matches with one or multiple transactions rejected in the past                                                                                                                                         |
| REJECTED      | LOOKUPS_HIGH_RISK_IP_ADDRESS                 | The IP address matches with one or multiple transactions rejected in the past                                                                                                                                          |
| WARNING       | ID_DATA_MISMATCH_LOW_CONFIDENCE              | There is a probable mismatch between different occurrences of a data field on a document                                                                                                                               |
| WARNING       | ID_DATA_INVALID                              | The data on the ID has failed validation checks in relation to field length, formatting or character type, etc.                                                                                                        |
| WARNING       | UNREADABLE_DATASOURCE                        | The data in the machine readable zone (MRZ) or barcode was not readable                                                                                                                                                |
| WARNING       | LOOKUPS_MEDIUM_RISK_SAME_DOCUMENT_NUMBER     | The ID matches the document number with at least one past transaction, which shows different first, last name, and date of birth                                                                                       |

---

# Liveness

https://documentation.jumio.ai/docs/references/capabilities/liveness

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Liveness

The Liveness capability provides automated checks that ensure the end user is physically present during the verification and is not attempting a spoofing attack.

#### Dependencies

Dependencies include [Usability](/docs/references/capabilities/usability) and [Selfie](/docs/references/credentials/#selfie) that is acquired for the workflow must be PASSED by the Usability capability.

#### Supported Credential include

- [Facemap](../../references/credentials/#facemap)
- [Selfie](../../references/credentials/#selfie)

A Facemap is optional, but significantly improves the reliability of the Liveness checks. The Facemap can only be acquired by using the [Web Client](../../developer-resources/web-client/) or one of the [Jumio SDKs](/docs/developer-resources/SDKs/Overview_of_SDKs).

## Response

Response data is available for transactions that include the Liveness capability. For information on transaction data see [this](/docs/developer-resources/API/retrieval).

<Tabs>
  <TabItem value="STANDARD" label="JUMIO_STANDARD">

```json
  "liveness": [
    {
      "id": "a070b186-d678-4de8-9a5f-5a15a35e99a4",
      "credentials": [
        {
          "id": "fe84b047-c9fb-490b-8358-009ee4e695a5",
          "category": "SELFIE"
        },
        {
          "id": "398cf6bf-524d-4fd5-b2a8-586e3df89502",
          "category": "FACEMAP"
        }
      ],
      "decision": {
        "type": "PASSED",
        "details": {
          "label": "OK"
        }
      },
      "data": {
        "type": "JUMIO_STANDARD",
        "predictedAge": 49,
        "ageConfidenceRange": "14-67"
      }
    }
  ],
```

 </TabItem>
  <TabItem value="Premium" label="JUMIO_PREMIUM">

    ```json
    "liveness": [
      {
        "id": "a070b186-d678-4de8-9a5f-5a15a35e99a4",
        "credentials": [
                    {
            "id": "398cf6bf-524d-4fd5-b2a8-586e3df89502",
            "category": "FACEMAP"
          },
          {
            "id": "fe84b047-c9fb-490b-8358-009ee4e695a5",
            "category": "SELFIE"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        },
        "data": {
          "type": "JUMIO_PREMIUM",
          "predictedAge": 24,
          "ageConfidenceRange": "13-42"
        }
      }
    ],
    ```

  </TabItem>
</Tabs>

## Decision Details Labels

| Decision Type | Label                      | Description                                                                                   |
| ------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Required data from another capability is not available.                                       |
| NOT_EXECUTED  | TECHNICAL_ERROR            | An error prevented execution.                                                                 |
| PASSED        | OK                         | Analysis determined that the end user was physically present during the verification process. |
| REJECTED      | LIVENESS_UNDETERMINED      | Liveness cannot be determined.                                                                |
| REJECTED      | ID_USED_AS_SELFIE          | An ID photo was used for the selfie.                                                          |
| WARNING       | MULTIPLE_PEOPLE            | More than one face appears in the selfie.                                                     |
| REJECTED      | DIGITAL_COPY               | The selfie was captured from a screen.                                                        |
| REJECTED      | PHOTOCOPY                  | The selfie was captured from a paper printout.                                                |
| REJECTED      | MANIPULATED                | The selfie was manipulated prior to uploading (for example, a background swap).               |
| REJECTED      | NO_FACE_PRESENT            | A face does not appear in the selfie.                                                         |
| REJECTED      | FACE_NOT_FULLY_VISIBLE     | The face is only partially visible in the selfie.                                             |
| REJECTED      | BLACK_WHITE                | The selfie image is black and white.                                                          |
| WARNING       | BAD_QUALITY                | The selfie is of bad quality.                                                                 |
| REJECTED      | PERSON_SWITCH              | More than one person appears in the liveness journey.                                         |
| WARNING       | AGE_DIFFERENCE (Deprecated)             | There is a large difference between the estimated selfie age and the date of birth on the ID. |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Data

| Key                  | Type    | Description                                                                                                                                                                                                         |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`               | string  | The service that is used. Possible values: <ul> <li>JUMIO_STANDARD</li><li> JUMIO_PREMIUM (requires additional configuration for your tenant)</li> </ul> **The technology used is based on the product purchased.** |
| `predictedAge`       | integer | Estimated age of the end user based on the selfie.                                                                                                                                                                  |
| `ageConfidenceRange` | string  | Age range into which the end user would fall.                                                                                                                                                                       |

---

# Similarity Check

https://documentation.jumio.ai/docs/references/capabilities/similarity

# Similarity

Similarity is an automated check that compares the face from the ID image with the face captured in the selfie. Some workflows may use alternate credential combinations, and each workflow defines the specific data required. The Similarity check is only executed when the necessary face images are available.

#### Dependency

Dependency includes [Usability](/docs/references/capabilities/usability), but only for cases related to face detectability.
The capability will not run only when the face on the ID cannot be detected. Missing mandatory ID fields do not affect Similarity execution.

#### Supported Credentials

- [ID](../../references/credentials/#id)
- [Selfie](../../references/credentials/#selfie)

## Decision Details Labels

| Decision Type | Label                      | Description                                                                               |
| ------------- | -------------------------- | ----------------------------------------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Capability could not run because the required face could not be detected on the ID image. |
| NOT_EXECUTED  | TECHNICAL_ERROR            | An error prevented execution.                                                             |
| PASSED        | MATCH                      | The faces in the images being compared belong to the same person.                         |
| REJECTED      | NO_MATCH                   | The faces in the selfie and ID do not match.                                              |
| WARNING       | NOT_POSSIBLE               | Similarity cannot be determined.                                                          |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Data

| Key          | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `similarity` | string | Possible values: `MATCH`, `NO_MATCH`, `NOT_POSSIBLE` |

:::important
If an eIDAS digital ID is used instead of a physical ID, the system does not have access to the ID face, meaning **Similarity checks cannot be performed**. The actual ID image is also not returned, so these checks are not possible. Additionally, the data points returned may differ when using an eIDAS digital ID. For risk scoring, this limitation may need to be addressed in your rules configuration.
:::

---

# Authentication

https://documentation.jumio.ai/docs/references/capabilities/authentication-capabilities

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Authentication

Jumio Authentication helps ensure that only the rightful user can access an account — continuously confirming their identity to prevent account takeover and foster long-term trust.

For a detailed description checkout [Authentication Workflow](../../references/servicesAndworkflow/standardService/authenticationWorkflow).
:::info
Authentication requires your integration to use either the Web Client or one of the Mobile SDKs.
:::

#### Dependency

[Liveness](../../references/capabilities/liveness) - **An Authentication workflow can only be initiated if at least one Liveness check has successfully passed for the user’s accountID**.

:::info
If your data retention policies remove existing credentials you have the option of using [Authentication On-Premises](../../references/servicesAndworkflow/standardService/authenticationOnPremises).
:::

#### Supported Credentials

- [Facemap](../../references/credentials/#facemap)
- [Selfie](../../references/credentials/#selfie)

## Response

Response data is available for transactions that include,

<Tabs>
  <TabItem value="STANDARD" label="REJECTED">

```json
    "authentication": [
     {
      "id": "1bd548ce-81bc-4f99-abbc-c4fe39b0ee1f",
      "credentials": [
          {
              "id": "fe5d9666-e451-4632-8e02-e325e0421b5c",
              "category": "FACEMAP"
          }
      ],
      "decision": {
          "type": "REJECTED",
          "details": {
              "label": "FAILED"
          }
      },
      "data": {
          "type": "JUMIO_STANDARD"
      }
    }
  ]
```

</TabItem>

  <TabItem value="RejectedSTANDARD" label="PASSED">
  
```json
    "authentication": [
        {
            "id": "78c51e8f-7378-4882-a4a5-e594b8906c94",
            "credentials": [
                {
                    "id": "27cab914-6886-405c-94f9-d2364580df8a",
                    "category": "FACEMAP"
                }
            ],
            "decision": {
                "type": "PASSED",
                "details": {
                    "label": "OK"
                }
            },
            "data": {
                "type": "JUMIO_STANDARD"
            }
        }
    ]
```
  </TabItem>
</Tabs>

**To get the specific rejection reason (e.g. "FACE_INVALID_DIGITAL_COPY"), make an additional call to retrieve the [response from /steps](https://documentation.jumio.ai/docs/developer-resources/API/retrieval#tag/Retrieval/operation/getWorkflowExecutionSteps)**

```json

"steps": {
"href":"https://retrieval.emea-1.jumio.link/api/v1/accounts/accountId/workflow-executions/workflowExecutionId/steps"
}

```

<Tabs>
  <TabItem value="STANDARD" label="Steps_REJECTED">
```json
{
    "steps": [
        {
            "id": "df7b6d9a-ee6c-43f6-8109-171ea4c647c7",
            "name": "AUTHENTICATION",
            "decision": {
                "type": "REJECTED",
                "details": {
                    "label": "REJECTED"
                },
                "reasons": [
                    {
                        "label": "FACE_INVALID_DIGITAL_COPY",
                        "type": "REJECTED"
                    }
                ]
            },
            "capabilities": [
                {
                    "id": "1bd548ce-81bc-4f99-abbc-c4fe39b0ee1f",
                    "category": "authentication"
                }
            ],
            "capabilityIds": [
                "1bd548ce-81bc-4f99-abbc-c4fe39b0ee1f"
            ]
        }
    ]
}
````

  </TabItem>
  <TabItem value="PassedSTANDARD" label="Steps_PASSED">
  ```json
{
    "steps": [
        {
            "id": "1c11905f-7667-4094-ab89-6846597ce990",
            "name": "AUTHENTICATION",
            "decision": {
                "type": "PASSED",
                "details": {
                    "label": "PASSED"
                }
            },
            "capabilities": [
                {
                    "id": "78c51e8f-7378-4882-a4a5-e594b8906c94",
                    "category": "authentication"
                }
            ],
            "capabilityIds": [
                "78c51e8f-7378-4882-a4a5-e594b8906c94"
            ]
        }
    ]
}
```
  </TabItem>
</Tabs>

## Decision Details Labels

:::note
When a **WARNING** result is returned, we recommend allowing the user to retry (up to 3 attempts).  
In contrast, if the result is **REJECTED**, retries should not be offered.
:::

| Decision Type | Label                        | Description                                                                                                          |
| ------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED   | Required data from another capability is not available.                                                              |
| NOT_EXECUTED  | TECHNICAL_ERROR              | A technical error prevented the capability from executing.                                                           |
| PASSED        | OK                           | The end user is the same person who previously uploaded credentials under the same account.                          |
| WARNING       | FACE_UNCLEAR_QUALITY         | The detected face does not meet the required quality standards for reliable processing.                              |
| WARNING       | FACE_UNCLEAR_MISSING_FACE    | A face does not appear in the selfie, making authentication impossible.                                              |
| WARNING       | FACE_UNCLEAR_PARTIAL         | The face is only partially visible in the selfie, leading to an authentication failure.                              |
| REJECTED      | FAILED                       | The end user is not the same person who previously uploaded credentials under the same account.                      |
| REJECTED      | FACE_INVALID_LIVENESS        | Liveness cannot be determined, making authentication invalid.                                                        |
| REJECTED      | FACE_INVALID_NO_MOTION       | The selfie does not show any facial features or eye movement, indicating the absence of a live person.               |
| REJECTED      | FACE_INVALID_SIMILARITY      | The faces in the enrolled data and the provided selfie do not match, leading to authentication failure.              |
| REJECTED      | FACE_MANIPULATED_IMAGE       | The selfie provided for authentication appears to be digitally altered or manipulated.                               |
| REJECTED      | FACE_MANIPULATED_PHOTOCOPY   | The selfie was captured from a paper printout, indicating a spoofing attempt.                                        |
| REJECTED      | FACE_INVALID_DIGITAL_COPY    | The selfie was captured from another screen (e.g., a mobile phone or computer), invalidating authentication.         |
| REJECTED      | FACE_INVALID_CAMERA          | The selfie was captured using a suspicious or untrusted camera device, invalidating authentication.                  |
| WARNING       | FACE_INVALID_MULTIPLE_PEOPLE | More than one face appears in the selfie, preventing single-user authentication.                                     |
| REJECTED      | FACE_INVALID_AGE_COMPARISON  | There is a significant mismatch between the estimated age from the selfie and the provided/enrolled age data.        |
| REJECTED      | FACE_MANIPULATED_MASKS       | The selfie appears to be a spoof attempt using physical artifacts such as silicone masks, 3D models, or latex masks. |
| REJECTED      | FACE_INVALID_PERSON_SWITCH   | More than one person appears in the liveness journey.                                                                |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

## Data

| Key    | Type   | Description                                                                                                                                              |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | The service that is used. Possible values: <ul> <li> JUMIO_PREMIUM (requires additional configuration for your tenant)</li> <li>JUMIO_STANDARD</li></ul> |

---

# Watchlist Screening

https://documentation.jumio.ai/docs/references/capabilities/watchlist

# Watchlist Screening

The Watchlist Screening capability screens users against global and regional sanctions and watchlists, PEPs.

## Prerequisite (Optional)

The [Creating or Updating Accounts](../../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) request body may include a WatchlistScreening object that includes a searchProfile. If used this value will override the default value configured in the Watchlist Screening settings. Consult your Jumio Account Manager for additional information.

Example WatchlistScreening Object

```
"capabilities":{
   "watchlistScreening": {
       "searchProfile": "abcd1234-xx11-yy22-zz33-a1b2-a1b2c3d4e5f6"
   }
}
```

#### Dependencies

Watchlist Screening is typically used with the ID or IDIV services. In those situations, the required data is extracted from the uploaded [ID](../../references/credentials/#id) credential, which requires these capabiities:

- [Usability](../../references/capabilities/usability)
- [Extraction](../../references/capabilities/extraction)
- [Image Checks](../../references/capabilities/image-checks)

## Prepared Data

Watchlist Screening can also be used as a standalone service by providing the following values as [Prepared Data](../../references/credentials/#prepared-data):

| Key               | Type   | Mandatory | Description                              |
| ----------------- | ------ | --------- | ---------------------------------------- |
| `address.country` | string | no        | Country should be ISO Alpha 3 Code only. |
| `dateOfBirth`     | string | no        | Date of birth in YYYY-MM-DD format only. |
| `firstName`       | string | Yes       | End user's first name.                   |
| `lastName`        | string | Yes       | End user's last name.                    |

### Decision Details Labels

| Decision Type | Label                      | Description                                             |
| ------------- | -------------------------- | ------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Required data from another capability is not available. |
| NOT_EXECUTED  | TECHNICAL_ERROR            | An error prevented execution.                           |
| NOT_EXECUTED  | NOT_ENOUGH_DATA            | Not enough data to make a decision.                     |
| NOT_EXECUTED  | VALIDATION_FAILED          | Validation failed during processing.                    |
| NOT_EXECUTED  | INVALID_MERCHANT_SETTINGS  | Invalid merchant settings detected.                     |
| NOT_EXECUTED  | NO_VALID_ID_CREDENTIAL     | No valid ID credential provided.                        |
| NOT_EXECUTED  | EXTRACTION_NOT_DONE        | Data extraction was not performed.                      |
| PASSED        | OK                         | The end user was not found on any watchlists.           |
| WARNING       | ALERT                      | The end user was found on one or more watchlists.       |

:::tip
For an overview of how Jumio handles PASSED, WARNING across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

### Data

| Key               | Type    | Description                                                         |
| ----------------- | ------- | ------------------------------------------------------------------- |
| `searchDate`      | string  | Timestamp (UTC) of the response. Format: `YYYY-MM-DDThh:mm:ss.SSSZ` |
| `searchStatus`    | string  | Possible values: `SUCCESS`, `NOT_DONE`, `ERROR`                     |
| `searchId`        | string  | Only if `searchStatus` = `SUCCESS`                                  |
| `searchReference` | string  | Only if `searchStatus` = `SUCCESS`                                  |
| `searchResultUrl` | string  | Only if `searchStatus` = `SUCCESS`                                  |
| `searchResults`   | integer | Only if `searchStatus` = `SUCCESS`                                  |

---

# Classification

https://documentation.jumio.ai/docs/references/capabilities/classification

# Classification

The classification capability provides details about the document type identified during the classification process. Additional information stored about the document, such as the first issue date, material type, or whether the document is handwritten, can be accessed via the Retrieval API.

This allows businesses to streamline their operations, for example, by filtering out specific types of documents from their workflows, resulting in more efficient document processing.

## Data

| Key                   | Type    | Description                                                                                                                                                                                                                                                                                                    |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`             | string  | The country that issued the document. Can be any ISO 3166-1 alpha-3 country code, and XKX for Kosovo. Examples: USA, AUT, DEU, FRA                                                                                                                                                                             |
| `state`               | string  | Possible values: Last two characters of ISO 3166-2:US state code, Last 2-3 characters of ISO 3166-2:AU state code, Last two characters of ISO 3166-2:CA state code, ISO 3166-1 country name, XKX (Kosovo), Free text if it can't be mapped to a state/country code                                             |
| `type`                | string  | Possible values include: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED                                                                                                                                                                                                                                 |
| `subType`             | string  | Possible values if `type = ID_Card`: NATIONAL_ID, CONSULAR_ID, ELECTORAL_ID, RESIDENT_PERMIT_ID, TAX_ID, STUDENT_ID, PASSPORT_CARD_ID, MILITARY_ID, PUBLIC_SAFETY_ID, HEALTH_ID, OTHER_ID, VISA, UNKNOWN, MULTI_PURPOSE_ID, PROFESSIONAL_ID, PUBLIC_SAFETY_ID, CITIZENSHIP_ID, SERVICES_ID, SOCIAL_SECURITY_ID |
| `printedDocumentName` | string  | Name as printed on the ID document                                                                                                                                                                                                                                                                             |
| `firstIssueDate`      | string  | Date when the ID was initially issued in YYYY-MM-DD format                                                                                                                                                                                                                                                     |
| `lastIssueDate`       | string  | The most recent date the ID was reissued in YYYY-MM-DD format                                                                                                                                                                                                                                                  |
| `notValidAfterDate`   | string  | The expiration date after which the ID is no longer valid in YYYY-MM-DD format                                                                                                                                                                                                                                 |
| `hasCryptoChip`       | boolean | If the document has a crypto chip available                                                                                                                                                                                                                                                                    |
| `isFoldable`          | boolean | If the document is foldable                                                                                                                                                                                                                                                                                    |
| `isHandwritten`       | boolean | If the document is handwritten                                                                                                                                                                                                                                                                                 |
| `layout`              | string  | Layout of the ID document                                                                                                                                                                                                                                                                                      |
| `material`            | string  | Material of the ID document                                                                                                                                                                                                                                                                                    |

## Decision Details Labels

| Decision Type | Label                      | Description                                                           |
| ------------- | -------------------------- | --------------------------------------------------------------------- |
| PASSED        | OK                         | The document metadata for classification was successfully identified. |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Required data from another capability is not available.               |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

---

# Cross Transaction Risk (CTR)

https://documentation.jumio.ai/docs/references/capabilities/ctr

# Cross Transaction Risk (CTR)

The Cross Transaction Risk (CTR) capability provides insights by comparing face, ID extracted data, and ID images from current transactions to those from prior transactions. The feature includes three types of matches:

1. **ID Data Matched Transactions**
   The Cross Transaction Risk (CTR) capability compares data extracted from an ID credential with previous transactions. If an ID with the same data was used in previous transactions, it returns the transaction IDs along with counts of those transactions categorized as high, medium, or low risk.

2. **Face Matched Transactions**
   The Cross Transaction Risk (CTR) capability compares Faces extracted from an ID credential and obtained from the Selfie with faces from previous transactions. If the same face was detected in prior transactions, it returns the transaction IDs and counts how many of those transactions were categorized as risk high, medium, or low.

3. **ID Image Matched Transactions**
   The Cross Transaction Risk (CTR) capability compares image parts (e.g. background) extracted from an ID or Selfie credential. If similar image parts were detected in prior transactions, it returns the transaction IDs and counts how many of those transactions were categorized as risk high, medium, or low.

Contact [Jumio Support](https://support.jumio.com/s/) if you require additional information or are interested in enabling the feature for your account.

## Output

Depending on your tenant configuration, CTR may return match statistics distributed across the following for each of the Match Types described above:

- **Network Transactions:** This includes all matching transactions for the same tenant where the current transaction is processed.
- **Associated Network Transactions:** Includes all matching transactions for other “connected” tenants under the same Customer account where the current Transaction is processed.
- **Global Network Transactions:** Excluding Network and Associated Network transactions, this covers all transactions part of Jumio's Cross-Customer Network, with end-user consent for data sharing and usage. Also, refer [End-User Consent to Collect Personal Data](/docs/developer-resources/API/end-user-consent)

Each of these Networks provides distribution of Matched Transactions across different risk levels, i.e., High, Medium, and Low Risk, along with Total Matched Transactions counts.

![Total count](image/ID.png)

Overall CTR Decision is also shared, refer the table [below](#decision-details-labels).

When using the Jumio Portal, within the Transaction Details page, you can also jump to CTR, which are part of the same Tenant (Network), and see CTR, which are part of Connected Tenants (Associated Network).
When using Jumio Retrieval Response, you also receive individual matched Transaction IDs from Network and Associated Network, along with the Earliest and Latest Transaction timestamps, checkout the [response](#response) section below.

![Matching Transaction](image/MT.png)

## Use in Rules

Due to different risk appetites and use cases that can be built around CTR, by default, the output is informational and doesn’t participate in Transaction scoring.

However, the output of CTR can be used to create rules using overall Summary Statistics or Individual Network and/or Risk Level Statistics to have better control of the outcome and treatment of current transactions.

Also, check: [Rules Management](../../portals/rules-management/rulesManagement)

#### Dependencies

- [Usability](/docs/references/capabilities/usability)
- [Extraction](../../references/capabilities/extraction)
- [Image Checks](../../references/capabilities/image-checks)

#### Supported Credentials

- [ID](../../references/credentials/#id)
- [Selfie](../../references/credentials/#selfie)

## Response

Response data is available for transactions that include the CTR capability. For information on transaction data see [this](/docs/developer-resources/retrieval).

<details>
<summary>Example Response </summary>

```
{
    "capabilities": {
        "lookups": [
            {
                "id": "4b0b64e8-c82a-43a6-b134-ba0fe45cb660",
                "credentials": [
                    {
                        "id": "6f1ba96f-80ce-48cc-acbb-4f062af75aab",
                        "category": "ID",
                        "label": "ID"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "WARNING"
                    }
                },
                "data": {
                    "matchedTransactions": {
                        "totalHighRiskTransactions": 0,
                        "totalMediumRiskTransactions": 8,
                        "totalLowRiskTransactions": 1,
                        "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                        "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                        "network": {
                            "highRiskTransactions": 0,
                            "mediumRiskTransactions": 8,
                            "lowRiskTransactions": 1,
                            "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                            "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                            "transactions": [
                                "1e52256a-3985-4e05-a22b-72624c924396",
                                "15c55070-5069-4e1c-84fe-04ec99781692",
                                "94eff29b-7987-4a5c-816d-4c97443e4e3e",
                                "930779a2-a2ef-43d2-b2a9-a8071cfe044a",
                                "cd763c51-9981-488d-8473-e22704a0ae50",
                                "d82831b2-ec7d-4654-a856-956143d2abc5",
                                "2073d47a-b1a0-4d72-a2d6-3b54319a5f32",
                                "e142b036-4b45-4747-aa0b-b4e2b5e9646b",
                                "c8f9d804-0f05-4a5d-83e8-bf53e8b0a191"
                            ]
                        },
                        "associatedNetwork": {
                            "highRiskTransactions": 0,
                            "mediumRiskTransactions": 0,
                            "lowRiskTransactions": 0,
                            "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                            "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                            "transactions": [
                                {
                                    "tenant1-guid": [
                                        "1e52256a-3985-4e05-a22b-72624c924396",
                                        "15c55070-5069-4e1c-84fe-04ec99781692"
                                    ]
                                },
                                {
                                    "tenant2-guid": [
                                        "94eff29b-7987-4a5c-816d-4c97443e4e3e",
                                        "930779a2-a2ef-43d2-b2a9-a8071cfe044a"
                                    ]
                                }
                            ]
                        },
                        "globalNetwork": {
                            "highRiskTransactions": 0,
                            "mediumRiskTransactions": 2,
                            "lowRiskTransactions": 1,
                            "earliestTransactionTime": "2023-12-17T13:26:43.802Z",
                            "latestTransactionTime": "2023-12-19T14:46:58.747Z"
                        }
                    }
                }
            },
            {
                "faceMatchedTransactions": {
                    "totalHighRiskTransactions": 0,
                    "totalMediumRiskTransactions": 8,
                    "totalLowRiskTransactions": 1,
                    "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                    "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                    "network": {
                        "highRiskTransactions": 0,
                        "mediumRiskTransactions": 8,
                        "lowRiskTransactions": 1,
                        "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                        "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                        "transactions": [
                            "1e52256a-3985-4e05-a22b-72624c924396",
                            "15c55070-5069-4e1c-84fe-04ec99781692",
                            "94eff29b-7987-4a5c-816d-4c97443e4e3e",
                            "930779a2-a2ef-43d2-b2a9-a8071cfe044a",
                            "cd763c51-9981-488d-8473-e22704a0ae50",
                            "d82831b2-ec7d-4654-a856-956143d2abc5",
                            "2073d47a-b1a0-4d72-a2d6-3b54319a5f32",
                            "e142b036-4b45-4747-aa0b-b4e2b5e9646b",
                            "c8f9d804-0f05-4a5d-83e8-bf53e8b0a191"
                        ]
                    },
                    "associatedNetwork": {
                        "highRiskTransactions": 0,
                        "mediumRiskTransactions": 0,
                        "lowRiskTransactions": 0,
                        "earliestTransactionTime": "2023-12-18T13:26:43.802Z",
                        "latestTransactionTime": "2023-12-19T14:46:58.747Z",
                        "transactions": [
                            {
                                "tenant1-guid": [
                                    "1e52256a-3985-4e05-a22b-72624c924396",
                                    "15c55070-5069-4e1c-84fe-04ec99781692"
                                ]
                            },
                            {
                                "tenant2-guid": [
                                    "94eff29b-7987-4a5c-816d-4c97443e4e3e",
                                    "930779a2-a2ef-43d2-b2a9-a8071cfe044a"
                                ]
                            }
                        ]
                    },
                    "globalNetwork": {
                        "highRiskTransactions": 0,
                        "mediumRiskTransactions": 2,
                        "lowRiskTransactions": 1,
                        "earliestTransactionTime": "2023-12-17T13:26:43.802Z",
                        "latestTransactionTime": "2023-12-19T14:46:58.747Z"
                    }
                }
            }
        ]
    }
}
```

</details>

### Decision Details Labels

| Decision Type | Label                      | ID  | Description                                                                                                                |
| ------------- | -------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------- |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | X   | Required data is not available. For example, if the ID did not pass Usability or if the data was not able to be extracted. |
| NOT_EXECUTED  | TECHNICAL_ERROR            | X   | The service encountered an error and was unable to process the request.                                                    |
| PASSED        | OK                         | X   | None of the CTR have medium or high risk.                                                                                  |
| REJECTED      | REJECTED                   | X   | Any CTR is high risk.                                                                                                      |
| WARNING       | WARNING                    | X   | Maximum risk of any CTR is medium risk.                                                                                    |

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](./#how-jumio-handles-results).
:::

### Data

The datablock includes top-level `matchedTransactions`, `faceMatchedTransactions` and `imageMatchedTransactions` objects.

#### matchedTransactions, faceMatchedTransactions and imageMatchedTransactions fields

| Key                           | Type            | Description                                                                                                                                                                |
| ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalHighRiskTransactions`   | integer         | 0 or any positive integer. The total number of high-risk transactions across all included networks.                                                                        |
| `totalMediumRiskTransactions` | integer         | 0 or any positive integer. The total number of medium-risk transactions across all included networks.                                                                      |
| `totalLowRiskTransactions`    | integer         | 0 or any positive integer. The total number of low-risk transactions across all included networks.                                                                         |
| `earliestTransactionTime`     | string dateTime | [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the oldest matching transaction.      |
| `latestTransactionTime`       | string dateTime | [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the most recent matching transaction. |
| `network`                     | object          | See [network](#network) fields.                                                                                                                                            |
| `associatedNetwork`           | object          | See [associatedNetwork](#associatednetwork) fields.                                                                                                                        |
| `globalNetwork`               | object          | See [globalNetwork](#globalnetwork) fields.                                                                                                                                |

#### network

This includes all matching transactions for the same tenant where the current transaction is processed.

| Key                           | Type            | Description                                                                                                                                                                |
| ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalHighRiskTransactions`   | integer         | 0 or any positive integer. The total number of high-risk transactions belonging to the same tenant.                                                                        |
| `totalMediumRiskTransactions` | integer         | 0 or any positive integer. The total number of medium-risk transactions belonging to the same tenant.                                                                      |
| `totalLowRiskTransactions`    | integer         | 0 or any positive integer. The total number of low-risk transactions belonging to the same tenant.                                                                         |
| `earliestTransactionTime`     | string dateTime | [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the oldest matching transaction.      |
| `latestTransactionTime`       | string dateTime | [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the most recent matching transaction. |
| `transactions`                | array           | An array of strings with the transaction IDs of the matching transactions.                                                                                                 |

#### associatedNetwork

Includes all matching transactions for other “connected” tenants under the same Customer account where the current Transaction is processed.

| Key                           | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalHighRiskTransactions`   | integer         | 0 or any positive integer. The total number of high-risk transactions across the associated network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `totalMediumRiskTransactions` | integer         | 0 or any positive integer. The total number of medium-risk transactions across the associated network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `totalLowRiskTransactions`    | integer         | 0 or any positive integer. The total number of low-risk transactions across the associated network.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `earliestTransactionTime`     | string dateTime | [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the oldest matching transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `latestTransactionTime`       | string dateTime | [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the most recent matching transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `transactions`                | array           | An array of objects containing the matching transactions from each tenant in the associated network. Each item in the array uses the Merchant Guid as the key with the matching transactions as the value. The Merchant Guid is the unique identifier for the tenant and can be found in the [Jumio Portal Explorer](../../portals/explorer/viewing-transaction-details). If the Merchant Guid column is not visible in the Transactions table you can click Columns to add it. Also checkout [Show or Hide Columns in the Explorer](../../portals/explorer/work_with_transaction_table#show-or-hide-columns-in-the-explorer) |

#### globalNetwork

Excluding Network and Associated Network transactions, this covers all transactions part of Jumio's Cross-Customer Network, and for which consent has been obtained from the end user.

| Key                           | Type            | Description                                                                                                                                                                |
| ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `totalHighRiskTransactions`   | integer         | 0 or any positive integer. The total number of high-risk transactions across the global network.                                                                           |
| `totalMediumRiskTransactions` | integer         | 0 or any positive integer. The total number of medium-risk transactions across the global network.                                                                         |
| `totalLowRiskTransactions`    | integer         | 0 or any positive integer. The total number of low-risk transactions across the global network.                                                                            |
| `earliestTransactionTime`     | string dateTime | [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the oldest matching transaction.      |
| `latestTransactionTime`       | string dateTime | [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format of the most recent matching transaction. |

```

```

---

# Risk Signals

https://documentation.jumio.ai/docs/references/riskSignals/overviewRiskSignals

# What are Risk Signals ?

**Risk Signals** are supplementary services designed to enhance the functionality of standard workflows by providing additional layers of verification and security. These signals help verify user information, assess potential risks, and ensure compliance with regulatory requirements. Examples include address validation, device risk assessment, global identity checks, and various forms of data verification, such as email, phone, or government database checks.

However, the Risk Signals are treated like capabilities and are triggered automatically when the necessary information is available.
While Risk Signals do not have strict dependencies, they rely on specific input Credentials depending on the context:

- DATA Credentials typically provide sufficient input for most risk signals.
- SELFIE Credentials are required when the signal involves biometric verification.
- In some workflows, input is derived from extraction capabilities, which are triggered by ID or DOCUMENT Credentials.

The way these signals are applied ultimately depends on the workflow configuration, which defines how Credentials are used and how signals interact with other capabilities.

The Risk Signal services include:

<details>
  <summary>[Address Services](./addressValidation/addressValidatity)</summary>

- [Address Check](./addressValidation/addressValidatity)
- [Proof of Residency](./addressValidation/addressProof)
</details>

<details>
  <summary>[Department of Motor Vehicles Check](./motorVehicleCheck)</summary>

- [Department of Motor Vehicles Check](./motorVehicleCheck)
</details>

<details>
  <summary>[Device Check](./deviceRiskCheck/deviceRisk)</summary>

- [Web SDK](./deviceRiskCheck/deviceRiskwithWebSDK)
- [Mobile SDK](eKYCcheck.md/deviceRiskCheck/deviceRiskwithMobileSDK)
- [Rest API](./deviceRiskCheck/deviceRiskwithRestAPI)
</details>

<details>
  <summary>[Email Check](./emailVerification)</summary>

- [Email Check](./emailVerification)
</details>

<details>
  <summary>[Government Database Checks](./govDatabaseCheck/)</summary>

- [Government Database Checks](./govDatabaseCheck/)
</details>

<details>
  <summary>[Phone Number Check](./phoneVerification)</summary>

- [Phone Number Check](./phoneVerification)
</details>

<details>
  <summary>[SSN Check](./ssnVerification)</summary>

- [SSN Check](./ssnVerification)
</details>

<details>
  <summary>[Geo IP Check](./geoIPVerification)</summary>

- [Geo IP Check](./geoIPVerification)
</details>

<details>
  <summary>[eKYC Check](./eKYCcheck)</summary>

- [eKYC Check](./eKYCcheck)
</details>

:::tip
For an overview of how Jumio handles PASSED, WARNING, and REJECTED across all capabilities, see [How Jumio Handles Results](#).
:::

---

# Address Validation

https://documentation.jumio.ai/docs/references/riskSignals/addressValidation/address-validation-overview

# Address Services

Address Services verify whether the address extracted from a government-issued ID (such as a passport, driver’s license, or ID card) exists in the real world. Jumio validates the address against trusted data sources (e.g., USPS, Royal Mail) to confirm its existence and ensure proper formatting based on regional standards. This service includes two components: **Address Check & Credentials** and **Proof of Residency**.

---

# Address Check

https://documentation.jumio.ai/docs/references/riskSignals/addressValidation/addressValidatity

# Address Check

Address Validation determines if the address extracted from a government-issued ID (e.g. passport, driver’s license, ID card) exists in the real world. Jumio checks the address against a number of trusted data sources (e.g. USPS, Royal Mail) to properly format and ensure that the address exists in a given jurisdiction.

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

| **Key**                  | **Type**  | **Mandatory**                                                             | **Description**                                        |
| ------------------------ | --------- | ------------------------------------------------------------------------- | ------------------------------------------------------ |
| **firstName**            | string    | No                                                                        | First name of the subject.                             |
| **middleName**           | string    | No                                                                        | Middle name of the subject.                            |
| **lastName**             | string    | No                                                                        | Last name of the subject.                              |
| **dateOfBirth**          | LocalDate | No                                                                        | Date of birth in `YYYY-MM-DD` format only.             |
| **socialSecurityNumber** | string    | No                                                                        | SSN of the subject.                                    |
| **personalNumber**       | string    | Must include one of: `socialSecurityNumber`, `personalNumber`, `idNumber` | For Brazil, this will be the CPF number.               |
| **address**              | Object    | Yes                                                                       | Only the fields mentioned are required                 |
| **address.line1**        | string    | Yes                                                                       | Address line 1 (Street address)                        |
| **address.line2**        | string    | No                                                                        | Address line 2 (Apartment, Suite, etc.)                |
| **address.city**         | string    | Yes                                                                       | City of residence as it appears on the ID.             |
| **address.postalCode**   | string    | Yes                                                                       | Postal or zip code.                                    |
| **address.subdivision**  | string    | Yes                                                                       | City subdivision of residence as it appears on the ID. |
| **address.country**      | string    | Yes                                                                       | Country in ISO-3166-1 Alpha-3 Code format.             |
| **id.idNumber**          | string    | No                                                                        | Primary ID number on the identity document.            |

### Example Prepared Data Body

```
{
    "firstName": "John",
    "middleName": "",
    "lastName": "Smith",
    "dateOfBirth": "1972-11-16",
    "socialSecurityNumber": "123456789",
    "address": {
        "line1": "12345 SW Address Ln",
        "postalCode": "97201",
        "city": "Portland",
        "subdivision": "OR",
        "country": "USA"
    }
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see [this](/docs/developer-resources/retrieval).

```
"capabilities": {
   "addressValidation": [{
      "id": "f72b219b-1878-4631-82e3-a16340dfda7a",
      ...
      "decision": {
         "type": "WARNING",
         "details": {
            "label": "ALERT"
         }
       },
       "data": {
          "reasonMessage": "Administrative Area Change, SubAdministrative Area Change,Unknown Street,Locality Partial,Geocoded to Community Level"
       }
   }]
```

### Decision Details Labels

| Decision Type | Label               | Description                                                                                                  |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| PASSED        | OK                  | Provided data matches datasource.                                                                            |
| REJECTED      | DENY                | Provided data does not match datasource.                                                                     |
| WARNING       | ALERT               | Provided data partially matches datasource.                                                                  |
| NOT_EXECUTED  | UNSUPPORTED_COUNTRY | Provided address.country value is not supported.                                                             |
| NOT_EXECUTED  | TECHNICAL_ERROR     | Verify the provided data is correct and retry, or contact [Support](https://www.jumio.com/contact/support/). |

### Data: Reason Messages

#### Address Validation Messages

<details>
<summary>Descriptions</summary>
| **Short Description**       | **Long Description**                                                                                                                                              |
|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Administrative Area Partial** | The address has been partially verified to the Administrative Area (State) Level, which is NOT the highest level possible with the reference data.               |
| **Locality Partial**         | The address has been partially verified to the Locality (City) Level, which is NOT the highest level possible with the reference data.                            |
| **Thoroughfare Partial**     | The address has been partially verified to the Thoroughfare (Street) Level, which is NOT the highest level possible with the reference data.                      |
| **Premise Partial**          | The address has been partially verified to the Premise (House or Building) Level, which is NOT the highest level possible with the reference data.                |
| **Administrative Area Full** | The address has been verified to the Administrative Area (State) Level, which is the highest level possible with the reference data.                              |
| **Locality Full**            | The address has been verified to the Locality (City) Level, which is the highest level possible with the reference data.                                         |
| **Thoroughfare Full**        | The address has been verified to the Thoroughfare (Street) Level, which is the highest level possible with the reference data.                                   |
| **Premises Full**            | The address has been verified to the Premise (House or Building) Level, which is the highest level possible with the reference data.                             |
| **SubPremises Full**         | The address has been verified to the SubPremise (Suite) or PO Box Level, which is the highest level possible with the reference data.                            |

</details>

#### Address Error Messages

<details>
<summary>Descriptions</summary>

| **Short Description**               | **Long Description**                                                                                                                             |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Postal Code Error/General Error** | The address could not be verified at least up to the postal code level.                                                                          |
| **Unknown Street**                  | Could not match the input street to a unique street name. Either no matches or too many matches found.                                           |
| **Component Mismatch Error**        | The combination of directionals (N, E, SW, etc.) and the suffix (AVE, ST, BLVD) is not correct and produces multiple possible matches.           |
| **Multiple Match**                  | The address was matched to multiple records. There is not enough information available in the address to break the tie between multiple records. |
| **Sub Premise Number Invalid**      | An address element after the house number, in most cases the sub-premise, was not valid.                                                         |
| **Sub Premise Number Missing**      | An address element after the house number, in most cases the sub-premise, was missing.                                                           |
| **Premise Number Invalid**          | The premise (house or building) number for the address is not valid.                                                                             |
| **Premise Number Missing**          | The premise (house or building) number for the address is missing.                                                                               |
| **Box Number Invalid**              | The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is invalid.                                                      |
| **Box Number Missing**              | The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is missing.                                                      |
| **PMB Number Missing**              | US Only. The address is a Commercial Mail Receiving Agency (CMRA), and the Private Mail Box (PMB or #) number is missing.                        |

</details>

## Portal View

Open a transaction in the Portal to review the response. The risk signal is labeled Address Validation as shown in the figure below.

![Portal](./img/PortalView_RS.png)

## Supported Countries

The following countries are supported by Address Validation today. The Address and Geocoding fields are further classified as follows

| Verification Level | GeoCode Level            |
| ------------------ | ------------------------ |
| AV-2               | G-2 Locality             |
| AV-3               | G-3 Thoroughfare         |
| AV-4               | G-4 Interpolated Rooftop |
| AV-5               | G-5 Rooftop              |

<details>
<summary>Supported Countries</summary>

| Country/Territory Name       | ISO2 | Region | Address | Geocoding |
| ---------------------------- | ---- | ------ | ------- | --------- |
| Aland Islands                | AX   | WE     | AV-4    | G-4       |
| Albania                      | AL   | EE     | AV-3    | G-2       |
| American Samoa               | AS   | NA     | AV-4    | G-3       |
| Andorra                      | AD   | WE     | AV-4    | G-5       |
| Angola                       | AO   | MEA    | AV-3    | G-4       |
| Argentina                    | AR   | SA     | AV-4    | G-4       |
| Australia                    | AU   | APA    | AV-5    | G-5       |
| Austria                      | AT   | WE     | AV-5    | G-5       |
| Azerbaijan                   | AZ   | EE     | AV-4    | G-4       |
| Bahamas                      | BS   | CAC    | AV-4    | G-4       |
| Bahrain                      | BH   | MEA    | AV-4    | G-4       |
| Bangladesh                   | BD   | ASIA   | AV-4    | G-4       |
| Belarus                      | BY   | EE     | AV-3    | G-4       |
| Belgium                      | BE   | WE     | AV-4    | G-5       |
| Bermuda                      | BM   | CAC    | AV-4    | G-4       |
| Bosnia and Herzegovina       | BA   | EE     | AV-4    | G-5       |
| Botswana                     | BW   | MEA    | AV-4    | G-4       |
| Brazil                       | BR   | SA     | AV-5    | G-5       |
| Brunei Darussalam            | BN   | ASIA   | AV-4    | G-4       |
| Bulgaria                     | BG   | EE     | AV-4    | G-5       |
| Canada                       | CA   | NA     | AV-5    | G-5       |
| Cayman Islands               | KY   | CAC    | AV-4    | G-4       |
| Chile                        | CL   | SA     | AV-4    | G-4       |
| Colombia                     | CO   | SA     | AV-4    | G-4       |
| Costa Rica                   | CR   | CAC    | AV-3    | G-3       |
| Croatia                      | HR   | EE     | AV-4    | G-4       |
| Cyprus                       | CY   | WE     | AV-4    | G-4       |
| Czech Republic               | CZ   | EE     | AV-4    | G-5       |
| Denmark                      | DK   | WE     | AV-4    | G-5       |
| Ecuador                      | EC   | SA     | AV-4    | G-4       |
| Egypt                        | EG   | MEA    | AV-4    | G-5       |
| Estonia                      | EE   | EE     | AV-4    | G-5       |
| Eswatini                     | SZ   | MEA    | AV-3    | G-4       |
| Finland                      | FI   | WE     | AV-4    | G-4       |
| France                       | FR   | WE     | AV-5    | G-5       |
| French Guiana                | GF   | SA     | AV-4    | G-5       |
| Germany                      | DE   | WE     | AV-5    | G-5       |
| Gibraltar                    | GI   | WE     | AV-4    | G-4       |
| Greece                       | GR   | WE     | AV-4    | G-4       |
| Guadeloupe                   | GP   | CAC    | AV-4    | G-5       |
| Guam                         | GU   | NA     | AV-5    | G-3       |
| Guatemala                    | GT   | CAC    | AV-3    | G-4       |
| Guernsey                     | GG   | WE     | AV-5    | G-4       |
| Hong Kong                    | HK   | ASIA   | AV-5    | G-4       |
| Hungary                      | HU   | EE     | AV-4    | G-5       |
| Iceland                      | IS   | WE     | AV-4    | G-4       |
| India                        | IN   | ASIA   | AV-4    | G-5       |
| Indonesia                    | ID   | ASIA   | AV-4    | G-5       |
| Ireland                      | IE   | WE     | AV-5    | G-4       |
| Isle of Man                  | IM   | WE     | AV-5    | G-4       |
| Israel                       | IL   | MEA    | AV-4    | G-5       |
| Italy                        | IT   | WE     | AV-4    | G-5       |
| Japan                        | JP   | ASIA   | AV-5    | G-5       |
| Jersey                       | JE   | WE     | AV-5    | G-4       |
| Jordan                       | JO   | MEA    | AV-4    | G-4       |
| Kazakhstan                   | KZ   | EE     | AV-4    | G-5       |
| Korea, Republic of           | KR   | ASIA   | AV-5    | G-4       |
| Kuwait                       | KW   | MEA    | AV-3    | G-3       |
| Latvia                       | LV   | EE     | AV-4    |           |
| Lebanon                      | LB   | MEA    | AV-4    | G-4       |
| Liechtenstein                | LI   | WE     | AV-4    | G-5       |
| Lithuania                    | LT   | EE     | AV-4    | G-4       |
| Luxembourg                   | LU   | WE     | AV-4    | G-5       |
| Macao                        | MO   | ASIA   | AV-4    | G-4       |
| Macedonia                    | MK   | EE     | AV-4    | G-5       |
| Malaysia                     | MY   | ASIA   | AV-4    | G-5       |
| Malta                        | MT   | WE     | AV-4    | G-5       |
| Marshall Islands             | MH   | NA     | AV-4    | G-3       |
| Martinique                   | MQ   | CAC    | AV-4    | G-5       |
| Mayotte                      | YT   | MEA    | AV-4    | G-5       |
| Mexico                       | MX   | NA     | AV-4    | G-4       |
| Micronesia                   | FM   | NA     | AV-4    | G-3       |
| Monaco                       | MC   | WE     | AV-4    | G-5       |
| Montenegro                   | ME   | EE     | AV-4    | G-4       |
| Morocco                      | MA   | MEA    | AV-4    | G-4       |
| Mozambique                   | MZ   | MEA    | AV-3    | G-4       |
| Namibia                      | NA   | MEA    | AV-4    | G-4       |
| Netherlands                  | NL   | WE     | AV-5    | G-5       |
| New Zealand                  | NZ   | APA    | AV-4    | G-4       |
| Nigeria                      | NG   | MEA    | AV-3    | G-4       |
| Northern Mariana Islands     | MP   | NA     | AV-4    | G-4       |
| Norway                       | NO   | WE     | AV-4    | G-4       |
| Oman                         | OM   | MEA    | AV-4    | G-4       |
| Palau                        | PW   | NA     | AV-4    | G-3       |
| Panama                       | PA   | CAC    | AV-4    | G-5       |
| Paraguay                     | PY   | SA     | AV-4    | G-4       |
| Peru                         | PE   | SA     | AV-4    | G-4       |
| Philippines                  | PH   | ASIA   | AV-4    | G-4       |
| Poland                       | PL   | EE     | AV-4    | G-5       |
| Portugal                     | PT   | WE     | AV-4    | G-4       |
| Puerto Rico                  | PR   | NA     | AV-5    | G-3       |
| Qatar                        | QA   | MEA    | AV-4    | G-4       |
| Réunion                      | RE   | MEA    | AV-4    | G-5       |
| Romania                      | RO   | EE     | AV-4    | G-5       |
| Russia                       | RU   | EE     | AV-5    | G-5       |
| Saint Barthélemy             | BL   | CAC    | AV-2    | G-4       |
| Saint Pierre and Miquelon    | PM   | NA     | AV-4    | G-5       |
| San Marino                   | SM   | WE     | AV-4    | G-4       |
| Saudi Arabia                 | SA   | MEA    | AV-4    | G-5       |
| Serbia                       | RS   | EE     | AV-4    |           |
| Singapore                    | SG   | ASIA   | AV-4    | G-5       |
| Slovakia                     | SK   | EE     | AV-4    | G-5       |
| Slovenia                     | SI   | EE     | AV-4    | G-4       |
| South Africa                 | ZA   | MEA    | AV-4    | G-5       |
| Spain                        | ES   | WE     | AV-4    | G-5       |
| Sri Lanka                    | LK   | ASIA   | AV-3    | G-4       |
| Suriname                     | SR   | SA     | AV-4    | G-4       |
| Sweden                       | SE   | WE     | AV-4    | G-4       |
| Switzerland                  | CH   | WE     | AV-4    | G-4       |
| Taiwan                       | TW   | ASIA   | AV-4    | G-5       |
| Thailand                     | TH   | ASIA   | AV-4    | G-5       |
| Tunisia                      | TN   | MEA    | AV-4    | G-4       |
| Turkey                       | TR   | EE     | AV-4    | G-5       |
| Ukraine                      | UA   | EE     | AV-4    | G-5       |
| United Arab Emirates         | AE   | MEA    | AV-4    | G-4       |
| United Kingdom               | GB   | WE     | AV-5    | G-5       |
| United States of America     | US   | NA     | AV-5    | G-5       |
| United States Virgin Islands | VI   | NA     | AV-5    | G-3       |
| Uruguay                      | UY   | SA     | AV-4    | G-4       |
| Vietnam                      | VN   | ASIA   | AV-4    | G-5       |
| Zimbabwe                     | ZW   | MEA    | AV-4    | G-4       |

</details>

### Geocode Status Messages

<details>
<summary>Descriptions</summary>
| **Short Description**               | **Long Description**                                                                                                                               |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| **Geocoded to Street Level**        | The record was coded to the street level (Zip+4 for US, full postal code for CA).                                                                 |
| **Geocoded to the Neighborhood Level** | The record was geocoded down to neighborhood level (Zip+2 for US).                                                                                |
| **Geocoded to Community Level**     | The record was coded to the community level (ZIP centroid for US, 3-digit postal code for CA).                                                    |
| **Geocoded to State Level**         | The record was geocoded to the state (administrative area) level.                                                                                 |
| **Geocoded to Rooftop Level**       | The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center.                       |
| **Geocoded to Interpolated Rooftop Level** | The record was geocoded down to the rooftop level using interpolation (educated estimations using street coordinates). The point may be in or close to the property boundaries. |
</details>

---

# Proof of Residency

https://documentation.jumio.ai/docs/references/riskSignals/addressValidation/addressProof

# Proof of Residency

Jumio Proof of Residency verifies that the physical address on an ID document exists by cross-checking it against government, credit, and commercial data sources worldwide. It then determines whether the person being verified actually resides at the extracted address.

## Supported Countries

The following countries are supported by Proof of Residency:

- **Australia**
- **Canada**
- **France**
- **Germany**
- **Italy**
- **Mexico**
- **Spain**
- **United Kingdom**
- **United States**

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

| Key        | Type   | Mandatory | Description                                                                         |
| ---------- | ------ | --------- | ----------------------------------------------------------------------------------- |
| firstName  | string | Yes       | First name of the subject.                                                          |
| middleName | string | No        | Middle name of the subject.                                                         |
| lastName   | string | Yes       | Last name of the subject.                                                           |
| address    | object | Yes       | Address that contains (address line, city, state, postalCode, subdivision, country) |

### Example Prepared Data Body

```
{
    "firstName": "Billy",
    "lastName": "Buck",
    "middleName": "Bob",
     "address": {
            "line1": "1835 ne",
            "postalCode": "95051",
            "city": "Malarkey",
            "state": "WA",
            "subdivision": "WA",
            "country": "USA"
       },
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see [View or Retrieve Workflow Transactions](../../../developer-resources/retrieval).

```
    "capabilities": {
        "proofOfResidency": [
            {
                "id": "debbccf1-b03f-425d-aa1b-771251dbc465",
                "credentials": [
                    {
                        "id": "07a5046c-21dd-436b-82c3-4fc0a94c636a",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "REJECTED",
                    "details": {
                        "label": "DENY"
                    }
                },
                "data": {
                    "reasonMessage": "No Name match to Address."
                }
            }
        ]
    }
```

| Decision Type | Label               | Description                                                                                                                                   |
| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| PASSED        | OK                  | Provided data matches the datasource.                                                                                                         |
| REJECTED      | DENY                | Provided data does not match the datasource.                                                                                                  |
| WARNING       | ALERT               | Provided data partially matches the datasource.                                                                                               |
| WARNING       | NOT_ENOUGH_DATA     | Provided data is insufficient to complete a full verification against DMV records. Please ensure all mandatory fields are properly filled in. |
| NOT_EXECUTED  | UNSUPPORTED_COUNTRY | Provided address.country value is not supported.                                                                                              |
| NOT_EXECUTED  | TECHNICAL_ERROR     | Verify the provided data is correct and retry, or contact [Support](https://www.jumio.com/contact/support/).                                  |

## Portal View

Open a transaction in the Portal to review the response. The risk signal is labeled Proof Of Residency as shown in the figure below.

<center> ![Portal View](./img/PortalView_AddressProof.png) </center>

---

# Department of Motor Vehicles Check

https://documentation.jumio.ai/docs/references/riskSignals/motorVehicleCheck

# Department of Motor Vehicles Check

The Jumio Department of Motor Vehicles (DMV) check is used to validate that a US driver’s license or ID card issued by the DMV is valid.

## Supported Credentials

The following values can be uploaded as [Prepared Data](../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

<details>

| Key                 | Type   | Mandatory | Description                                                                                                 |
| ------------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------- |
| firstName           | string | Yes       | First name of the subject.                                                                                  |
|                     |
| middleName          | string | No        | Middle name of the subject.                                                                                 |
|                     |
| lastName            | string | Yes       | Last name of the subject.                                                                                   |
|                     |
| dateOfBirth         | string | Yes       | Date of Birth in yyyy-MM-dd format only                                                                     |
| address.line1       | string | Yes       | Address line 1 (Street address)                                                                             |
| address.line2       | string | No        | Address line 2 (Apartment, Suite, etc.)                                                                     |
| address.city        | string | Yes       | City of residence as it appears on the Id.                                                                  |
| address.postalCode  | string | Yes       | Postal or zip code.                                                                                         |
| address.subdivision | string | Yes       | State name can be provided here. See [Supported States](../riskSignals/motorVehicleCheck#supported-states). |
| address.country     | string | Yes       | country should be ISO Alpha 3 Code only                                                                     |
| id.idNumber         | string | Yes       | number for ID being provided                                                                                |
| id.issuingDate      | string | No        | in YYYY-MM-DD format only                                                                                   |
| id.expiryDate       | string | No        | in YYYY-MM-DD format only                                                                                   |
| id.type             | string | Yes       | only possible values are: DRIVING_LICENSE, PERMIT, ID_CARD                                                  |

</details>

## Example Prepared Data Body

```
{
    "firstName": "J****",
    "middleName": "J****",
    "lastName": "****h",
    "dateOfBirth": "1972-**-1*",
    "address": {
        "line1": "***** SW Address Ln",
        "postalCode": "9***1",
        "city": "****",
        "subdivision": "OR",
        "country": "USA"
    },
    "id": {
        "idNumber": "0*****812",
        "type": "DRIVING_LICENSE",
        "issuingDate": "20**-01-**",
        "expiryDate": "20**-01-**"
    }
}
```

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see [this](/docs/developer-resources/retrieval).

```
"drivingLicenseVerification": [
            {
                "id": "bd91fa85-8ef8-42d2-a064-954a30c10ed6",
                "credentials": [
                    {
                        "id": "51c426f0-3e34-4c62-a552-85a73e9d52de",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "ALERT"
                    }
                },
                "data": {
                    "nameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "middleNameMatch": "MATCH",
                    "addressMatch": "NOT_MATCH",
                    "addressLine1Match": "NOT_MATCH",
                    "addressLine2Match": "NOT_MATCH",
                    "cityMatch": "MATCH",
                    "stateMatch": "MATCH",
                    "zipCodeMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "idNumberMatch": "MATCH",
                    "expiryDateMatch": "MATCH",
                    "issuingDateMatch": "MATCH"
                },
            }
```

### Decision Details Labels

| Decision Type | Label               | Description                                                                                                  |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| PASSED        | OK                  | Provided data matches DMV data.                                                                              |
| REJECTED      | DENY                | Provided data does not match DMV data.                                                                       |
| WARNING       | ALERT               | Provided data partially matches DMV data.                                                                    |
| NOT_EXECUTED  | UNSUPPORTED_COUNTRY | Provided address.country value is not supported. Must be USA.                                                |
| NOT_EXECUTED  | UNSUPPORTED_STATE   | Provided address.subdivision value is not supported. Must be a USA state listed below.                       |
| NOT_EXECUTED  | TECHNICAL_ERROR     | Verify the provided data is correct and retry, or contact [Support](https://www.jumio.com/contact/support/). |

### Data

<details>
<summary>Fields include </summary>
| Key                | Possible Values | Description                                          |
|--------------------|-----------------|------------------------------------------------------|
| nameMatch          | MATCH, NOT_MATCH | First and last name both match.                     |
| firstNameMatch     | MATCH, NOT_MATCH | First name matches.                                 |
| lastNameMatch      | MATCH, NOT_MATCH | Last name matches.                                  |
| middleNameMatch    | MATCH, NOT_MATCH | Middle name matches.                                |
| addressMatch       | MATCH, NOT_MATCH | All address values match.                           |
| addressLine1Match  | MATCH, NOT_MATCH | Line1 address value matches.                        |
| addressLine2Match  | MATCH, NOT_MATCH | Line2 address value matches.                        |
| cityMatch          | MATCH, NOT_MATCH | City address value matches.                         |
| stateMatch         | MATCH, NOT_MATCH | State address value matches.                        |
| zipCodeMatch       | MATCH, NOT_MATCH | Postal code address value matches.                  |
| dobMatch           | MATCH, NOT_MATCH | Date of birth matches.                              |
| idNumberMatch      | MATCH, NOT_MATCH | The number of the license, permit, or ID card matches. |
| expiryDateMatch    | MATCH, NOT_MATCH | Expiration date matches.                            |
| issuingDateMatch   | MATCH, NOT_MATCH | Issue date matches.                                 |

</details>

## Supported States

The following states are supported by our DMV check today. Currently, this is available in the USA only.

<details>
<summary>States include</summary>

| State                | Abbrv Code |
| -------------------- | ---------- |
| ALABAMA              | AL         |
| ARIZONA              | AZ         |
| ARKANSAS             | AR         |
| COLORADO             | CO         |
| CONNECTICUT          | CT         |
| DELAWARE             | DE         |
| DISTRICT OF COLUMBIA | DC         |
| FLORIDA              | FL         |
| GEORGIA              | GA         |
| HAWAII               | HI         |
| IDAHO                | ID         |
| ILLINOIS             | IL         |
| INDIANA              | IN         |
| IOWA                 | IA         |
| KANSAS               | KS         |
| KENTUCKY             | KY         |
| MAINE                | ME         |
| MARYLAND             | MD         |
| MASSACHUSETTS        | MA         |
| MICHIGAN             | MI         |
| MISSISSIPPI          | MS         |
| MISSOURI             | MO         |
| MONTANA              | MT         |
| NEBRASKA             | NE         |
| NEVADA               | NV         |
| NEW HAMPSHIRE        | NH         |
| NEW JERSEY           | NJ         |
| NEW MEXICO           | NM         |
| NORTH CAROLINA       | NC         |
| NORTH DAKOTA         | ND         |
| OHIO                 | OH         |
| OKLAHOMA             | OK         |
| OREGON               | OR         |
| RHODE ISLAND         | RI         |
| SOUTH CAROLINA       | SC         |
| SOUTH DAKOTA         | SD         |
| TENNESSEE            | TN         |
| TEXAS                | TX         |
| VERMONT              | VT         |
| VIRGINIA             | VA         |
| WASHINGTON           | WA         |
| WEST VIRGINIA        | WV         |
| WISCONSIN            | WI         |
| WYOMING              | WY         |

</details>

---

# Device Risk Check

https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRisk

# What is Device Risk Check?

Device Risk provides an overall risk & reputation assessment of the device used to initiate a transaction. Data about the device are captured and passed as a credential to be evaluated by the transaction workflow. How the device data is captured and uploaded depends on the integration channel:

- Integrations using the [Jumio Web Client](../../../developer-resources/web-client) do not require additional setup, as it comes pre-configured to support Device Risk.
- [Mobile apps](../deviceRiskCheck/deviceRiskwithMobileSDK) need to integrate with an SDK to generate a blackbox string containing the required device data, which should then be uploaded as a Prepared Data credential using the REST API.
- For integrations using the [Jumio Web SDK](../deviceRiskCheck/deviceRiskwithWebSDK), a reverse proxy is necessary to download required third-party scripts.
- Web applications that want to use Device Risk as a standalone service can acquire the device data as a blackbox string and upload it as Prepared Data via the [REST API](../deviceRiskCheck/deviceRiskwithRestAPI).

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see [this](/docs/developer-resources/retrieval).

`````
        "deviceRiskVerification": [
            {
                "id": "UUID",
                "credentials": [
                    {
                        "id": "UUID",
                        "category": "DATA",
                        "label": "DATA"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "MEDIUM_RISK"
                    }
                },
                "data": {
                    "deviceModel": "WINDOWS",
                    "deviceOS": "WINDOWS NT 6.1",
                    "browser": "CHROME",
                    "trueIP": "50.165.158.124",
                    "ipLocationCity": "COUNCIL BLUFFS",
                    "ipLocationCountry": "USA",
                    "ipLocationLatitude": "41.26192",
                    "ipLocationLongitude": "-95.86762",
                    "ipLocationRegion": "IOWA",
                    "metaDataAge": "381759890",
                    "deviceAlerts": [
                        "Country Mismatch",
                        "Accounts Per Device- 2 Max",
                        "Tz/Geo Mismatch- More Than 3",
                        "Accts Created Per Device- 2 in 30 days"
                    ],
                    "browserCookiesEnabled": true,
                    "browserLanguage": "EN-US",
                    "browserVersion": "35.0.1916.114",
                    "deviceFirstSeen": "2026-06-10T05:40:26.604Z",
                    "deviceScreen": "900X1600",
                    "isp": "COMCAST",
                    "flashEnabled": true,
                    "browserTimezone": "+06:00",
                    "deviceIsNew": false,
                    "statedIp": {
                        "ip": "4.193.78.102",
                        "isp": "MICROSOFT CORPORATION",
                        "ipLocation": {
                            "city": "SINGAPORE",
                            "country": "SGP",
                            "latitude": "1.28795",
                            "longitude": "103.85178",
                            "region": "CENTRAL SINGAPORE"
                        }
                    },
                    "deviceIdAlias": "410061316747938016"
                },
                ````
            }
        ]

`````

### Decision Details Labels

| Decision Type    | Label           | Description                                                                                                                  |
| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **PASSED**       | OK              | Device does not exhibit any known risk or fraud indicators.                                                                  |
| **REJECTED**     | DENY            | Device has been flagged as high-risk or associated with known fraudulent activity.                                           |
| **WARNING**      | ALERT           | Device exhibits suspicious behavior or patterns but is not conclusively high-risk.                                           |
| **NOT_EXECUTED** | TECHNICAL_ERROR | An error occurred during device risk evaluation. Verify input and retry, or contact [Support](https://support.jumio.com/s/). |

## Data

<details>
<summary>Data </summary>
| Key                   | Type             | Description                                                                                                                                                           |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| browser               | string           | Detected browser. eg Chrome Mobile, Chrome, Mobile Safari, Firefox, Safari.                                                                                           |
| browserCookiesEnabled | boolean          | Whether JavaScript cookies are enabled.                                                                                                                               |
| browserLanguage       | string           | Browser default language.                                                                                                                                             |
| browserTimezone       | string           | Browser timezone.                                                                                                                                                     |
| browserVersion        | string           | Browser version.                                                                                                                                                      |
| deviceAlerts          | array of strings | Messages indicating the reasons why a WARNING or REJECTED decision type was returned. See [Device Alerts](./deviceRisk#device-alerts).                                |
| deviceFirstSeen       | string           | Date/time the device was first seen by Iovation.                                                                                                                      |
| deviceIsNew           | boolean          | Whether the device has ever been seen by Iovation.                                                                                                                    |
| deviceModel           | string           | Device model name and model version. For Apple devices, this refers to the hardware identifier (such as iPhone6.1), not the public product model (such as iPhone 6s). |
| deviceOS              | string           | For Web, UserAgent header. eg "iOS", "Mac OS X", "Android", "Windows" or "Linux". For mobile SDKs it's constant "Android" or "iOS".                                   |
| deviceScreen          | string           | The screen resolution.                                                                                                                                                |
| flashEnabled          | boolean          | Whether Flash is enabled.                                                                                                                                             |
| ipLocationCity        | string           | City associated with the IP address.                                                                                                                                  |
| ipLocationCountry     | string           | Alpha-3 country code of the country associated with the IP address.                                                                                                   |
| ipLocationLatitude    | string           | Latitude associated with the IP address.                                                                                                                              |
| ipLocationLongitude   | string           | Longitude associated with the IP address.                                                                                                                             |
| ipLocationRegion      | string           | State/region name associated with the IP address.                                                                                                                     |
| isp                   | string           | Internet service provider of the stated IP address.                                                                                                                   |
| metaDataAge           | string           | Age of the blackbox, in seconds.                                                                                                                                      |
| statedIp              | string           | The stated IP address from the end-user's device. This can be an IPv4 or IPv6 address.                                                                                |
| trueIp                | string           | IP properties for the Real IP address.                                                                                                                                |
|deviceIdAlias|string|An alternate identifier assigned to the device by Iovation that can be used to recognize the same device across related transactions.|
</details>

## Device Alerts

<details>
<summary>Device Alerts include</summary>
| Alert                                   | Description                                                                                                                                                                                                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounts Per Device                     | Number of accounts associated to the same device.                                                                                                                                                                                                                 |
| Countries Per Device                    | Number of countries the device has been seen from.                                                                                                                                                                                                                |
| Device Not Provided                     | No blackbox is received, this could be due to direct action by the end user or an issue with the integration. The absence of a device ID can be correlated to increased risk in many cases.                                                                       |
| Device Risk Global                      | Looks at other devices in the Iovation network with similar characteristics to the device the transaction is coming from. Risk is determined when a minimum of 70% of those devices are associated with evidence of fraud at any of Iovation’s subscribers.       |
| Geolocation Mismatch                    | If the stated IP is different than the Real IP Iovation collects, this rule looks at the geographical location of each - define if difference is at Country, Region or City level.                                                                                |
| High Risk Country                       | Transactions sent from countries on a defined list will cause the rule to fire.                                                                                                                                                                                   |
| Invalid Blackbox                        | Blackbox cannot be decrypted or parsed. Usually this is an indication that there may be a problem with the integration with Iovation.                                                                                                                             |
| IP Address Risk                         | Risk assessment based on all devices seen at any of Iovation’s subscribers’ sites that have been seen with the same IP address. Risk is determined when a minimum of 70% of those devices are associated with evidence of fraud at any of Iovation’s subscribers. |
| IP Mismatch with ISP Exclusions                            | Triggered when the declared IP address does not align with the actual IP detected by Iovation. Common ISP have been excluded to not be effected by  Apple Private Relay, or traffic routed through CDN providers (e.g., Cloudflare, Fastly). |
| ISP Watch List                          | ISP is on a list of ISPs to watch for.                                                                                                                                                                                                                            |
| Jailbreak / Root Detected               | Device has been jailbroken (iOS devices) or rooted (Android devices).                                                                                                                                                                                             |
| Other Subscriber ATO Evidence           | Direct Account TakeOver evidence has been placed by other Iovation subscribers against the device.                                                                                                                                                                |
| Other Subscriber Cheating Evidence      | Direct or indirect Cheating evidence has been placed by other Iovation subscribers against the account or device.                                                                                                                                                 |
| Other Subscriber Financial Evidence     | Direct or indirect Financial evidence has been placed by other Iovation subscribers against the account or device.                                                                                                                                                |
| Other Subscriber ID Theft Evidence      | Direct or indirect ID Theft evidence has been placed by other Iovation subscribers against the account or device.                                                                                                                                                 |
| Other Subscriber Miscellaneous Evidence | Direct or indirect Miscellaneous evidence has been placed by other Iovation subscribers against the account or device.                                                                                                                                            |
| Other Subscriber Policy Fraud Evidence  | Direct or indirect Policy Fraud evidence has been placed by other Iovation subscribers against the account or device.                                                                                                                                             |
| Owned Evidence Exists                   | There is direct or indirect evidence against the account or device. The evidence has been placed by the subscriber.                                                                                                                                               |
| Proxy in Use                            | Transaction is sent via a proxy service to obfuscate the true location of the end user.                                                                                                                                                                           |
| Suspect Device Data                     | Corrupt or incomplete blackbox. This is due to direct action by the end user.                                                                                                                                                                                     |
| Timezone/Geolocation Mismatch           | When the timezone the device is configured is different than the timezone the Real IP determines - define # of minutes.                                                                                                                                           |
| TOR Exit Node IP                        | Detects when a user is accessing the TOR network to remain anonymous online.                                                                                                                                                                                      |
| Transactions per IP                     | Number of Transactions per IP.                                                                                                                                                                                                                                   |
| VPN in Use | Indicates that the device is connected through a Virtual Private Network (VPN), which may obscure the user's actual IP address, location, and network origin. |

</details>

---

# Web SDK

https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRiskwithWebSDK

# Web SDK

Prior to executing a workflow that includes **Device Risk, the Jumio Web SDK** dynamically downloads third-party JavaScripts to access the required device data. Implement a reverse proxy in your own domain to redirect the script requests through your own servers. This avoids potential problems with browsers canceling third-party requests.

## To Configure the Reverse Proxy:

1. Set up a proxy configuration within your domain.
2. Specify a URI for iojs on your site. Using the URI, forward any requests beginning with: http://my.domain.com/iojs
3. Direct the proxy to forward the requests to the following URL: https://first.iovation.com

## Example NGINX Configuration

Edit the default.conf configuration file and add the following lines to the server section:

```
server {
    .. other configuration entries ...
    location /iojs/ {
    proxy_pass https://first.iovation.com/;
    }
    ... }
```

With a successful implementation there should be two upload calls after the end user presses the Start button. The second one should contain a request with a random string.

If you open the network tab of the developer console you should see that four files were fetched, with no errors.

<center>![developer console](./img/IovationDownloads.png)</center>

---

# Mobile SDK

https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRiskwithMobileSDK

# Mobile SDK

To use **Device Risk with a mobile app**:

1. Integrate the Iovation Device Risk SDK.
2. Upload the blackbox string obtained from the Iovation SDK as a Prepared Data credential using the Jumio REST API.
3. Either:
   - Call the finalize API to process the transaction, if you are using Device Risk as a standalone capability.
   - Continue the customer journey using one of the Jumio Mobile SDKs.

## Integrating the Iovation SDK

Iovation provides an SDK for generating the blackbox:

- For iOS see [deviceprint-SDK-iOS](https://github.com/iovation/deviceprint-SDK-iOS), learn more about [Jumio Mobile SDK-iOS](/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-ios-master/README_iOS).
- For Android see [deviceprint-SDK-android](https://github.com/iovation/deviceprint-SDK-android), learn more about [Jumio Mobile SDK-Android](/docs/developer-resources/SDKs/mobile-sdk/mobile-sdk-android-master/README_Android).

## Uploading the Blackbox

A request to update or create an account that references a workflow that calls Device Risk will include a DATA credential with a "device_risk" part. The JSON object for the credential will include the bearer token and URL for uploading the blackbox obtained from the Iovation SDK.

```
    "credentials": [
      {
        "id": "UUID",
        "category": "DATA",
        "label": "DATA",
        "allowedChannels": [
          "API"
        ],
        "api": {
          "token": "JWT",
          "parts": {
            "device_risk": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32/credentials/9d79ed28-947b-4b83-9dfc-80b64467d70c/parts/DEVICE_RISK"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32"
        }
      }
    ]
```

### Device Risk Data

| Key       | Type   | Mandatory | Description                          |
| --------- | ------ | --------- | ------------------------------------ |
| sessionId | string | Yes       | Blackbox obtained from Iovation SDK. |

#### Example: Device Risk Data

```
{
"sessionId": "0400l1oURA1kJHkNf94lis1ztsLfEt3/IFXXN1MYH/C7FN9WGrecBg4p0ON8Qk5xXP5yzri4ipiY+gcauEKiR3CD0f5bxgCPh2s4xV2jOAT9QDo46MvqbksKpwyCiDVa0KzS3EXoW3wRrlco8IG1qk9lAIBU13+e+YkwDXMzdeKt5csId7H9j3oUV2HkUixgPRKu8cFCb3XpK0LXm0XBtvk2RW2s0fO33l4+w84qwFGsHzXgiEms7PTw/N/7HinDpb16xsYSmrsKhFi8VDdLGBfK9PH/LgnAtMTg3G/gqjChOr3UE93P7lQ6YY1QqVXhJlc0TMj6Y82LrlflYU9iUMb03U590nH6wX2EU2IImCqOVt1Lb3Rq69nPqNh+4KFmyEtnhFqIBpUqh4gjqERo3lTicqoN6O+jq/sPjofZbR2X0CIID6FY6p00ehQugOFx8rWe05+m/s9uEinvsD8Ae2HMhGn9cJjqZjvIjNXsgMEghG088ZC6JnyJ5fPoP5g1QwsRQTMzPSNXu7gXqEkpOTPbD6jApGyavAPnx7yacWI+PSIAtXVX6KlFBPc3vlN6JaM3rjS2HZzFE1aixPMqjFULp9I8UWAJoym9T+HoQVdeZcRmg6J8uARU7CENZVhLgl43xKmKi0E5mbJ5wzug8QBi+7I+vS3zO1UWbqNLtKFF+Ej3oU6k968Na6nSLy2F7Hp7vFQ3SxgXyvTx/y4JwLTE4P4M9O7lUiDQIMyfBSWv/vuXVqFEs8cInVHsazfWk+JVPmEazlvGoKjmhhOQo4K74RCU9nsEY/2KXawrAyogf4PM8fwrGTmgzskUPUHB2KBz1PnBUfUaSr7ZOMtF4ceNvkYBKknoROYtYNJHJfSFZ+1EZnuQG7VXjwuFGpzshDlVv912gmTa+7D6oxNEfoZFV+DscBxLl+dLDzomaz9kojls8my31ramZUkmPOslRT8GUQ50p/wnlDZFRarIuC6RSZndk1PYFXQ2ZFBv5giE92SxAiJ6dZ3B8hEON+BvWb01b3apMSFR1WXZKbyG5meGt9kxpLMTusENhXF7hmR8PZ+DB82UHqdjtxv/OsaDA0k7CA2/2p99K8A/smYGPMGbNwgNv9qffSvAV5uQhSymIGAIDb/an30rwFKAZUfejFreCA2/2p99K8DalO9KDtKoXAsmmx9bqOcfryRVak4KySGXmXf+xzrSIocc4vivspj4G/86xoMDSTttIJAL1chbPonJeh0dRqi1FcOv46vzrKfU0HnrAUrLxC+HGoczCbjhGgbsrJKKTCS7DlYuPBTitwMZUgt2Da8GGUoKbb/pm4aia9S/YqbWZmDZurZubUAT+4QNFcISoxS+h0qcCpIEPAjeTrc3OBfUlFXF00bch/Du5a/0VxS7QpGUdmUMUwCxekHRr9G3NpEKmK/Oz7gQwFgFqUSspd+3g2jcOWRd8azW3CGQ1LX2fL7Y6qSQNeXSEo1QEv4tzQmMYND4T0JKUQpbJRlMGw9q9ftyks+99NcozimYay8uUBzvFuMPm89GC3/vUxT+kSwZvf7wOdzePZmoxa72mXhf2khAqKdWEtdu52KFGFNCVBYxtvKFLh9PlTnlXrCxqIyVT31SgfbGSYEVm3q9npvKMXDe/htBXCHlccEEM2wYZqR/mwMsZEA87Q3z0zIaBGVK0Bgv1jhwxuZpe1KXZSaa8cG+2KdGP22HPmnClNMvcbqLSUV0LG8JzcmmERYC1Gz1LaL75tS477GWfT72CsVv+YtO8ArCh3ufb5p0+N9t6zGsdGil6G+M6QwuNtanQnlQQ16gTYXgqAk39+502nZNVrIc/x4UXaZ40s6qimpeCXTaMl686fnTbuOr37uPFjN8X/YvUDvtEZoVugXwRLvf23Q+XdyVtqdQQ16gTYXgqAk39+502nZNVrIc/x4UXaZ40s6qimpeCXTaMl686fnTbuOr37uPFjMO6L3qtdOASyFHJHhMvyClUmK+W/pTqArcD2srI+H9ZislHmuQbhrvLso5bgIo9tjDN7aLd8tmN9AySWY3fRRS4G+b9j512CI2ABfLQqcPrHcgqn9KYunPLxn0jBuM6kkWhDITwJ+fFCXJ91CNvJuTS6HnmJ1CatHwiZNgJIhJCRjnWnKRJDonIGgE3xZCAEVZK4DLpvXThE0MH6wQTRkvIzqIEVc5bblnbChVFMXIW0rc/2p5wHg8dXfE0inMWYCgtI1MfSxvOq8EG2IhA5WZxSRwl/ssA2Q5gBtsn0VVkGahu173HCRKGUUtl+nD/05VSWkufaJbp2P8L5YARpWvKSQzticzU/R3N/8WxtfBooYOzIDfWTaRUxfSnsGHojxyyO66aVU6MdA4zKpFNgetzfpP6gdqigpGvWm5lSpMPg=="
}
```

---

# REST API

https://documentation.jumio.ai/docs/references/riskSignals/deviceRiskCheck/deviceRiskwithRestAPI

# REST API

To use **Device Risk** as a standalone service you can:

- Integrate a JavaScript from Iovation to capture the blackbox data from the end user's device.
- Upload the blackbox string as a Prepared Data credential using the Jumio REST API.
- Call the finalize API to process the transaction.

## Integrating the Iovation JavaScript

Download the [loader.js](/resources/loader.zip) JavaScript file from Iovation for generating the blackbox.

### Multi-Domain Recognition

The Iovation script will dynamically load additional resources from both your domain (the First-party domain) and TransUnion's domain (the Third-party domain). Including scripts from both of these domains allows the following:

Third-Party JavaScript: Share fraud history for devices and accounts across TransUnion subscribers.

First-Party JavaScript: Collect device information for users whose browsers are configured to disable third-party JavaScript, or that block the TransUnion domain.

:::tip
This script will load the appropriate resources from both sets of domains. Components loaded by the script are dynamically generated and therefore not included with the script provided, nor should they be directly included on your page.
:::

Retrieving the dynamic first party script will require you to implement a reverse proxy in your own domain to redirect the script requests through your own servers. This avoids potential problems with browsers canceling the requests.

## Configuring the JavaScript

To configure the Iovation JavaScript you must define settings for a configuration object that is used by the JavaScript. If the object is not defined, default values will be used.

The configuration object has various sections and looks something like the following:

```
/_ Copyright(c) 2016, iovation, inc. All rights reserved. _/
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
"bbout_element_id" : "iobb",
"bb_callback": null,
"loader" : {
"uri_hook" : "iojs",
"version" : "general5",
"subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
}
};
```

You will receive a configuration script in addition to the collection script. You can include these separately, combine them or in-line the definition on your page.

:::caution
It is critical that the configuration comes before TransUnion's loader script otherwise configuration variables will not be used once the script starts running.
:::

## Configuration script sections

### TransUnion Global Object Name

Before delving into the options available, a quick word on the io_global_object_name, IGLOO, by default. In earlier versions of the scripts, TransUnion configured the script through the use of global variables. While this approach is simple enough, it can add a lot of additional variables to the window object which has the potential to collide with other scripts.

To remedy this, TransUnion has created an object that encapsulates all of the settings and functionality and you can change the ID to prevent potential collisions by changing the name.

:::note
window.io_global_object_name = "&lt;your custom name&gt;"

If you do change the value, references functions and values as follows:

- window.&lt;your custom name&gt;.xxxxx
- Change the following as well: window.IGLOO = window.IGLOO || to match your new custom name.
  :::

**TransUnion configuration object** has 2 main components:

1. Generic settings that indicate how to retrieve a device print and restrictions on what information is collected, for instance Flash values

2. Loader settings that indicate how to access first-party components and basic debug and versioning information

Each set of configuration options belongs in a specific section of the object:

```
/_ Copyright(c) 2016, iovation, inc. All rights reserved. _/
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
// generic settings go here as
// "option" : value
...
"loader" : {
// loader configuration options go here as
// "option" : value
}
};
```

## Generic Configuration Options

| Parameter        | Type               | Default Value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bbout_element_id | string, optional   |               | The ID of the HTML element to populate with the blackbox from the third-party JavaScript. If bb_callback is specified, this parameter has no effect.                                                                                                                                                                                                                                                                                                 |
| bb_callback      | function, optional |               | This JavaScript function is an event handler that is called when a collection method has finished updating a blackbox. This must be a function, not a string. Declare the function as follows: `bb_callback: function(bb, complete) { /* code to process blackbox here */ }` The variables store the following: `bb` – the updated value of the blackbox, `complete` – a boolean value indicating whether all the collection methods have completed. |
| enable_rip       | boolean, optional  | true          |                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## Loader Configuration Options

| Parameter     | Type               | Default Value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------- | ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uri_hook      | string, optional   | iojs          | Location of dynamic first party components. This should be a reference to the web directory being proxied. You can use relative or absolute references, but should not use a complete URL. For example, if your reverse proxy is accessed from <ul><li> http://mysite.com/iov/wdp/....,and your page is loaded from: </li> <li>http://mysite.com/app/mypage.html,</li> <li> you would use: "uri_hook" : "/iov/wdp" </li> <li>If the reverse proxy is accessed at http://mysite.com/app/iojs and </li> <li>your page is at http://mysite.com/app/page.html, you might use: "uri_hook" : "iojs" </li> <li>This should not be a URL (i.e. include http(s)://host:port) as this will fail and the scripts must be loaded from the same domain as the page.</li></ul> |
| subkey        | string, optional   |               | This will be a TransUnion assigned value that tracks requests from your site. This is primarily used for debugging and troubleshooting purposes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| version       | string, required   | general5      | This is the version of the script to load. The value should either correspond to a specific version you wish to use, or one of the following aliases to get the latest version of the code: `general5` - the latest stable version of the JavaScript, `early5` - the latest available version of the JavaScript. `general5` and `early5` may be the same code, however, any new changes will be released on `early5` prior to `general5`. Once the new release has been vetted in production and deemed satisfactory, `general5` will be updated to match `early5`.                                                                                                                                                                                              |
| trace_handler | function, optional |               | This JavaScript function can be used to provide tracing messages for the script. This will provide information on the progress of the script and is useful for debugging purposes. Declare the function as follows: `trace_handler: function(message) { /* process/record trace message here */ }` where `message` is the trace message provided by the script.                                                                                                                                                                                                                                                                                                                                                                                                  |

### Example Configuration File

```
/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  "bbout_element_id" : "iobb",
  "loader" : {
    "uri_hook" : "/iojs",
    "version" : "general5",
    "subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
  }
};
```

## Define the bb_callback Function

The callback interface allows you to manage blackbox generation in a more event-driven manner. As blackbox collection progresses,the script fires update events as collection methods complete. These events trigger a user-defined callback function to update the page with the new blackbox value. When all of the collection methods are completed, a Boolean flag is set indicating no further updates are expected and the value is the final blackbox value.

In the JavaScript configuration parameters, set the bb_callback parameter to a function that processes the blackbox value, and that has the following signature:

function bb_update_callback( bb, complete)

Where:

- bb is the updated value of the blackbox
- complete is a boolean value that indicates whether all collection methods (Flash, etc.) are complete

```
/* Copyright(c) 2016, iovation, inc. All rights reserved. */
window.io_global_object_name = "IGLOO";
window.IGLOO = window.IGLOO || {
  "bb_callback": function ( bb, complete ) {
                      var bb_field = document.getElementById( "bb" );
                      bb_field.value = bb;
                  },
  "loader" : {
    "version" : "general5",
    "subkey" : "5FExse+oA1134BhiwCF2EeQ1TfisPJGha4CpVG2nd7E="
  }
};
```

:::tip
If bb_callback and bbout_element_id are both specified, the hidden field specified in bbout_element_id will not be populated, unless explicitly done so by the function specified in bb_callback.
:::

## Configure the Reverse Proxy with the steps below

1. Set up a proxy configuration within your domain.
2. Specify a URI for iojs on your site. Using the URI, forward any requests beginning with: http://my.domain.com/iojs
3. Direct the proxy to forward the requests to the following URL: https://first.iovation.com

### Example NGINX Configuration

Edit the default.conf configuration file and add the following lines to the server section:

```
server {
.. other configuration entries ...
location /iojs/ {
proxy_pass https://first.iovation.com/;
}
... }
```

## Uploading the Blackbox

A request to update or create an account that references a workflow that calls Device Risk will include a DATA credential with a "device_risk" part. The JSON object for the credential will include the bearer token and URL for uploading the blackbox obtained from the Iovation SDK.

```
    "credentials": [
      {
        "id": "9d79ed28-947b-4b83-9dfc-80b64467d70c",
        "category": "DATA",
        "label": "DATA",
        "allowedChannels": [
          "API"
        ],
        "api": {
          "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XLOw4CMQxF0b2kxlLiycemQ1S07MCfpBugQIIRYu8EdkD3dHXeK_Tn4R72IVWuudREuBQOuyBmJ5_dY3LWVqEYEmSfS6s4dGRjSUqRypf_MI0xWSNAFZs4G6gLg3R1cmyiC078GP0fbuc-pl6343W9yWX7pt-_GblFHpBT6ZCxDWAaCj0NKdFVEWN4fwAX03Be4wAAAA.wR-1U9aOdOk4gJiDc665u2i4-clB8-g2CATM1YODcFuDec5_gumFa2wJh7eoMPGoZoJmWXEEMDZaG6VjSLajZw",
          "parts": {
            "device_risk": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32/credentials/9d79ed28-947b-4b83-9dfc-80b64467d70c/parts/DEVICE_RISK"
          },
          "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/d01d9b76-5c28-4d76-b6ad-e29c9a1b8085/workflow-executions/8ff5c278-2bac-4d4c-bda9-aebd8d27ab32"
        }
      }
    ]
```

### Device Risk Data

| Key       | Type   | Mandatory | Description                          |
| --------- | ------ | --------- | ------------------------------------ |
| sessionId | string | Yes       | Blackbox obtained from Iovation SDK. |

#### Example: Device Risk Data

```
{
    "sessionId": "0400l1oURA1kJHkNf94lis1ztsLfEt3/IFXXN1MYH/C7FN9WGrecBg4p0ON8Qk5xXP5yzri4ipiY+gcauEKiR3CD0f5bxgCPh2s4xV2jOAT9QDo46MvqbksKpwyCiDVa0KzS3EXoW3wRrlco8IG1qk9lAIBU13+e+YkwDXMzdeKt5csId7H9j3oUV2HkUixgPRKu8cFCb3XpK0LXm0XBtvk2RW2s0fO33l4+w84qwFGsHzXgiEms7PTw/N/7HinDpb16xsYSmrsKhFi8VDdLGBfK9PH/LgnAtMTg3G/gqjChOr3UE93P7lQ6YY1QqVXhJlc0TMj6Y82LrlflYU9iUMb03U590nH6wX2EU2IImCqOVt1Lb3Rq69nPqNh+4KFmyEtnhFqIBpUqh4gjqERo3lTicqoN6O+jq/sPjofZbR2X0CIID6FY6p00ehQugOFx8rWe05+m/s9uEinvsD8Ae2HMhGn9cJjqZjvIjNXsgMEghG088ZC6JnyJ5fPoP5g1QwsRQTMzPSNXu7gXqEkpOTPbD6jApGyavAPnx7yacWI+PSIAtXVX6KlFBPc3vlN6JaM3rjS2HZzFE1aixPMqjFULp9I8UWAJoym9T+HoQVdeZcRmg6J8uARU7CENZVhLgl43xKmKi0E5mbJ5wzug8QBi+7I+vS3zO1UWbqNLtKFF+Ej3oU6k968Na6nSLy2F7Hp7vFQ3SxgXyvTx/y4JwLTE4P4M9O7lUiDQIMyfBSWv/vuXVqFEs8cInVHsazfWk+JVPmEazlvGoKjmhhOQo4K74RCU9nsEY/2KXawrAyogf4PM8fwrGTmgzskUPUHB2KBz1PnBUfUaSr7ZOMtF4ceNvkYBKknoROYtYNJHJfSFZ+1EZnuQG7VXjwuFGpzshDlVv912gmTa+7D6oxNEfoZFV+DscBxLl+dLDzomaz9kojls8my31ramZUkmPOslRT8GUQ50p/wnlDZFRarIuC6RSZndk1PYFXQ2ZFBv5giE92SxAiJ6dZ3B8hEON+BvWb01b3apMSFR1WXZKbyG5meGt9kxpLMTusENhXF7hmR8PZ+DB82UHqdjtxv/OsaDA0k7CA2/2p99K8A/smYGPMGbNwgNv9qffSvAV5uQhSymIGAIDb/an30rwFKAZUfejFreCA2/2p99K8DalO9KDtKoXAsmmx9bqOcfryRVak4KySGXmXf+xzrSIocc4vivspj4G/86xoMDSTttIJAL1chbPonJeh0dRqi1FcOv46vzrKfU0HnrAUrLxC+HGoczCbjhGgbsrJKKTCS7DlYuPBTitwMZUgt2Da8GGUoKbb/pm4aia9S/YqbWZmDZurZubUAT+4QNFcISoxS+h0qcCpIEPAjeTrc3OBfUlFXF00bch/Du5a/0VxS7QpGUdmUMUwCxekHRr9G3NpEKmK/Oz7gQwFgFqUSspd+3g2jcOWRd8azW3CGQ1LX2fL7Y6qSQNeXSEo1QEv4tzQmMYND4T0JKUQpbJRlMGw9q9ftyks+99NcozimYay8uUBzvFuMPm89GC3/vUxT+kSwZvf7wOdzePZmoxa72mXhf2khAqKdWEtdu52KFGFNCVBYxtvKFLh9PlTnlXrCxqIyVT31SgfbGSYEVm3q9npvKMXDe/htBXCHlccEEM2wYZqR/mwMsZEA87Q3z0zIaBGVK0Bgv1jhwxuZpe1KXZSaa8cG+2KdGP22HPmnClNMvcbqLSUV0LG8JzcmmERYC1Gz1LaL75tS477GWfT72CsVv+YtO8ArCh3ufb5p0+N9t6zGsdGil6G+M6QwuNtanQnlQQ16gTYXgqAk39+502nZNVrIc/x4UXaZ40s6qimpeCXTaMl686fnTbuOr37uPFjN8X/YvUDvtEZoVugXwRLvf23Q+XdyVtqdQQ16gTYXgqAk39+502nZNVrIc/x4UXaZ40s6qimpeCXTaMl686fnTbuOr37uPFjMO6L3qtdOASyFHJHhMvyClUmK+W/pTqArcD2srI+H9ZislHmuQbhrvLso5bgIo9tjDN7aLd8tmN9AySWY3fRRS4G+b9j512CI2ABfLQqcPrHcgqn9KYunPLxn0jBuM6kkWhDITwJ+fFCXJ91CNvJuTS6HnmJ1CatHwiZNgJIhJCRjnWnKRJDonIGgE3xZCAEVZK4DLpvXThE0MH6wQTRkvIzqIEVc5bblnbChVFMXIW0rc/2p5wHg8dXfE0inMWYCgtI1MfSxvOq8EG2IhA5WZxSRwl/ssA2Q5gBtsn0VVkGahu173HCRKGUUtl+nD/05VSWkufaJbp2P8L5YARpWvKSQzticzU/R3N/8WxtfBooYOzIDfWTaRUxfSnsGHojxyyO66aVU6MdA4zKpFNgetzfpP6gdqigpGvWm5lSpMPg=="
}
```

---

# Email Verification

https://documentation.jumio.ai/docs/references/riskSignals/emailVerification

# Email Verification

Email Verification enables you to assess the risk of email addresses provided by the end user. It is a fundamental risk check that analyzes an email address to provide an overall risk. It, adds email intelligence as a layer of defense to fraud prevention. It assesses risks by evaluating email address metadata points such as domain details, email details, and risk indicators.

## Use Case

For those with onboarding and account login workflows, who wish to understand and assess the risks of a given email address.

## Supported Credentials

The following values can be uploaded as [Prepared Data](./../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

To use Prepared Data with email verification as a standalone capability use workflow key 10066
| Key | Type | Mandatory | Description |
|----------------|---------|-----------|------------------------------------------|
| Email address | String | yes | Email Address of Applicant |
|ipAddress|String|no|The IP address entered as a string. Either IPv4 or IPv6 format is accepted.|

### Example Prepared Data Body

```
{
    "email": "martin***ng@gmail.com"
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see [View or Retrieve Workflow Transactions](../../developer-resources/retrieval).

**Example Response**

```
{
   "workflow": {
     "id": "203cf33c-77f8-443d-ac4d-ad52121f94f8",
     "status": "PROCESSED",
     "definitionKey": "10066",
     "userReference": "abc",
     "customerInternalReference": "dd"
   },
   "account": {
     "id": "4363fce6-6197-46e6-9840-39cda6860c97"
   },
   "createdAt": "2025-05-08T12:45:43.518Z",
   "startedAt": "2025-05-08T12:45:51.122Z",
   "completedAt": "2025-05-08T12:45:53.801Z",
   "credentials": [
     {
       "id": "a0c4d666-9718-49a0-a120-d259f1cea0a4",
       "category": "DATA",
       "parts": [
         {
           "classifier": "PREPARED_DATA",
           "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/4363fce6-6197-46e6-9840-39cda6860c97/credentials/a0c4d666-9718-49a0-a120-d259f1cea0a4/parts/PREPARED_DATA"
         }
       ]
     }
   ],
   "decision": {
     "type": "PASSED",
     "details": {
       "label": "TXN_PASSED"
     },
     "risk": {
       "score": 0
     }
   },
   "steps": {
     "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/4363fce6-6197-46e6-9840-39cda6860c97/workflow-executions/203cf33c-77f8-443d-ac4d-ad52121f94f8/steps"
   },
   "capabilities": {
     "emailVerification": [
       {
         "id": "0790a7f1-5ebf-451a-98b1-d6ad60f2ffe0",
         "credentials": [
           {
             "id": "a0c4d666-9718-49a0-a120-d259f1cea0a4",
             "category": "DATA"
           }
         ],
         "decision": {
           "type": "PASSED",
           "details": {
             "label": "LOW_RISK"
           }
         },
         "data": {
           "emailVerificationStatus": "ValidDomain",
           "firstVerifiedAt": "2022-07-10T00:00:00.000Z",
           "totalHits": "6",
           "domainExists": true,
           "domainName": "jumio.com",
           "domainCompany": "Jumio",
           "domainRiskLevel": "LOW",
           "domainCreationDate": "2004-03-30T07:07:55.000Z",
           "advice": "LOWER_FRAUD_RISK",
           "domainCountry": "USA",
           "domainCategory": "Technology",
           "domainCorporate": true,
           "reason": "EMAIL_CREATED_AT_LEAST_YEARS_AGO",
           "emailDeterminedStatus": "Not Sure",
           "countForReason": 2
         },
       }
     ]
   },
 }
```

#### Decision Details Labels

<details>

| Decision Type | Label                      | Description                                                                                                                      |
| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| PASSED        | LOW_RISK                   | No significant risk associated with the data.                                                                                    |
| REJECTED      | HIGH_RISK                  | High risk associated with the data.                                                                                              |
| WARNING       | MEDIUM_RISK                | Moderate risk associated with the data.                                                                                          |
| NOT_EXECUTED  | PERMISSION_DENIED          | Cannot be executed because the required permissions or credentials are missing. Verify your API key and access rights.           |
| NOT_EXECUTED  | BAD_REQUEST                | Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying. |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Preconditions were not met to process the data.                                                                                  |
| NOT_EXECUTED  | TECHNICAL_ERROR            | There was an error in processing the request.                                                                                    |

</details>

#### Data

<details>

| Parameter                   | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **firstVerificationDate**   | date time (UTC) | The oldest date found for records associated with the query. This date can also be considered the First Seen Date. If it's the first time an email is seen, the field will be set to the current date. Returned in UTC format.                                                                                                                                                                                                                                                                                                                                                        |
| **emailVerificationStatus** | string          | Possible values: <ul> <li>`GeneralError` - Unidentified error generated at the time of your request. </li> <li>`Certified` - The email exists and we have its creation data. </li> <li>`Verified` - The email exists but we are not sure when it was created. </li><li>`EmailInexistent` - The email does not exist but the domain does.</li> <li>`ValidDomain` - The email domain exists, but we are not sure if the email address exists.</li> <li>`DomainInexistent` - The domain doesn't exist. </li><li>`Unknown` - We are not sure whether the domain exists or not. </li></ul> |
| **totalHits**               | integer         | Number of times the email address was queried through the risk signal or overall vendor platform in the last 7 days.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **emailExists**             | boolean         | Indicates whether or not the email address exists. Possible values: <ul> <li>`true` - The email address exists. </li> <li>`false` - The email address does not exist. </li></ul>                                                                                                                                                                                                                                                                                                                                                                                                      |
| **domainExists**            | boolean         | Indicates whether or not the email domain exists. Possible values:<ul> <li> `true` - The email domain exists.</li><li> `false` - The email domain does not exist. </li></ul>                                                                                                                                                                                                                                                                                                                                                                                                          |
| **domainName**              | string          | The email domain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **domainCompany**           | string          | Owner of the email domain.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **domainRiskLevel**         | string          | Possible values: <ul> <li> `VERY HIGH`</li> <li>`HIGH`</li> <li>`MEDIUM`</li> <li>`LOW` </li> <li> `VERY_LOW`</li> </ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **domainCreationDate**      | string          | The creation date of the domain. This field may be blank for some queries. Returned in UTC format: `YYYY-MM-DDThh:mm:ssZ`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **advice**                  | string          | Possible values: <ul><li>`FRAUD_REVIEW` - Review the email address for fraud risks.</li> <li>`UNCLEAR_RISK` - The risk is unclear, further analysis needed. </li><li>`LOWER_FRAUD_RISK` - The email address has lower fraud risk. </li><li>`MODERATE_FRAUD_RISK` - The email address has moderate fraud risk.</li><li> `DATA_REVIEW` - The email requires data review. </li></ul>                                                                                                                                                                                                     |
| **domainCountry**           | string          | The country that issued the domain. Can be any ISO 3166-1 alpha-3 country code, and `XKX` for Kosovo. Examples: `USA`, `AUT`, `DEU`, `FRA`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **domainCategory**          | string          | The category of the domain. For example, <ul> <li> Email services</li> <li> Email delivery services</li> <li>Webmail</li> <li> Disposable email services</li> <li>Malware</li><li>Misspelled</li><li>Private domain</li><li>No content found</li><li>Not available</li><li>Not loading</li><li>Paid webmail, etc.</li></ul>                                                                                                                                                                                                                                                           |
| **domainCorporate**         | boolean         | Indicates if the domain is corporate. Possible values: <ul> <li>`true` - The domain is corporate.</li><li> `false` - The domain is not corporate. </li> </ul>                                                                                                                                                                                                                                                                                                                                                                                                                         |
| reason                      | string          | Refer the table below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| emailDeterminedStatus       | string          | Uncertainty in determining whether the email exists. This field is included only when the emailExists field has the value Not Sure. Possible values: `Not Sure`                                                                                                                                                                                                                                                                                                                                                                                                                       |
| domainDeterminedStatus      | string          | Uncertainty in determining whether the domain exists. This field is included only when the domainExists field has the value Not Sure. Possible values: `Not Sure`                                                                                                                                                                                                                                                                                                                                                                                                                     |

</details>

#### Reason Type

<details>
<summary>Reason Type</summary>

| Reason Type                                       | Description                                                                               |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| FRAUD_LEVEL                                       | Number of unique customers in the Emailage Network who marked the email as fraud.         |
| EMAIL_DOES_NOT_EXIST_EMAIL_DOES_NOT_EXIST_ANYMORE | The email address does not exist or no longer exists.                                     |
| DOMAIN_DOES_NOT_EXIST                             | Domain is not found in registry.                                                          |
| RISKY_DOMAIN                                      | Domain has a high fraud rate.                                                             |
| RISKY_COUNTRY                                     | Email owner, domain, or IP location originates from a high-risk country.                  |
| RISKY_EMAIL_SYNTAX                                | Email pattern is known to be associated with fraud.                                       |
| NUMERIC_EMAIL                                     | Email handle contains numeric patterns, often seen in fraudulent emails.                  |
| LIMITED_HISTORY_FOR_EMAIL                         | Insufficient historical data to determine fraud risk.                                     |
| EMAIL_RECENTLY_CREATED                            | Email was created recently (determined by machine learning).                              |
| EMAIL_LINKED_TO_HIGH_RISK_ACCOUNT                 | Email is associated with high-risk accounts.                                              |
| GOOD_LEVEL                                        | Number of unique customers who marked the email as good.                                  |
| LOW_RISK_DOMAIN                                   | Domain has a low fraud rate.                                                              |
| EMAIL_CREATED_YEARS_AGO                           | Email creation timestamp provided in years.                                               |
| EMAIL_CREATED_AT_LEAST_YEARS_AGO                  | Approximate number of years since email creation.                                         |
| EMAIL_LINKED_TO_LOW_RISK_ACCOUNT                  | Email is associated with low-risk accounts.                                               |
| INVALID_EMAIL_SYNTAX                              | Email format is syntactically incorrect.                                                  |
| MAILBOX_IS_FULL                                   | Mailbox has reached its storage limit.                                                    |
| MAILBOX_IS_INACTIVE                               | Email address is no longer active.                                                        |
| MAILBOX_IS_EXPIRED                                | Email existed previously but is now expired.                                              |
| USER_DEFINED_RISK_DOMAIN                          | Domain marked as high-risk by the client/company.                                         |
| USER_DEFINED_LOW_RISK_DOMAIN                      | Domain marked as low-risk by the client/company.                                          |
| VELOCITY_LEVEL                                    | High query frequency for the email in a short period.                                     |
| RISK_DOMAIN_CATEGORY                              | Domain falls under high-risk category (e.g., webmail, banking).                           |
| LOW_RISK_DOMAIN_CATEGORY                          | Domain falls under a low-risk category.                                                   |
| HIGH_RISK_EMAIL_ACCOUNT                           | Email has a high probability of fraud association.                                        |
| EMAIL_CREATED_AT_LEAST_MONTHS_AGO                 | Approximate number of months since email creation.                                        |
| POTENTIALLY_BREACHED_EMAIL                        | Email was exposed in a known breach.                                                      |
| GOOD_POPULARITY                                   | Email has positive associations via social or public sources.                             |
| RISK_DOMAIN_CATEGORY_REVIEW                       | Domain category has a high fraud rate.                                                    |
| TUMBLING_ABUSE                                    | Slight email variations suggest potential abuse (e.g., a.bc@gmail.com vs ab.c@gmail.com). |
| EMAIL_ENUMERATION_FOR_COMPANY                     | Multiple similar email handles were queried by the same company.                          |
| EMAIL_ENUMERATION_FOR_INDUSTRY                    | Multiple similar email handles were queried by companies in the same industry.            |
| CREATION_DATE_VELOCITY                            | Email creation dates show suspicious timing patterns across the network.                  |
| CUSTOMER_EMAIL_NOT_PROVIDED                       | No customer email provided; a dummy email is used for processing.                         |
| RISK_EMAIL_PATTERN                                | Email follows a pattern associated with fraud per global risk analysis.                   |
| SUSPECTED_FRAUD                                   | Email explicitly marked as "Suspected Fraud."                                             |
| LIMITED_EMAIL_INFORMATION                         | Very little information available about the email.                                        |
| DOMAIN_RECENTLY_CREATED                           | Domain was registered recently, suggesting potential risk.                                |
| VELOCITY_OTHER                                    | High velocity of usage flagged by external sources.                                       |
| VALID_EMAIL_FROM_DOMAIN                           | Email is valid and correctly associated with its domain.                                  |
| VALID_DOMAIN                                      | Domain is valid and exists.                                                               |
| LOW_RISK_EMAIL_DOMAIN_FOR_COMPANY                 | Email domain is low-risk for the querying company.                                        |
| LOW_RISK_EMAIL_DOMAIN_FOR_INDUSTRY                | Email domain is low-risk within the industry.                                             |
| LOW_RISK_EMAIL_DOMAIN_FOR_NETWORK                 | Email domain is low-risk at the network level.                                            |
| VERY_LOW_RISK_EMAIL_DOMAIN_FOR_COMPANY            | Email domain is very low-risk for the querying company.                                   |
| VERY_LOW_RISK_EMAIL_DOMAIN_FOR_INDUSTRY           | Email domain is very low-risk within the industry.                                        |
| VERY_LOW_RISK_EMAIL_DOMAIN_FOR_NETWORK            | Email domain is very low-risk at the network level.                                       |
| HIGH_RISK_EMAIL_DOMAIN_FOR_COMPANY                | Email domain is high-risk for the querying company.                                       |
| HIGH_RISK_EMAIL_DOMAIN_FOR_INDUSTRY               | Email domain is high-risk within the industry.                                            |
| HIGH_RISK_EMAIL_DOMAIN_FOR_NETWORK                | Email domain is high-risk at the network level.                                           |
| VERY_HIGH_RISK_EMAIL_DOMAIN_FOR_COMPANY           | Email domain is very high-risk for the querying company.                                  |
| VERY_HIGH_RISK_EMAIL_DOMAIN_FOR_INDUSTRY          | Email domain is very high-risk within the industry.                                       |
| VERY_HIGH_RISK_EMAIL_DOMAIN_FOR_NETWORK           | Email domain is very high-risk at the network level.                                      |

</details>

---

# Government Database Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/

# Government Database Check

The objective of the Government Database check is to provide additional confidence and assurance that the Information extracted from a government ID or document is real and valid by vetting it against an authoritative government source or database tied to the specific country of origin.

For example, this could involve validating a National ID number against an authoritative source, such as checking a Mexican CURP against the RENAPO (Registro Nacional de Población) database to confirm that the identity details provided are accurate and exist in the government registry.

These government database checks each connect to a specific, selected government database, and results depend on the accuracy and availability of the source. Some of these same databases may also be part of broader, multi-source checks—like eKYC or waterfall workflows—using the same provider (e.g., GDC or LSEG).

Other examples include validating Names, Date of Birth or National ID numbers from passports or ID cards against their respective issuing authorities. For example, the Government Database checks that, an Australian passport number is verified via the Document Verification Service (DVS), which is managed by the Australian Government Attorney General's Department.

## Country-Specific Data and Biometric Verification

Some government checks require additional or specialized data or configuration. See the following:

| **Country**         | **Data Check**                                                                        | **Biometric Verification**                                                          |
| ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Argentina**       | [Renaper Check](./../govDatabaseCheck/Argentina/checkArgentina)                       | [Biometric Verification](./../govDatabaseCheck/Argentina/biometricArgentina)        |
| **Mexico**          | [Credential Validation (Lista Nominal)](./../govDatabaseCheck/mexicanINECred)         | [Mexican INE Data & Face Validation ](./../govDatabaseCheck/mexicanINEDataFace)     |
|                     | [Mexican CURP Validation (Renapo)](./../govDatabaseCheck/mexicanCheckRenapo)          |                                                                                     |
|                     | [Mexican RFC Database Check](./../govDatabaseCheck/mexicanRFCDatabaseCheck)           |                                                                                     |
| **Brazil**          | [Brazilian CPF Number Check](./../govDatabaseCheck/Brazilian/brazilianCPFCheck)       | [CPF Biometric Verification](./../govDatabaseCheck/Brazilian/brazilianCPFBiometric) |
| **Colombia**        | [Colombian Registraduria Check](./../govDatabaseCheck/checkColombianRegistraduria)    | -                                                                                   |
| **Thailand**        | [Thai DOPA Check](./../govDatabaseCheck/checkThai)                                    | -                                                                                   |
| **Peru**            | [RENEIC Data Check ](./../govDatabaseCheck/peruRENEIC)                                | -                                                                                   |
| **Australian**      | [Document Verification Service (DVS) Check ](./../govDatabaseCheck/AustralianDBCheck) | -                                                                                   |
| **Other Countries** | Contact [Jumio Support](https://www.jumio.com/contact/support/)                       |

Refer to the figure below for a visual of how the Government Database check works.

![image](../img/GovernmentDatabaseCheck.png)

## Use Cases

### Use Case 1

Extract the information from the ID document via Jumio’s ID Verification service and send the data to the pertinent authoritative data source to validate the information. Jumio will respond with a risk level of one of the following:

- Accept - Match
- Warning - Partial Match
- Reject - No Match

The risk level is sent to our customers with an overall decision and metadata pertaining to individual elements supplied.

### Use Case 2

Customers provide personal information that they have collected from their consumers. Jumio provides an overall risk assessment based upon that information tied to the government database that it is configured to. Jumio will respond with a risk level of one of the following:

- Accept - Match
- Warning - Partial Match
- Reject - No Match

The risk level is sent to our customers with an overall decision and metadata pertaining to individual elements supplied.

## Supported Credentials

The following values can be uploaded as Prepared Data. Alternatively, they can be extracted by an upstream capability in a workflow.

<details>
| Key                       | Type       | Mandatory  | Description                                                                                 |
|---------------------------|------------|------------|---------------------------------------------------------------------------------------------|
| firstName                 | string     |                                     Yes         |    Optimal to include.                                                                                          |
| middleName                | string     |                                      No         |   Middle name of the subject.                                                                                          |
| lastName                  | string     |                                    Yes         |  Optimal to include                                                                                           |
| dateOfBirth               | LocalDate  | No         | Date of birth in YYYY-MM-DD format only                                                      |
| socialSecurityNumber      | string     | No         | Either socialSecurityNumber, personalNumber or idNumber should be provided                   |
| personalNumber            | string     | No         | Either socialSecurityNumber, personalNumber or idNumber should be provided                   |
| address                   | Object     | No         | Only the fields which are mentioned are required                                            |
| address.line1             | string     | No         |  First line of the address.                                                                                                                                |
| address.line2             | string     | No         |    Second line of the address.                                                                                         |
| address.city              | string     | No         |   City of residence as it appears on the ID.                                                                                          |
| address.postalCode        | string     | No         | Postal code AKA Zip code                                                                     |
| address.subdivision       | string     | No         | Subdivision AKA state                                                                         |
| address.country           | string     | No         | Country should be ISO Alpha 3 Code only                                                       |
| id                         | Object     | No         | See below                                                                               |
| id.idNumber               | string     | Yes         | Either socialSecurityNumber, personalNumber or idNumber should be provided                   |
| id.Type                | string     | conditional| Not required for all countries. Only required for countries where id Type is not sufficient. For more details, connect with Jumio Platform Integration Squad |

</details>

### Sample Prepared Data Body

```
{
    "firstName": "KARLA B***D",
    "lastName": "V***AVICENCIO ***",
    "dateOfBirth": "1***-04-27",
    "address": {
        "line1": "",
        "postalCode": "",
        "city": "",
        "subdivision": "",
        "country": "MEX"
    },
    "id": {
        "idNumber": "VIMK98**27MDFLN***",
        "type": "ID_CARD"


    }
}
```

### Sample Response Body

```
"capabilities": {
"govtIdVerification": [
            {
"id": "f06b17ba-d760-4aac-9e43-59510ab0d928",
               "credentials": [
                   {
                       "id": "c0015c70-8518-4a6f-801e-ec71c230eb89",
                       "category": "ID"
                   }
               ],

               "decision": {
                   "type": "PASSED",
                   "details": {
                       "label": "OK"
                   }
               }

               "data": {
                   "country": "MEX",
                   "type": "ID_CARD",
                   "completeNameMatch": "MATCH",
                   "initialNameMatch": "MATCH",
                   "firstNameMatch": "MATCH",
                   "lastNameMatch": "MATCH",
                   "nationalIdMatch": "NOT_MATCH",
                   "dobDayMatch": "MATCH",
                   "dobMonthMatch": "MATCH",
                   "dobYearMatch": "MATCH",
                   "dobMatch": "MATCH",
                   "addressMatch": "NOT_MATCH",
                   "score": 10,                 }]
}
```

### Decision Details Labels

<details>
| Decision Type | Label                      | Description                                                                                                                      |
| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| PASSED        | LOW_RISK                   | No significant risk associated with the data.                                                                                    |
| REJECTED      | HIGH_RISK                  | High risk associated with the data.                                                                                              |
| WARNING       | MEDIUM_RISK                | Moderate risk associated with the data.                                                                                          |
| NOT_EXECUTED  | PERMISSION_DENIED          | Cannot be executed because the required permissions or credentials are missing. Verify your API key and access rights.           |
| NOT_EXECUTED  | BAD_REQUEST                | Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying. |
| NOT_EXECUTED  | PRECONDITION_NOT_FULFILLED | Preconditions were not met to process the data.                                                                                  |
| NOT_EXECUTED  | TECHNICAL_ERROR            | There was an error in processing the request.                                                                                    |
</details>

### Data

<details>
| Parameter           | Type   | Values                                            |
|---------------------|--------|---------------------------------------------------|
| Country             | string | Country of Government Check                       |
| type                | string | Type of ID used if applicable                     |
| completeNameMatch   | string | Match, No Match                                   |
| initialNameMatch    | string | Match, No Match                                   |
| firstNameMatch      | string | Match, No Match                                   |
| lastNameMatch       | string | Match, No Match                                   |
| nationalIdMatch     | string | Match, No Match                                   |
| dobDayMatch         | string | Match, No Match                                   |
| dobMonthMatch       | string | Match, No Match                                   |
| dobYearMatch        | string | Match, No Match                                   |
| dobMatch            | string | Match, No Match                                   |
| addressMatch        | string | Match, No Match                                   |
| score               | int    | 10 - Pass, 20 - Warning, 30 - Reject              |
</details>

<!--
## Portal View

Open a transaction in the Portal to review the response. The risk signal is labeled Government ID Verification as shown in the figure below.

![image](../img/portalView.png)

-->

---

# Argentina Renaper Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/Argentina/checkArgentina

# Argentina Renaper Check

Jumio has a database check service available for Renaper in Argentina. This check allows you to validate the Documento Nacional de Identidad (DNI) and personal identifiable information.

This service connects with the National Registry of Persons (Renaper – Registro Nacional de las Personas). Renaper is the national agency that is responsible for the registration and identification of all individuals who are domiciled in the Argentinian territory or jurisdiction of all Argentina.

![image](../../img/RenaperArgentina.png)

## Supported Credentials

The following values can be uploaded as Prepared Data. Alternatively, they can be extracted by an upstream capability in a workflow.

- To use the Renaper Check along with the standard Jumio IDIV service use workflow key 10054.
- To use Prepared Data with the Renaper Check as a standalone capability use workflow key 10020.

<details>
| Key               | Type      | Mandatory | Description                                                                 |
|-------------------|-----------|-----------|-----------------------------------------------------------------------------|
| firstName         | string    | no       | First name of the subject.                                                   |
| lastName          | string    | no       | Last name of the subject.                                                    |
| middleName        | string    | no        | Middle name of the subject.                                                  |
| sex               | string    | yes       | M - Male, F - Female                                                         |
| dateOfBirth       | LocalDate | no       | Date of birth in YYYY-MM-DD format only                                      |
| address           | Object    | yes       | Only the fields mentioned are required                                       |
| address.line1     | string    | no        | Line 1 of the address.                                                       |
| address.line2     | string    | no        | Line 2 of the address.                                                       |
| address.city      | string    | no       | City of residence.                                                           |
| address.postalCode| string    | no       | Postal code or Zip code.                                                     |
| address.subdivision| string   | no        | Subdivision (e.g., state).                                                   |
| address.country   | string    | yes       | Country in ISO Alpha-3 format only, e.g., "ARG".                             |
| id                | Object    | yes       | ID-related details                                                            |
| id.idNumber       | string    | yes       | DNI or ID number (e.g., "12345678").                                          |
| id.Type           | string    | conditional| Type of the ID (e.g., "ID_CARD").                                            |
| id.subType        | string    | conditional| Subtype of the ID (e.g., "NATIONAL_ID").                                     |
| id.issuingDate    | string    | conditional| Date the ID was issued.                                                      |
| id.expiryDate     | string    | conditional| Date the ID will expire.                                                     |

</details>

### Sample Prepared Data Body

```
{
  "firstName": "XXXXI",
  "lastName": "XXXXXXI",
  "sex": "M",
  "middleName": "",
  "dateOfBirth": "1997-01-10",
  "address": {
    "line1": "",
    "postalCode": "",
    "city": "",
    "state": "",
    "subdivision": "",
    "country": "ARG"
  },
  "id": {
    "idNumber": "12345678",
    "type": "ID_CARD",
    "subType": "NATIONAL_ID"
  }
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

**Sample Response**

```
"govtIdVerification": [
            {
                "id": "79e0fa63-0ff5-4bab-99b2-bb9c49637ba2",
                "credentials": [
                    {
                        "id": "1ceaf3c0-2689-43ea-93aa-187c2ba5da51",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "country": "ARG",
                    "type": "ID_CARD",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "addressMatch": "NOT_MATCH",
                    "sexMatch": "MATCH",
                    "message": "Not Deceased"
                },

                }
            }
```

## Decision Type Label

<details>
| Decision Type     | Label              | Description                                                           |
|-------------------|--------------------|-----------------------------------------------------------------------|
| NOT_EXECUTED      | PRECONDITION_NOT_FULFILLED | Provided data is incomplete or incorrectly formatted.                |
| NOT_EXECUTED      | TECHNICAL_ERROR    | The service encountered an error and was unable to process the request.|
| NOT_EXECUTED      | PERMISSION_DENIED  | The request is not authorized to access the service.                  |
| PASSED            | OK                 | Successful processing of the request.                                 |
| WARNING           | ALERT              | A warning was raised, typically indicating potential issues.          |
| REJECTED          | DENY               | The request was denied due to a failure in validation or policy.      |
</details>

## Data

<details>
| Key              | Type        | Description          |
|------------------|-------------|----------------------|
| country          | string      | ARG                  |
| type             | string      | ID_CARD              |
| firstNameMatch   | string      | MATCH / NOT_MATCH    |
| lastNameMatch    | string      | MATCH / NOT_MATCH    |
| nationalIdMatch  | string      | MATCH / NOT_MATCH    |
| dobMatch         | string      | MATCH / NOT_MATCH    |
| addressMatch     | string      | MATCH / NOT_MATCH    |
| sexMatch         | string      | MATCH / NOT_MATCH    |
| message          | string      | Not Deceased         |
</details>

## PII Fields Returned (DPA Restricted)

The following PII fields from the Argentina Renaper Check API response will be returned ONLY for customers who have signed the updated Data Processing Agreement (DPA). This feature is disabled by default and must be explicitly enabled by Jumio. Please work with your Jumio account manager if you require this.

```
    "data": {
        "country": "ARG",
        "type": "ID_CARD",
        "firstNameMatch": "MATCH",
        "lastNameMatch": "MATCH",
        "nationalIdMatch": "MATCH",
        "sexMatch": "MATCH",
        "message": "Not Deceased",
        "fullName": "XXXXXXXXXXXx",
        "dateOfBirth": "YYYY-MM-DDD",
        "idNumber": "XXXXXXXX",
        "taxId": "XXXXXXXXX",
        "taxIdType": "CUIT",
        "gender": "F"
    },
```

### Field Mapping (DPA Restricted)

| Jumio Output | Description                           |
| ------------ | ------------------------------------- |
| fullName     | Individual’s registered name          |
| dateOfBirth  | Date of birth on record               |
| idNumber     | Documento Nacional de Identidad (DNI) |
| taxId        | Taxpayer identification number        |
| taxIdType    | Taxpayer type – CUIT or CUIL          |
| gender       | Gender (M = Male, F = Female)         |

### Response Example with PII Fields

```
"capabilities": {
        "govtIdVerification": [
            {
                "id": "e7e765ec-e282-4bbe-9d49-2dea489f5432",
                "credentials": [
                    {
                        "id": "edf900eb-0bec-4f07-9c8c-276ac29a00af",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "country": "ARG",
                    "type": "ID_CARD",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "sexMatch": "MATCH",
                    "message": "Not Deceased",
                    "fullName": "XXXXXXXXXXX",
                    "dateOfBirth": "YYYY-MM-DD",
                    "idNumber": "XXXXXXXX",
                    "taxId": "XXXXXXXXXX",
                    "taxIdType": "CUIT",
                    "gender": "F"
                },
.....
      }
    ]
}
```

:::warning
DNI numbers and names may be partially masked in logs and documentation examples to comply with data protection requirements.
:::

---

# Argentina Renaper Biometric Verification

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/Argentina/biometricArgentina

# Argentina Renaper Biometric Verification

Biometric Verification checks a Selfie provided by the end user against the photo on record with Renaper. The ID number and selfie are provided as inputs, along with name and gender data, and a decision on the risk is returned in the response.

## Supported Credentials

The Renaper number can be uploaded as Prepared Data. Alternatively, it can be extracted by an upstream capability in a workflow. The Selfie can be uploaded through the API, or obtained as part of the customer journey.

To use the API to upload Prepared Data and the Selfie use workflow key 10093. The Selfie will be checked by the Usability capability prior to calling the biometricVerification capability.

To use Renaper Verification along with the standard Jumio IDIV service use workflow key 10094.

The following value can be uploaded as Prepared Data.

<details>
| Key               | Type   | Mandatory | Description                                      |
|-------------------|--------|-----------|--------------------------------------------------|
| firstName         | string | no        | First name of the subject. Optimal to include    |
| lastName          | string | no        | Last name of the subject. Optimal to include     |
| middleName        | string | no        | Middle name of the subject.                      |
| sex               | string | yes       | M - Male / F - Female                            |
| address.country   | string | yes       | Country in ISO Alpha-3 format only, e.g., "ARG". |
| id                | Object | yes       | ID-related details                               |
| id.idNumber       | string | yes       | DNI number .                                     |
</details>

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

Example Response

```
"biometricVerification": [
            {
                "id": "4c9de7c7-0e91-4476-a303-dde196357ec5",
                "credentials": [
                    {
                        "id": "b0e79c4e-b0e9-4121-bc93-a67b8e1ffc85",
                        "category": "ID"
                    },
                    {
                        "id": "233641de-2a97-4764-9153-180308145a00",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "MEDIUM_RISK"
                    }
                },
                "data": {
                    "nameMatch": "MATCH",
                    "faceMatch": "PARTIAL_MATCH",
                    "idNumberMatch": "MATCH",
                    "genderMatch": "MATCH"
                }
            }
```

### Decision Details Labels

<details>
| **Decision Type** | **Label**           | **Description**                                              |
|-------------------|---------------------|--------------------------------------------------------------|
| PASSED            | LOW_RISK            | The provided Selfie matches the photo on record.             |
| REJECTED          | HIGH_RISK           | The provided Selfie does not match the photo on record.      |
| WARNING           | MEDIUM_RISK         | It cannot be determined whether the Selfie matches the photo on record. |
| NOT_EXECUTED      | TECHNICAL_ERROR     | Verify the provided data is correct and retry, or contact [Support](https://support.jumio.com/s/). |
| NOT_EXECUTED      | PERMISSION_DENIED   |  Cannot be executed because the required permissions or credentials are missing. Verify your API key and access rights.                                                            |
| NOT_EXECUTED      | BAD_REQUEST         | Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying.                                                             |

</details>

### Data

<details>

| Key             | Possible Values                 | Description                                                                                                                                                                                                                          |
| --------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nameMatch`     | MATCH, NOT_MATCH                | Indicates whether the concatenated `firstName` and `lastName` values provided in the input data exactly match the corresponding name stored in the Renaper database.                                                                 |
| `faceMatch`     | MATCH, NOT_MATCH, PARTIAL_MATCH | Indicates the result of the face comparison between the submitted selfie and the photo on record in the Renaper database. A `PARTIAL_MATCH` means some facial similarity was detected, but not enough to be considered a full match. |
| `idNumberMatch` | MATCH, NOT_MATCH                | Indicates whether the identification number provided in the input data matches a valid identification number stored in the Renaper database.                                                                                         |
| `genderMatch`   | MATCH, NOT_MATCH                | Indicates whether the gender provided in the input data matches the gender stored in the Renaper database.                                                                                                                           |

</details>

## PII Fields Returned (DPA Restricted)

The following PII fields from the Argentina Biometric check API response will be returned ONLY for customers who have signed the updated Data Processing Agreement (DPA). This feature is disabled by default and must be explicitly enabled by Jumio. Please work with your Jumio account manager if you require this.

```
"data": {
                    "faceMatch": "MATCH",
                    "idNumberMatch": "MATCH",
                    "genderMatch": "MATCH",
                    "fullName": "MXXXX RXXXX",
                    "dateOfBirth": "YYYY-MM-DD",
                    "idNumber": "XXXXXX",
                    "taxId": "XXXXXXX",
                    "taxIdType": "CUIT",
                    "gender": "M"
}
```

### Field Mapping (DPA Restricted)

| Jumio Output | Description                           |
| ------------ | ------------------------------------- |
| fullName     | Individual’s registered name          |
| dateOfBirth  | Date of birth on record               |
| idNumber     | Documento Nacional de Identidad (DNI) |
| taxId        | Taxpayer identification number        |
| taxIdType    | Taxpayer type – CUIT or CUIL          |
| gender       | Gender (M = Male, F = Female)         |

### Response Example with PII Fields

```
{
  "biometricVerification": [
    {
      "id": "f1a60eca-536f-4907-8661-8707a49d3df2",
      "credentials": [
        {
          "id": "bea35edd-92a3-4357-89a0-f7f7cc755c76",
          "category": "DATA",
          "label": "DATA"
        },
        {
          "id": "93bc29d7-20a5-41f5-9af5-8b3618a21667",
          "category": "SELFIE",
          "label": "SELFIE"
        }
      ],
      "decision": {
        "type": "PASSED",
        "details": {
          "label": "LOW_RISK"
        }
      },
      "data": {
        "faceMatch": "MATCH",
        "idNumberMatch": "MATCH",
        "genderMatch": "MATCH",
        "fullName": "MXXXXX RXXXX",
        "dateOfBirth": "YYYY-MM-DD",
        "idNumber": "12345678",
        "taxId": "12345678912",
        "taxIdType": "CUIT",
        "gender": "M"
      }
    }
  ]
}
```

:::warning
DNI numbers and names may be partially masked in logs and documentation examples to comply with data protection requirements.
:::

---

# Brazilian CPF Number Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/Brazilian/brazilianCPFCheck

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Brazilian CPF Number Check

The Jumio CPF check allows customers to validate the CPF Number. CPF is the Brazilian Individual Taxpayer Registry Identification number, referred to as Cadastro de Pessoas Fisicas (Portuguese for “Natural Persons Register”). A CPF number is a permanent number printed on current driver’s licenses (DL) & ID versions. A CPF number is assigned to both Brazilians and resident aliens who are subject to taxes in Brazil.

The CPF Number Validation service will send the extracted CPF number from the DL & ID to the Tax ID database in order to:

- Retrieve the status of the CPF number.
- Compare the name returned from the database with the name provided for the transaction.
- Map the results and return the status of the match.

## Supported Credentials

The following values can be uploaded as [prepared data](../../../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

To use Prepared Data with the CPF Number Check as a standalone capability use workflow key 10020.

<details>
| **Key**         | **Type** | **Mandatory** | **Description**                                           |
| --------------- | -------- | ------------- | --------------------------------------------------------- |
| id.idNumber     | string   | yes           | For Brazil, this will be CPF number                       |
| id.type         | string   | no            | `ID_CARD` or `DL`                                         |
| firstName       | string   | yes           | Must include firstName or lastName, and may include both. **First Name** is required only for the version that does not provide the raw response when a DPA is signed. The DPA-enabled version can operate using only the ID. |
| lastName        | string   | yes           | Must include firstName or lastName, and may include both. **Last Name** is required only for the version that does not provide the raw response when a DPA is signed. The DPA-enabled version can operate using only the ID.|
| dateOfBirth     | string   | no            | YYYY-MM-DD. Will influence risk score if provided.        |
| address.country | string   | yes           | Country should be ISO Alpha 3 Code only                   |
</details>

:::tip
The concatenated values of the firstName and lastName fields are matched against the name on record for the CPF number.
:::

## Example Prepared Data Body

```
{
   "firstName": "pris****",
   "lastName": "da *****",
   "dateOfBirth":"1982-MM-08",
   "address": {
      "country": "BRA"
   },
   "id":{
       "idNumber":"28908936***",
       "type":"ID_CARD"
   }

 }
```

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

**Example Response**

<Tabs>
  <TabItem value="Success" label="Success">
```
"capabilities": {
        "govtIdVerification": [
            {
                "id": "222b58e7-7954-4abc-8180-7500518b2ed8",
                "credentials": [
                    {
                        "id": "56cbb7d8-184e-469a-9c6e-77c0b89f9ab1",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "completeNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH"
                }
            }
        ] }
```
  </TabItem>

<TabItem value="Fail" label="Fail">

```
"capabilities": {
        "govtIdVerification": [
            {
                "id": "a65880f6-cb9a-4cc1-b1fc-d391be0b8a3c",
                "credentials": [
                    {
                        "id": "73b0dc00-af42-41f6-ab7c-909027297b7f",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "NOT_EXECUTED",
                    "details": {
                        "label": "PRECONDITION_NOT_FULFILLED"
                    }
                },
                "data": {
                    "country": "BRA",
                    "type": "ID_CARD",
                    "reasonMessage": "cpf_invalid"
                }
            }
        ] }
```

  </TabItem>
</Tabs>

## Decision Details Labels

<details>
| **Decision Type**    | **Label**    | **Description**                                                                 |
|----------------------|--------------|---------------------------------------------------------------------------------|
| PASSED               | OK           | The provided data matched                                                       |
| REJECTED             | DENY         | The provided data did not match what was on record.                             |
| WARNING              | ALERT        | The CPF number is valid but either the name or DOB do not exactly match.       |
| NOT_EXECUTED         | NOT_ENOUGH_DATA | The provided data was inadequate to process the transaction.                   |
| NOT_EXECUTED         | TECHNICAL_ERROR |   An error occurred during device risk evaluation. Verify input and retry, or contact [Support](https://support.jumio.com/s/).                                                                              |
</details>

## Data

<details>
| **Key**             | **Possible Values**    | **Description**                                                                                   |
|---------------------|------------------------|---------------------------------------------------------------------------------------------------|
| nameMatch           | `MATCH`, `NOT_MATCH`    | To be a `MATCH` the concatenated firstName and lastName value of the input data must exactly match what is in the CPF database. |
| cpfMatch            | `MATCH`, `NOT_MATCH`    | CPF number matches.                                                                                |
| dateOfBirthMatch    | `MATCH`, `NOT_MATCH`    | Date of birth matches.                                                                             |

</details>

### Additional Status Flags

<details>

| **Parameter**                | **Type** | **Note**                                                                             |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `data.suspended`             | boolean  | true / false. Indicates if the license is suspended.                                 |
| `data.deceased`              | boolean  | true / false. Indicates if the individual is marked deceased.                        |
| `data.cancelled`             | boolean  | true / false. Indicates if the license is cancelled.                                 |
| `data.regularizationPending` | boolean  | true / false. Indicates if there are pending regularization issues with the license. |
| `data.cancellationReason`    | string   | Provides details on the cancellation reason.                                         |
| `data.reasonMessage`         | string   | Additional explanation of the status.                                                |

</details>

## Raw Serpro Consulta CPF Fields (DPA Restricted)

The following raw fields from the Serpro Consulta CPF API response will be returned ONLY for customers who have signed the updated Data Processing Agreement (DPA). This feature is disabled by default and must be explicitly enabled by Jumio.

```json
"cpfData": "{\"cpf\":\"7XXXXXXXXX80\",\"name\":\"JOSE XXXXXXXXX SILVA\",\"details\":{\"code\":\"0\",\"description\":\"Regular\"},\"dateOfBirth\":\"XX12XXXX\"}"
```

### Field Mapping

| Serpro Field                  | Jumio Output        | Description                                         |
| ----------------------------- | ------------------- | --------------------------------------------------- |
| ni                            | CPF number          | Taxpayer identification number                      |
| name                          | Full name           | Individual’s registered name                        |
| situacao (code + description) | Registration status | Status of the CPF number (refer to the table below) |
| nascimento                    | Date of birth       | Date of birth on record                             |

### Situacao Status Code Reference

| Code | Label                      | Description                                           |
| ---- | -------------------------- | ----------------------------------------------------- |
| 0    | Regular                    | CPF is valid with no issues                           |
| 2    | Suspended                  | Registration has inconsistencies                      |
| 3    | Deceased Holder            | The CPF owner is deceased                             |
| 4    | Pending Regularization     | Missing recent tax returns                            |
| 5    | Canceled – Multiplicity    | Duplicate CPFs exist, canceled to resolve duplication |
| 8    | Null (Annulled)            | CPF invalidated due to detected fraud                 |
| 9    | Canceled by Official Order | Canceled by administrative or judicial order          |

### Response Example with Raw Fields (braCpfValidation)

```json
"braCpfValidation": [
    {
        "id": "79e0fa63-0ff5-4bab-99b2-bb9c49637ba2",
        "credentials": [
            {
                "id": "1ceaf3c0-2689-43ea-93aa-187c2ba5da51",
                "category": "DATA"
            }
        ],
        "decision": {
            "type": "PASSED",
            "details": { "label": "OK" }
        },
        "data": {
            "nameMatch": "MATCH",
            "cpfMatch": "MATCH",
            "dateOfBirthMatch": "MATCH",
            "cpfData": {
                "cpf": "7XXXXXXXXX80",
                "name": "JOSE XXXXXXXXX SILVA",
                "details": { "code": "0", "description": "Regular" },
                "dateOfBirth": "XX05XXXX"
            }
        }
    }
]
```

:::warning
CPF numbers and names may be partially masked in logs and documentation examples to comply with data protection requirements.
:::

---

# Brazilian CPF Biometric Verification

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/Brazilian/brazilianCPFBiometric

# Brazilian CPF Biometric Verification

Biometric Verification checks a Selfie provided by the end user against the photo on record with the Brazilian CPF data. The CPF number and selfie are provided as inputs, and a decision on the risk is returned in the response.

## Supported Credentials

The CPF number can be uploaded as Prepared Data. Alternatively, it can be extracted by an upstream capability in a workflow. The Selfie can be uploaded through the API, or obtained as part of the customer journey.

To use the API to upload Prepared Data and the Selfie use workflow key 10006. The Selfie will be checked by the Usability capability prior to calling the biometricVerification capability.

To use Biometric Verification along with the standard Jumio IDIV service and the CPF Number check service, use workflow key 10021.

The following value can be uploaded as Prepared Data.

| **Key**        | **Type** | **Mandatory** | **Description** |
| -------------- | -------- | ------------- | --------------- |
| personalNumber | string   | yes           | The CPF number  |

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see [viewing or retrieving workflow transactions](../../../../developer-resources/retrieving-results/retrieval).

Example Response

```
"biometricVerification":[
   {
      "id":"14be80df-e3b4-4ce8-aa55-bccf52464ae4",
      "credentials":[
         {
            "id":"d20757d8-2979-4805-b64b-30e75afec88f",
            "category":"DATA"
         },
         {
            "id":"487578ce-36d4-45d1-bdd0-fe5702ba2443",
            "category":"SELFIE"
         }
      ],
      "decision":{
         "type":"PASSED",
         "details":{
            "label":"LOW_RISK"
         }
      },
      "data":{
         "nameMatch":"MATCH",
         "dobMatch":"MATCH",
         "nationalIdMatch":"NOT_MATCH",
         "faceMatch":"MATCH"
      }
   }
   ...
]
```

## Decision Details Labels

| **Decision Type** | **Label**                          | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PASSED            | LOW_RISK                           | The provided Selfie matches the photo on record.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| REJECTED          | HIGH_RISK                          | The provided Selfie does not match the photo on record.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| WARNING           | MEDIUM_RISK                        | It cannot be determined whether or not the provided Selfie matches the photo on record.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| NOT_EXECUTED      | TECHNICAL_ERROR                    | Verify the provided data is correct and retry, or [contact Support](https://support.jumio.com/s/).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| NOT_EXECUTED      | PERMISSION_DENIED                  | The request is not authorized to access the service.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| NOT_EXECUTED      | BAD_REQUEST                        | Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| NOT_EXECUTED      | UNABLE_TO_VERIFY_PHOTO_WITH_VENDOR | The submitted face image could not be successfully verified by the vendor. To complete the verification process, please upload a new photo that meets the following requirements: <ul> <li> `Clear and Visible` - Ensure only one face is present in the image, clearly visible, well-lit, and free from blur or obstructions.</li> <li>`Proper Framing` - Position your face in the center of the frame and ensure it is fully captured within the image boundaries.</li> <li> `Correct Format` - Upload a supported image file format (such as JPEG or PNG) and ensure the file is not corrupted and uploads successfully. </li> </ul> |

## Data

| **Key**         | **Possible Values**               | **Description**                                                                                                                 |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| nameMatch       | `MATCH`, `NOT_MATCH`              | To be a `MATCH` the concatenated firstName and lastName value of the input data must exactly match what is in the CPF database. |
| nationalIdMatch | `MATCH`, `NOT_MATCH`              | nationalIdMatch number matches or not.                                                                                          |
| dobMatch        | `MATCH`, `NOT_MATCH`              | Date of birth matches or not.                                                                                                   |
| faceMatch       | `MATCH`, `NOT_MATCH`, `Not_Found` | Selfie matches the photo on record.                                                                                             |

---

# Colombian Registraduria Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/checkColombianRegistraduria

# Colombian Registraduria Check

Jumio has a database check service available for the Colombian Registraduria database. This check verifies that a provided Colombian ID number and related user information corresponds to existing government records.

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../../references/credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

To use with the standard Jumio IDIV service use workflow key 10054.

To use Prepared Data with the Colombian Registradurias Check as a standalone capability use workflow key 10020.

<details>

| **Key**         | **Type**  | **Mandatory** | **Description**                                            |
| --------------- | --------- | ------------- | ---------------------------------------------------------- |
| firstName       | string    | yes           |                                                            |
| lastName        | string    | yes           |                                                            |
| middleName      | string    | no            |                                                            |
| paternalSurname | string    | no            |                                                            |
| maternalSurname | string    | no            |                                                            |
| dateOfBirth     | LocalDate | yes           | Date of birth in `YYYY-MM-DD` format only                  |
| id              | object    | yes           | See in next row                                            |
| id.idNumber     | string    | yes           | NUIP number. Do not include periods. Example: `1234567890` |
| id.type         | string    | yes           | Possible values: `DRIVING_LICENSE`, `PERMIT`, `ID_CARD`    |
| id.issuingDate  | string    | no            | Date the ID was issued in `YYYY-MM-DD` format only         |
| address         | object    | yes           |                                                            |
| address.country | string    | yes           | Country in `ISO-3166-1 Alpha-3 Code` format                |

</details>

## Sample Prepared Data Body

```
{
    "firstName": "XXXXXX",
    "lastName": "XXXXXX",
    "dateOfBirth": "1959-04-22",
    "paternalSurname": "XXXXXX",
    "maternalSurname": "XXXXXX",
    "address": {
        "country": "COL" )
    },
    "id": {
        "idNumber": "XXXXXXXXXX",
        "type": "ID_CARD",
        "issuingDate": "1977-09-01"
    }
}
```

## Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

**Example Response**

```
"govtIdVerification": [
            {
                "id": "721a8178-162e-4ff4-8ab3-4194ceb0e310",
                "credentials": [
                    {
                        "id": "6248205a-3194-4a23-b5be-515306729583",
                        "category": "DATA",
                        "label": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "completeNameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "issuingDateMatch": "MATCH",
                    "paternalSurnameMatch": "MATCH",
                    "maternalSurnameMatch": "MATCH",
                    "statusCode": "0",
                    "statusDescription": "Valid/Active"
		}
            }
        ]
```

### Decision Details Labels

| **Decision Type** | **Label**                    | **Description**                                                         |
| ----------------- | ---------------------------- | ----------------------------------------------------------------------- |
| NOT_EXECUTED      | `PRECONDITION_NOT_FULFILLED` | Provided data is incomplete or incorrectly formatted.                   |
| NOT_EXECUTED      | `TECHNICAL_ERROR`            | The service encountered an error and was unable to process the request. |
| NOT_EXECUTED      | `PERMISSION_DENIED`          | The request is not authorized to access the service.                    |
| PASSED            | `OK`                         |                                                                         |
| WARNING           | `ALERT`                      | The NUIP number is valid but other data may not match.                  |
| REJECTED          | `DENY`                       | The NUIP number is invalid or does not match the provided data.         |

## Data

| **Key**                | **Type** | **Description**                                            |
| ---------------------- | -------- | ---------------------------------------------------------- |
| firstNameMatch\*       | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| lastNameMatch\*        | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| completeNameMatch\*    | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| nationalIdMatch        | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| dobMatch               | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| issuingDateMatch       | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| paternalSurnameMatch\* | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| maternalSurnameMatch\* | string   | Possible values: `MATCH`, `NOT_MATCH`                      |
| statusCode             | string   | Status code number.                                        |
| statusDescription      | string   | Description of the status associated with the status code. |

:::tip
The firstNameMatch, lastNameMatch, paternalSurnameMatch, and maternalSurnameMatch fields will be returned only if the granular name values are provided as Prepared Data.
:::

If the name is extracted from an ID document, only the completeNameMatch field will be returned, as shown in the following example:

```
"govtIdVerification": [
            {
                "id": "7502be48-390c-4796-989e-5000e59c7e8e",
                "credentials": [
                    {
                        "id": "38317d8c-7b5f-4b8f-b21a-f3757b1b86c1",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "country": "COL",
                    "type": "ID_CARD",
                    "completeNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "issuingDateMatch": "MATCH","statusCode": "0",
                    "statusDescription": "Valid/Active"
	},
```

---

# Thai DOPA Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/checkThai

# Thai DOPA Check

The Thai DOPA check compares provided credential data to data on record with the Thai Department of Provincial Administration (DOPA) records.

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../../references/credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

- To use the Thai DOPA check with data extracted from a Thai National ID Card use workflow key 10054.
- To use Prepared Data with the Thai DOPA Check as a standalone capability use workflow key 10020.

<details>    
| **Key**               | **Type**   | **Mandatory** | **Description**                                                     |
|-----------------------|------------|---------------|---------------------------------------------------------------------|
| id.idNumber           | string     | yes           | The Identification Number from the Thai National ID Card            |
| id.secondaryIdNumber  | string     | yes           | The laser number on the back of the Thai National ID Card           |
| id.type               | string     | no            | Possible values: `ID_CARD`                                          |
| firstName             | string     | yes           | First name (must be in Thai)                                        |
| lastName              | string     | yes           | Last name (must be in Thai)                                         |
| dateOfBirth           | string     | yes           | Format: `YYYY-MM-DD`                                                |
| address.country       | string     | yes           | Country should be `THA` (ISO Alpha 3 Code for Thailand)             |
</details>

### Example Prepared Data Body

```
{
    "firstName": "วิสิทธิ์",
    "lastName": "วงศ์พิพันธ์",
    "dateOfBirth": "1959-03-27",
    "address": {
        "country": "THA"
    },
    "id": {
        "idNumber": "3800400217161",
        "secondaryIdNumber" : "JC3159691039",
        "type": "ID_CARD",
        "subType": "NATIONAL_ID"

    }
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

**Example Response**

```
"govtIdVerification": [
            {
                "id": "ba86037a-1380-4cc4-b410-e609cc7035a9",
                "credentials": [
                    {
                        "id": "16eab951-21bc-46f6-a1d9-e8ce1f25b33c",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "personalIdNumberMatch": "MATCH"
                }
            }
        ]
```

#### Decision Details Labels

| **Decision Type** | **Label**                     | **Description**                                                                          |
| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
| PASSED            | `OK`                          | The provided data matched                                                                |
| REJECTED          | `DENY`                        | The provided data did not match what was on record. See Data for additional information. |
| NOT_EXECUTED      | `PRECONDITIONS_NOT_FULFILLED` | The provided data was inadequate to process the transaction.                             |
| NOT_EXECUTED      | `TECHNICAL_ERROR`             | The service encountered an error and was unable to process the request.                  |

#### Data

| **Key**               | **Possible Values**  | **Description**                                        |
| --------------------- | -------------------- | ------------------------------------------------------ |
| firstNameMatch        | `MATCH`, `NOT_MATCH` | firstName value matches the DOPA record.               |
| lastNameMatch         | `MATCH`, `NOT_MATCH` | lastName value matches the DOPA record.                |
| dobMatch              | `MATCH`, `NOT_MATCH` | Date of birth matches the DOPA record.                 |
| nationalIdMatch       | `MATCH`, `NOT_MATCH` | idNumber matches the DOPA record.                      |
| personalIdNumberMatch | `MATCH`, `NOT_MATCH` | secondaryIdNumber matches the DOPA personal ID number. |

---

# Mexican INE Data & Face Validation

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/mexicanINEDataFace

# Mexican INE Data & Face Validation

Jumio has a number of database check services available for Mexico. These checks allow you to validate Mexican National IDs and personal identifiable information.

This service connects with the Mexican National Electoral Institute (Instituto Nacional Electoral, INE) to validate INE ID numbers, owner information and biometric information. There are 2 services that are available for INE:

## 1. Data Validation of Voting credential at INE.

- Verifies that the data registered at INE’s nominal database matches those presented by the user.
- Validates that the credential is a valid document.
  ![image](../img/INE_Data_Face_Validation.png)

## 2. Biometric Validation of Voting credential at INE.

Verifies that the face of the user matches that registered in the INE.

:::info
The data validation and Biometric validation services both require a direct contract with the INE. Please see your Jumio Sales representative for more information. We work with a partner to directly integrate with INE.
:::

![image](../img/INE_Data.png)

| **Service Name**           | **Description**                   | **Required Fields**       | **Verifiable Fields**                                                                                                                                     |
| -------------------------- | --------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mexico INE Data Validation | Input is verified against the INE | Elector Key, OCR, Issue # | Name, Paternal Surname, Maternal Surname, Curp #(National Id), OCR#, Elector Key, Registration Year, Issuing Year, Issuing Number                         |
| Mexico INE Face Validation | Input is verified against the INE | Elector Key, OCR, Issue # | Selfie Image, Name, Paternal Surname, Maternal Surname, Face Match, OCR#, Elector Key, Registration Year, Issuing Year, Issuing Number, Curp #(Id number) |

## Customer Onboarding

Due to the nature of the integration with INE, we will work with our partner to stand up a dedicated secure infrastructure that is required by the Mexican Government to access INE. Once the contract with INE is signed, our production team will work you and our partner (FIMPE) to start the onboarding process.

Our production team needs the following information:

AWS Region and Stage where Middleware needs to be deployed.

Tenant Information:

- Tenant GUID
- Tenant Id
- Tenant Name

FIMPE Middleware Key files(provided by FIMPE):

- INSTITUTONACIONALELECTORAL_publica.key
- MW_KEYS_TO_SVBI_PRIVATE_MW_KEY
- publica.key
- privada.key
- FIMPE SVBI Port Number(provided by FIMPE)

The estimated time needed for completion:

- 4-5 days/client to setup the environments
- 2 days/client for the Engineering team to test and certify the setup and functionality.

### Required Credentials

<details>
<summary>Prepared Data: INE Data </summary>
| **Key**               | **Type**    | **Mandatory** | **Description**                                               |
|-----------------------|-------------|---------------|---------------------------------------------------------------|
| firstName             | string      | no            |  First name of the subject. Optimal to include.                                                               |
| paternalSurname       | string      | no            |  Paternal surname of the subject.                                                             |
| maternalSurname       | string      | no            |   Maternal surname of the subject.                                                            |
| address              | Object      | no            | Only the fields which are mentioned are required              |
| address.country      | string      | no            | country should be set to “MEX”                                |
| id                    | Object      | no            | See in next row                                               |
| id.idNumber          | string      | no            | CURP ID number # example "XXXX910225XXXXXS09"                 |
| id.Type              | string      | conditional   | ID_CARD                                                       |
| id.subType           | string      | no            |  Only required for countries where idType is not sufficient.                                                             |
| id.issuingDate       | string      | no            | Date in YYYY-MM-DD format only.                                                              |
| id.expiryDate        | string      | no            |  Date in YYYY-MM-DD format only.                                                             |
| ine                   | Object      | yes           | See in next row                                               |
| ine.cic               | string      | no            | CIC number of the elector credential                          |
| ine.ocr               | string      | yes           | OCR number of the elector credential                          |
| ine.issuingNumber     | string      | yes           | Issuing Number - Numeric                                      |
| ine.electorKey        | string      | yes           | Elector Key - 18 Characters                                   |
| ine.registrationYear  | string      | no            | YYYY                                                          |
| ine.issuingYear       | string      | no            | YYYY                                                          |

</details>

### Capability Request

```
{
    "firstName": "XXXXX",
    "paternalSurname": "XXXXXX",
    "maternalSurname": "XXXXX",
    "address": {
        "country": "MEX"
    },
    "id": {
        "idNumber": "XYZA891218ABCEFG01",
        "type": "ID_CARD",
        "subType": "",
        "issuingDate": "",
        "expiryDate": ""
    },
    "ine": {
        "cic": "201112341",
        "ocr": "0000345678911", <mandatory>
        "issuingNumber": "02", <mandatory>
        "electorKey": "ABCDEF12341809C100",<mandatory>
        "registrationYear": 2008,
        "issuingYear": 2019
    }
}
```

### Response Values

<details>
| **Parameter**                | **Type**                  | **Note**                                                                                 |
|------------------------------|---------------------------|------------------------------------------------------------------------------------------|
| id                           | string                    | UUID of the capability                                                                  |
| credentials                  | array(Credential)         |                                                                                          |
| decision                     | object                    |                                                                                          |
| decision.type                | string                    | **Possible values**: `NOT_EXECUTED`, `PASSED`, `REJECTED`, `WARNING`                    |
|                              |                           | If curp # is a mismatch, `decision = REJECT`, risk score 100, else:                      |
|                              |                           | If elector key, ocr, and name are a match, `decision = PASS`, risk score 0, else `decision = WARNING`, risk score 50 |
| decision.details             | object                    |                                                                                          |
| decision.details.label       | string                    | **Possible values**: `OK`, `DENY`, `ALERT`, `NOT_ENOUGH_DATA`, `TECHNICAL_ERROR`, `PERMISSION_DENIED`, `BAD_REQUEST`, `PRECONDITION_NOT_FULFILLED` |
| data                         | object                    |                                                                                          |
| data.completeNameMatch       | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.nationalIdMatch         | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.ocrMatch                | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.issuingNumberMatch      | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.registrationYearMatch   | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.issuingYearMatch        | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.electorKeyMatch         | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.paternalSurnameMatch    | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |
| data.maternalSurnameMatch    | string                    | **Possible values**: `MATCH`, `NOT_MATCH`                                                 |

</details>

## Credential

| **Key**  | **Type** | **Description**             |
| -------- | -------- | --------------------------- |
| id       | string   | UUID of credential used     |
| category | string   | Category of credential used |

### Capability Response

```
"govtIdVerification": [
            {
                "id": "d1858198-d2f2-4235-97f7-5f9cb088a2ae",
                "credentials": [
                    {
                        "id": "21135260-f435-4052-93a7-a943f12d5f2c",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "ALERT"
                    }
                },
                "data": {
                    "completeNameMatch": "NOT_MATCH",
                    "nationalIdMatch": "MATCH",
                    "ocrMatch": "MATCH",
                    "issuingNumberMatch": "NOT_MATCH",
                    "registrationYearMatch": "NOT_MATCH",
                    "issuingYearMatch": "MATCH",
                    "electorKeyMatch": "MATCH",
                    "paternalSurnameMatch": "MATCH",
                    "maternalSurnameMatch": "MATCH"
                }
            }
        ]
```

## Required Credentials for Prepared Data: INE Data with Biometric (Selfie)

<details>
<summary>Required Credentials</summary>
| **Key**               | **Type**    | **Mandatory** | **Description**                                               |
|-----------------------|-------------|---------------|---------------------------------------------------------------|
| firstName             | string      | no            |                                                               |
| paternalSurname       | string      | no            |                                                               |
| maternalSurname       | string      | no            |                                                               |
| address              | Object      | no            | Only the fields which are mentioned are required              |
| address.country      | string      | no            | country should be set to “MEX”                                |
| id                    | Object      | no            | See in next row                                               |
| id.idNumber          | string      | no            | CURP ID number # example "XXXX910225XXXXXS09"                 |
| id.Type              | string      | conditional   | ID_CARD                                                       |
| id.subType           | string      | no            |                                                               |
| id.issuingDate       | string      | no            |                                                               |
| id.expiryDate        | string      | no            |                                                               |
| ine                   | Object      | yes           | See in next row                                               |
| ine.cic               | string      | no            | CIC number of the elector credential                          |
| ine.ocr               | string      | yes           | OCR number of the elector credential                          |
| ine.issuingNumber     | string      | yes           | Issuing Number - Numeric                                      |
| ine.electorKey        | string      | yes           | Elector Key - 18 Characters                                   |
| ine.registrationYear  | string      | no            | YYYY                                                          |
| ine.issuingYear       | string      | no            | YYYY                                                          |
</details>

:::note
Biometric (Selfie) needs to be sent with Prepared Data.
:::

### Capability Request

```
{
    "firstName": "XXXXX",
    "paternalSurname": "XXXXXX",
    "maternalSurname": "XXXXX",
    "address": {
        "country": "MEX"
    },
    "id": {
        "idNumber": "XYZA891218ABCEFG01",
        "type": "ID_CARD",
        "subType": "",
        "issuingDate": "",
        "expiryDate": ""
    },
    "ine": {
        "cic": "201112341",
        "ocr": "0000345678911", <mandatory>
        "issuingNumber": "02", <mandatory>
        "electorKey": "ABCDEF12341809C100",<mandatory>
        "registrationYear": 2008,
        "issuingYear": 2019
    }
}
```

### Response Values

<details>

| **Parameter**              | **Type**          | **Note**                                                                                                                                           |
| -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                         | string            | UUID of the capability                                                                                                                             |
| credentials                | array(Credential) |                                                                                                                                                    |
| decision                   | object            |                                                                                                                                                    |
| decision.type              | string            | **Possible values**: `NOT_EXECUTED`, `PASSED`, `REJECTED`, `WARNING`                                                                               |
|                            |                   | If `curp` is a mismatch and face similarity is &lt;=50%, `decision = REJECT`, risk score is 100, else:                                             |
|                            |                   | If the elector key, ocr, and name match with similarity &gt;=85%, `decision = PASS`, risk score = 0, else `decision = WARNING`. Risk score = 50    |
| decision.details           | object            |                                                                                                                                                    |
| decision.details.label     | string            | **Possible values**: `OK`, `DENY`, `ALERT`, `NOT_ENOUGH_DATA`, `TECHNICAL_ERROR`, `PERMISSION_DENIED`, `BAD_REQUEST`, `PRECONDITION_NOT_FULFILLED` |
| data                       | object            |                                                                                                                                                    |
| data.NameMatch             | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.faceMatch             | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.ocrMatch              | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.issuingNumberMatch    | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.registrationYearMatch | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.issuingYearMatch      | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.electorKeyMatch       | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.paternalSurnameMatch  | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.maternalSurnameMatch  | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |
| data.idNumberMatch         | string            | **Possible values**: `MATCH`, `NOT_MATCH`                                                                                                          |

</details>

### Credential

| **Key**  | **Type** | **Description**             |
| -------- | -------- | --------------------------- |
| id       | string   | UUID of credential used     |
| category | string   | Category of credential used |

### Capability Response

```
"biometricVerification": [
  {
    "id": "c0015f7b-0999-4682-a1a6-a10241a01f7c",
    "credentials": [
      {
        "id": "36b715ee-2822-488d-ac2a-159536645411",
        "category": "DATA"
      },
      {
        "id": "adce826e-a43d-45d4-84f7-80e2b917fda1",
        "category": "SELFIE"
      }
    ],
    "decision": {
      "type": "REJECTED",
      "details": {
        "label": "HIGH_RISK"
      }
    },
    "data": {
      "nameMatch": "NOT_MATCH",
      "faceMatch": "NOT_MATCH",
      "ocrMatch": "MATCH",
      "issuingNumberMatch": "NOT_MATCH",
      "registrationYearMatch": "NOT_MATCH",
      "issuingYearMatch": "MATCH",
      "electorKeyMatch": "MATCH",
      "paternalSurnameMatch": "MATCH",
      "maternalSurnameMatch": "MATCH",
      "idNumberMatch": "MATCH"
    }
  }
]

```

---

# Mexican INE Credential Validation (Lista Nominal)

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/mexicanINECred

# Mexican INE Credential Validation (Lista Nominal)

Jumio has a number of database check services available for Mexico. These checks allow you to validate Mexican National IDs and personal identifiable information.
This service connects with the Mexican National Electoral Institute (Instituto Nacional Electoral, INE) to validate INE ID numbers against the official Lista Nominal database.
The service validates only specific INE credential fields and does not compare personal identifiable information (PII) such as names, phone numbers, or email addresses.

<center>![image](../img/INE_lista_Credential_Validation.png)</center>

| **Service Name**                 | **Description**                                | **Required Fields**                             | **Verifiable Fields**                                             |
| -------------------------------- | ---------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
| Mexico INE Credential Validation | Input is verified against the INE Nominal list | Elector key, CIC, Citizen ID/OCR, Issue #, Type | Elector key Match / No Match, OCR/Citizen ID, CIC, Issuing number |

:::note
Required fields may vary due to the version of the INE card.
:::

## Supported Credentials

The following is a nominal list of required values. They can be uploaded as [prepared data](../../credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

<details>
| **Key**                | **Type** | **Mandatory** | **Description**                                                                              |
| ---------------------- | -------- | ------------- | -------------------------------------------------------------------------------------------- |
| `address.country`      | string   | yes           | Must be set to `MEX` (ISO Alpha 3 Code for Mexico).                                          |
| `id.type`              | string   | yes           | Must be `ID_CARD`.                                                                           |
| `ine.cic`              | string   | yes           | CIC number of the INE credential.                                                            |
| `ine.ocr`              | string   | yes           | OCR number of the INE credential (for card types C–F).                                       |
| `ine.citizenID`        | string   | yes           | Same as `OCR` for card types G–H, where the field name changed to *Identificador ciudadano*. |
| `ine.electorKey`       | string   | yes           | Elector key (Clave de Elector).                                                              |
| `ine.issuingNumber`    | string   | yes           | Issue number (Número de emisión).                                                            |
| `ine.registrationYear` | integer  | yes           | Year of registration on the INE credential.                                                  |
| `ine.type`             | string   | yes           | Type of INE card (C, D, E, F, G, or H).                                                      |

</details>

:::note
Lista Nominal validation is not dependent on card type. Only the above INE credential fields are required.
:::

## Capability Request (Card Type H or E)

```
{
  "address": {
    "country": "MEX"
  },
  "id": {
    "type": "ID_CARD"
  },
  "ine": {
    "cic": "156885641",
    "ocr": "3614093418420",
    "electorKey": "XXXXXX92082030X700",
    "issuingNumber": "08",
    "registrationYear": 2001,
    "type": "H" // (Card Type can be H or E)
  }
}
```

:::note
The Lista Nominal service validates only the ine fields listed above.
PII data such as names, contact information, or address details are not validated.
:::

## Response

```
"govtIdVerification": [
  {
    "id": "49726009-a68a-4ad0-a099-98c0a4613b2e",
    "credentials": [
      {
        "id": "86d416e5-76b8-49ec-9ad2-20b530b8e947",
        "category": "DATA"
      }
    ],
    "decision": {
      "type": "PASSED",
      "details": {
        "label": "OK"
      }
    },
    "data": {
      "ocr": "MATCH",
      "issueNumber": "MATCH",
      "registrationYear": "MATCH",
      "issueYear": "MATCH",
      "electorKey": "MATCH",
      "message": "Valid as ID and you can vote"
    }
  }
]
```

## Decision Details Labels

<details>
| **Decision Type** | **Label**                  | **Description** |
| ----------------- | -------------------------- | --------------- |
| PASSED            | OK                         | Provided data matches DMV data.                |
| REJECTED          | DENY                       | Provided data does not match DMV data.                 |
| WARNING           | ALERT                      | Provided data partially matches DMV data.                |
| NOT_EXECUTED      | PERMISSION_DENIED          | Cannot be executed because the required permissions or credentials are missing. Verify your API key and access rights.                 |
| NOT_EXECUTED      | NOT_ENOUGH_DATA            |  Not enough data to process the request.                 |
| NOT_EXECUTED      | BAD_REQUEST                |  Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying.               |
| NOT_EXECUTED      | PRECONDITION_NOT_FULFILLED | Preconditions were not met to process the data.                |
| NOT_EXECUTED      | TECHNICAL_ERROR            | Verify the provided data is correct and retry, or contact [Support](https://support.jumio.com/s/).             |
</details>

## Data

<details>
| **Parameter**    | **Type** | **Note**                     |
| ---------------- | -------- | ---------------------------- |
| ocr              | string   | MATCH / NOT_MATCH                             |
| issueNumber      | string   | MATCH / NOT_MATCH            |
| registrationYear | string   | MATCH / NOT_MATCH            |
| issueYear        | string   | MATCH / NOT_MATCH            |
| electorKey       | string   | MATCH / NOT_MATCH            |
| message          | string   | Human-readable validation result message. |
</details>

---

# Mexican CURP Validation (Renapo)

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/mexicanCheckRenapo

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Mexican CURP Validation (Renapo)

Jumio has a number of database check services available for Mexico. These checks allow you to validate Mexican National IDs and personal identifiable information.
This service connects with the Mexican National Population Registry (Registro Nacional de Población / RENAPO) to validate that the Unique Population Registry Code (Clave Única de Registro de Población / CURP) number present on the ID card exists and its owner matches the data.

:::note
The CURP ID must contain exactly **18 characters**.
:::

![image](../img/Mexican_Curp_Validation_Check.png)

| **Service Name**       | **Description**                                                                                                                                                            | **Required Fields**                                                                                                      | **Verifiable Fields**                                                                                                                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mexico CURP Validation | Input is verified against the RENAPO (Registro Nacional de Población e Identificación Personal). This stands for the National Census and Personal Identification Registry. | <ul><li>First Name</li><li>Paternal Name</li><li>Maternal Name</li><li>Address (country)</li><li>ID (IDNumber)</li></ul> | <ul><li>CURP ID#</li><li>First Name</li><li>Paternal Name</li><li>Maternal Name</li><li>Date of Birth (DOB)</li><li>Gender</li><li>Address (country)</li></ul> |

## CURP Validation

### Required Credentials

<details> 
<summary>Prepared Data</summary>
| **Key**                 | **Type**     | **Mandatory** | **Description**                                                                                  |
|-------------------------|--------------|---------------|--------------------------------------------------------------------------------------------------|
| `firstName`            | string       | yes           | First name of the subject. Optimal to include.                                                                                        |
| `paternalSurname`      | string       | yes           | Paternal Surname of the subject.                                                                                |
| `maternalSurname`      | string       | yes           | Maternal Surname of the subject.                                                                              |
| `sex`                  | string       | yes           | Gender (`M` - Male, `F` - Female)                                                              |
| `email`                | string       | no            | Email Address                                                                                   |
| `phoneNumber`          | string       | no            | Phone Number                                                                                   |
| `ipAddress`            | string       | no            | IP Address                                                                                     |
| `socialSecurityNumber` | string       | no            | Either `socialSecurityNumber`, `personNumber`, or `idNumber` should be provided                |
| `dateOfBirth`          | LocalDate    | yes           | Date of Birth in `YYYY-MM-DD` format only                                                      |
| `address`              | Object       | yes           | Only the fields mentioned below are required                                                   |
| `address.country`      | string       | yes           | Country should be `MEX` (ISO Alpha-3 Code for Mexico)                                          |
| `address.subdivision` | string        | no            | Added in **request without CURP**. City subdivision of residence as it appears on the ID.                |
| `address.state` | string        | no            | State name can be provided here. <br />See Supported States **[here](./mexicanCheckRenapo#supported-states)**.                |
| `id`                   | Object       | yes           | See details below                                                                               |
| `id.idNumber`          | string       | yes           | CURP ID (Example: `XXXXXXXXXXXXXXXXXX`)                                                             |
| `id.type`              | string       | conditional   | `ID_CARD`                                                                                      |
| `id.subType`           | string       | conditional   | Subtype of ID                                                                                  |
| `id.issuingDate`       | string       | conditional   | Date the ID was issued                                                                         |
| `id.expiryDate`        | string       | conditional   | Expiry date of the ID                                                                          |

</details>

:::info

- If CURP (nationalID) is present, we validate the CURP and surface match/no match for address (state), gender, name (first name), Date of Birth (DOB), and nationalID, if provided.
- If CURP/nationalID is not present, we validate KYC namely name (full name, paternal surname, maternal surname, gender, DOB, and address (state). All fields are mandatory except maternal surname.
- 10054 may not work, since extraction does not extract paternal and maternal surnames. It is extracted as full name and we are unable to bifurcate).
  :::

#### Supported States

<details>
<summary>Expand the list to view the **Supported States** </summary>
- AGUASCALIENTES
- BAJA CALIFORNIA
- BAJA CALIFORNIA SUR
- BORN ABROAD
- CAMPECHE
- CHIAPAS
- CHIHUAHUA
- COAHUILA
- COLIMA
- DISTRITO FEDERAL
- DURANGO
- GUANAJUATO
- GUERRERO
- HIDALGO
- JALISCO
- MÉXICO
- MICHOACÁN
- MORELOS
- NAYARIT
- NACIDO EN EL EXTRANJERO
- NUEVO LEÓN
- OAXACA
- PUEBLA
- QUERÉTARO
- QUINTANA ROO
- SAN LUIS POTOSI
- SINALOA
- SONORA
- TABASCO
- TAMAULIPAS
- TLAXCALA
- VERACRUZ
- YUCATÁN
- ZACATECAS

</details>

### Response Values

<details>
| **Parameter**             | **Type**          | **Note**                                                                                                                                                   |
| ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                        | string            | UUID of the capability                                                                                                                                     |
| credentials               | array(Credential) |                                                                                                                                                            |
| decision                  | object            |                                                                                                                                                            |
| decision.type             | string            | Possible values: `NOT_EXECUTED`, `PASSED`, `REJECTED`, `WARNING`                                                                                           |
| decision.details          | object            |                                                                                                                                                            |
| decision.details.label    | string            | Possible values: `OK`, `DENY`, `ALERT`, `NOT_ENOUGH_DATA`, `TECHNICAL_ERROR`, `PERMISSION_DENIED`, `BAD_REQUEST`, `PRECONDITION_NOT_FULFILLED`             |
| data                      | object            |                                                                                                                                                            |
| data.nationalidMatch      | string            | Possible values: `Match`, `NoMatch`                                                                                                                        |
| data.reasonMessage        | string            | Possible values: `Verification Successful`, `WITHOUT RENAPO RESPONSE`, `DOES NOT RESPOND`, `INCORRECT DATA`, `REFERENCE ALREADY EXIST`, `UNEXPECTED ERROR` |
| data.firstNameMatch       | string            | `Match`, `NoMatch`                                                                                                                                         |
| data.dobMatch             | string            | `Match`, `NoMatch`                                                                                                                                         |
| data.sexMatch             | string            | `Match`, `NoMatch`                                                                                                                                         |
| data.paternalSurnameMatch | string            | `Match`, `NoMatch`                                                                                                                                         |
| data.maternalSurnameMatch | string            | `Match`, `NoMatch`                                                                                                                                         |
| data.stateKeyMatch        | string            | `Match`, `NoMatch`                                                                                                                                         |

</details>

### Credential

| **Key**  | **Type** | **Description**             |
| -------- | -------- | --------------------------- |
| id       | string   | UUID of credential used     |
| category | string   | Category of credential used |

### Capability Request (with/without CURP)

<Tabs>
  <TabItem value="with-curp" label="Request with CURP">

```json
{
  "firstName": "Jorge",
  "paternalSurname": "Garcia",
  "maternalSurname": "Perez",
  "sex": "H",
  "dateOfBirth": "1991-01-01",
  "address": {
    "country": "MEX"
  },
  "id": {
    "idNumber": "ID1234567890XXXXXX",
    "type": "ID_CARD"
  }
}
```

</TabItem>

<TabItem value="without-curp" label="Request without CURP">
````json
{
  "firstName": "Jorge",
  "paternalSurname": "Garcia",
  "maternalSurname": "Perez",
  "sex": "H",
  "dateOfBirth": "1991-01-01",
  "address": {
    "country": "MEX",
    "subdivision": "CMX"
  },
  "id": {
    "idNumber": "ID1234567890",
    "type": "ID_CARD"
  }
}
````
</TabItem> 
</Tabs>

### Capability Response (CURP ID)

```
{
  "govtIdVerification": [
    {
      "id": "439e2649-d1f4-4418-a9e7-14cba6522124",
      "credentials": [
        {
          "id": "45591915-55b2-42fc-a615-8f170c5558b4",
          "category": "DATA"
        }
      ],
      "decision": {
        "type": "PASSED",
        "details": {
          "label": "OK"
        }
      },
      "data": {
        "firstNameMatch": "NOT_MATCH",
        "nationalIdMatch": "MATCH",
        "sexMatch": "MATCH",
        "stateKeyMatch": "NOT_MATCH",
        "reasonMessage": "Verification Successful"
      }
    }
  ]
}

```

### Capability Response (No CURP ID)

```
{
  "govtIdVerification": [
    {
      "id": "bd84dbf7-35dc-4136-bc54-8faea1f09116",
      "credentials": [
        {
          "id": "b8d793ab-8f65-47c1-8025-9f00a477b5fb",
          "category": "DATA"
        }
      ],
      "decision": {
        "type": "PASSED",
        "details": {
          "label": "OK"
        }
      },
      "data": {
        "firstNameMatch": "MATCH",
        "dobMatch": "MATCH",
        "sexMatch": "MATCH",
        "paternalSurnameMatch": "MATCH",
        "maternalSurnameMatch": "MATCH",
        "stateKeyMatch": "MATCH",
        "reasonMessage": "Verification Successful"
      }
    }
  ]
}

```

---

# Mexican RFC Database Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/mexicanRFCDatabaseCheck

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Mexican RFC Database Check

In Mexico, the RFC is a unique tax identification number assigned to individuals and companies. It is issued by the tax authority and is commonly used for financial and legal purposes.

Jumio’s RFC Data Check verifies the provided RFC by querying the Servicio de Administración Tributaria (SAT), the official government authority responsible for issuing and maintaining RFC records. Also, this checks the data against official records. The verification confirms:

- Whether the RFC is valid
- Whether it belongs to the provided individual or company
  This check is based on user-provided data, as RFC is not available on standard identity documents.

## Use Case

This check is useful for verifying tax identification data in Mexico. It can be used:

- As a standalone check
- Alongside other Mexico-specific checks to improve overall verification accuracy

## How Does it Work?

- **Data Collection** - The RFC is provided by the user or passed by the customer system.
- **Data Submission** - The RFC is sent to Jumio for validation.
- **Verification** with Servicio de Administración Tributaria (SAT) through our partner, Jumio, sends the request to FIMPE, which validates the RFC against official records. Based on the response, a match or no-match result is returned.

## Supported Credentials

The following values can be uploaded as [prepared data](https://documentation.jumio.ai/docs/references/credentials/#data).

| **Key**         | **Type** | **Mandatory** | **Description**       |
| --------------- | -------- | ------------- | --------------------- |
| address.country | string   | yes           | Country should be MEX |
| id.idNumber     | string   | yes           | RFC ID number         |
| id.type         | string   | yes           | Type of national ID   |

:::note
1. The RFC ID should contain exactly **13 characters**.
2. This is a standalone check.
3. RFC must be provided by the customer.
:::

## Example Request

```
{
  "address": {
    "country": "MEX"
  },
  "id": {
    "idNumber": "AAZA**0**2****",
    "type": "ID_CARD"
  }
}

```

## Response

Response data is available for transactions that include the risk signal. For information on transaction data, see [Viewing or Retrieving Workflow Transactions](https://documentation.jumio.ai/docs/developer-resources/retrieval).

**Example Success Response**

<Tabs>
  <TabItem value="Person(FISICA)" label="Person(FISICA)">

```
{
"govtIdVerification": [
  {
    "id": "12345-abcde-67890",
    "credentials": [
      {
        "id": "cred-12345",
        "category": "DATA"
      }
    ],
    "decision": {
      "type": "PASSED",
      "details": {
        "label": "OK"
      }
    },
    "data": {
      "nationalIdMatch": "MATCH",
      "reasonMessage": "Valid RFC, eligible to receive invoices",
      "entityType": "PERSON (Fisica)"
    }
  }
]
}
```

  </TabItem>

<TabItem value="Business RFC" label="Business RFC">

```
{
  "govtIdVerification": [
    {
      "id": "e6014cab-b499-408f-87ca-61337f6e53a0",
      "credentials": [
        {
          "id": "3c9a3fec-5214-4cce-b4a7-289cba8b5cc3",
          "category": "DATA"
        }
      ],
      "decision": {
        "type": "PASSED",
        "details": {
          "label": "OK"
        }
      },
      "data": {
        "nationalIdMatch": "MATCH",
        "reasonMessage": "Valid RFC, eligible to receive invoices",
        "entityType": "COMPANY (Moral)"
      }
    }
  ]
}
```

  </TabItem>

  </Tabs>

**Example Rejection Response**

```
{
  "capabilities": {
    "govtIdVerification": [
      {
        "id": "84aea756-4935-4187-b270-3d4b8d76345b",
        "credentials": [
          {
            "id": "47ba6e43-fbdc-4e50-8f26-3158e0ebc734",
            "category": "DATA"
          }
        ],
        "decision": {
          "type": "REJECTED",
          "details": {
            "label": "DENY"
          }
        },
        "data": {
          "nationalIdMatch": "NOT_MATCH",
          "reasonMessage": "RFC is not in the list of non-cancelled RFCs"
        }
        .....
      }
      ......
    ]
  }
}
```

## Credentials

| **Key**  | **Type** | **Description**              |
| -------- | -------- | ---------------------------- |
| id       | string   | UUID of the credential used  |
| category | string   | Category of credentials used |

## Decision Details Labels

| **Decision Type** | **Label**       | **Description**                  |
| ----------------- | --------------- | -------------------------------- |
| PASSED            | OK              | RFC is valid and matches records |
| REJECTED          | DENY            | RFC is invalid or does not match |
| NOT_EXECUTED      | TECHNICAL_ERROR | The check could not be completed |

## Data

| **Key**         | **Type** | **Description**                                                                                                         |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| entityType      | string   | Type of RFC: Individual (Persona Fisica) or Company (Persona Moral)                                                     |
| nationalIdMatch | string   | "MATCH", "NOT_MATCH": Indicates the match status of the ID. National ID may not always be supported in all countries    |
| reasonMessage   | string   | Detailed message for success or failure cases. See the table below for examples (e.g., valid RFC, invalid format, etc.) |

### Data - reasonMessage

| **Decision** | **Message**                                 | **Description**                            |
| ------------ | ------------------------------------------- | ------------------------------------------ |
| PASSED       | Valid RFC, eligible to receive invoices     | RFC is valid and can be used for invoicing |
| REJECTED     | RFC not registered in the taxpayer registry | RFC does not exist in the official records |
| REJECTED     | RFC is not in the list of non-canceled RFCs | RFC is canceled or inactive                |
| REJECTED     | RFC with invalid format                     | RFC format is incorrect                    |
| NOT_EXECUTED | Authentication error                        | Failed due to authentication issues        |
| NOT_EXECUTED | Encryption error                            | Encryption-related failure                 |
| NOT_EXECUTED | Insufficient permissions                    | Access rights are not sufficient           |
| NOT_EXECUTED | Incorrect data                              | Provided data is incorrect                 |
| NOT_EXECUTED | Incorrect data format                       | Data format does not meet requirements     |
| NOT_EXECUTED | Reference already registered                | Duplicate reference detected               |
| NOT_EXECUTED | Database execution error                    | Internal database processing failure       |
| NOT_EXECUTED | Service unavailable                         | External service is not reachable          |
| NOT_EXECUTED | SAT unavailable                             | SAT system is unavailable                  |

---

# Peru RENIEC Data Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/peruRENEIC

# Peru RENIEC Data Check

Jumio offers a data verification service through Peru’s National Registry of Identification and Civil Status (Registro Nacional de Identificación y Estado Civil - RENIEC). This service enables real-time validation of the DNI (Documento Nacional de Identidad) and personally identifiable information (PII) against official government records.

## Overview

In Peru, the DNI is a unique identification number assigned to each citizen and resident. It appears on the national identity card and serves as the primary identifier in both government and private sector records.
Jumio’s RENIEC Data Check verifies the submitted identity data by querying RENIEC — the official government agency responsible for civil registration and identity management. The check confirms whether the provided information (e.g., DNI number, name) matches an existing record in the RENIEC database.
This check can be initiated using either data extracted from an identity document or information entered manually by the user.

### Use Case

This signal is beneficial in identity verification workflows that require strong assurance that a user’s identity data matches official records. It can be used as a standalone check or with other Jumio services to increase verification accuracy.

### How Does it Work?

1. Data Collection: Identity information is captured either from a scanned DNI (Documento Nacional de Identidad) or manually entered by the user during onboarding.
2. Data Submission: The captured information — including the DNI number and full name— is securely sent to Jumio.
3. Verification with RENIEC: Jumio queries RENIEC to verify if the submitted identity data matches an official government record.
   The response from RENIEC confirms whether the data is valid and corresponds to an existing record. Based on this result, a success or failure signal is returned.

### Supported Credentials

The following values can be uploaded as Prepared Data. Alternatively, they can be extracted by an upstream capability in a workflow.

| **Key**           | **Type**  | **Mandatory** | **Description**                                 |
| ----------------- | --------- | ------------- | ----------------------------------------------- |
| `id.idNumber`     | string    | yes           | The Identification Number from the Peru DNI ID. |
| `id.type`         | string    | no            | Type of ID. Expected value: `ID_CARD`.          |
| `firstName`       | string    | yes           | First name.                                     |
| `lastName`        | string    | yes           | Last name.                                      |
| `dateOfBirth`     | LocalDate | yes           | Date of birth in YYYY-MM-DD format only.        |
| `address.country` | string    | yes           | Country should be `PER`.                        |

### Example Prepared Data Body

```
{
    "firstName": "CESAR JOSE MARTIN",
    "paternalSurname": "LEMA",
    "maternalSurname": "SONCCO",
    "dateOfBirth": "1985-05-13",
    "address": {
        "country": "PER"
    },
    "id": {
        "idNumber": "43028793",
        "type": "ID_CARD"
    }
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data, see Viewing or Retrieving Workflow Transactions.

**Example Response Body**

```
"govtIdVerification": [
            {
                "id": "79e0fa63-0ff5-4bab-99b2-bb9c49637ba2",
                "credentials": [
                    {
                        "id": "1ceaf3c0-2689-43ea-93aa-187c2ba5da51",
                        "category": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "country": "PER",
                    "type": "ID_CARD",
                    "completeNameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "reasonMessage": "DATA_MATCH",
                    "paternalSurnameMatch": "MATCH",
                    "maternalSurnameMatch": "MATCH
			  },
}
]
```

### Credentials

| **Key**    | **Type** | **Description**               |
| ---------- | -------- | ----------------------------- |
| `id`       | string   | UUID of the credential used.  |
| `category` | string   | Category of credentials used. |

### Decision Details Labels

| **Decision Type** | **Label**         | **Description**                                                                                                                |
| ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `PASSED`          | `OK`              | The provided data matched.                                                                                                     |
| `REJECTED`        | `DENY`            | The provided data did not match what was on record. See [data](./peruRENEIC#data) for more info.                               |
| `NOT_EXECUTED`    | `TECHNICAL_ERROR` | The verification could not be completed due to a technical error (e.g., service downtime, timeout, or invalid request format). |

### Data

| **Key**                | **Possible Values**           | **Description**                                                      |
| ---------------------- | ----------------------------- | -------------------------------------------------------------------- |
| `firstNameMatch`       | `MATCH`, `NOT_MATCH`          | Indicates if the first name matches the PERU record.                 |
| `lastNameMatch`        | `MATCH`, `NOT_MATCH`          | Indicates if the last name matches the PERU record.                  |
| `completeNameMatch`    | `MATCH`, `NOT_MATCH`          | Indicates if the combined first and last name match the PERU record. |
| `nationalIdMatch`      | `MATCH`, `NOT_MATCH`          | Indicates if the `idNumber` matches the PERU record.                 |
| `dobMatch`             | `MATCH`, `NOT_MATCH`          | Indicates if the date of birth matches the PERU record.              |
| `reasonMessage`        | `DATA_MATCH`, `DATA_NO_MATCH` | Indicates whether the reason data matches the official source.       |
| `paternalSurnameMatch` | `MATCH`, `NOT_MATCH`          | Indicates if the paternal surname matches the PERU record.           |
| `maternalSurnameMatch` | `MATCH`, `NOT_MATCH`          | Indicates if the maternal surname matches the PERU record.           |

---

# Australian Document Verification Service (DVS) Check

https://documentation.jumio.ai/docs/references/riskSignals/govDatabaseCheck/AustralianDBCheck

# Australian Document Verification Service (DVS) Check

The Australian Document Verification Service (DVS) check validates identity data against official government records in real time. This capability ensures that customer credentials (such as Passports, Driver licences) are authentic and belong to a living person.

:::note
**Access to the Australian DVS service requires customer onboarding.** Customers who wish to use this service must first complete the required onboarding process with our vendor. To begin onboarding and receive the necessary forms and guidance, please contact your Account Manager.
:::

Customers can either upload this data directly as Prepared Data or have it automatically extracted by an upstream capability (such as OCR/document scan) within the workflow.

- Workflow key for Prepared Data is **10020**
- Workflow key for Extraction with ID Verification is **10054**

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../../references/credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

- Driver licence (DRIVING_LICENCE)
- Passport (PASSPORT)

## Request

### Example Prepared Data Body (Passport Example)

When triggering an Australian DVS check with a Passport, use the **country code AUS** and set the **document type to PASSPORT**.

```
{
  "firstName": "May Lee",
  "address": {
    "country": "AUS"
  },
  "dateOfBirth": "1985-02-08",
  "id": {
    "idNumber": "949XXX000",
    "type": "PASSPORT"
  }
}

```

### Example Prepared Data Body (DRIVING_LICENCE Example)

When verifying an Australian Driver licence, you must include both the licence number (idNumber) and the card number or state-specific identifier (secondaryIdNumber) inside the id block.

Here the document type should be **DRIVING_LICENCE**.

```
{
    "firstName": "JOHN CITIZEN",
    "lastName": "SMITH",
    "dateOfBirth": "1990-01-15",
    "address": {
        "line1": "123 George St",
        "postalCode": "2000",
        "city": "Sydney",
        "subdivision": "NSW",
        "country": "AUS"
    },
    "id": {
        "idNumber": "2XXXXX71",
        "secondaryIdNumber": "20XXXXX138",
        "type": "DRIVING_LICENCE"
    }
}
```

#### Data

| Field                 |                                                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **idNumber**          | The primary Driver licence number.                                                                                                                                                                      |
| **secondaryIdNumber** | The Card Number found on the physical driver's licence (varies by Australian state or territory). This value is required by the Australian DVS registry to help prevent fraud.                          |
| **subdivision**       | The abbreviation of the issuing Australian state or territory (for example, `NSW`, `VIC`, `QLD`, `WA`, `SA`, `TAS`, `ACT`, or `NT`). This must match the jurisdiction that issued the driver's licence. |

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

**Example Response**

```
"govtIdVerification": [
    {
                "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
                "credentials": [
                    {
                        "id": "z9y8x7w6-v5u4-3t2s-1r0q-p9o8n7m6l5k4",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "LOW_RISK"
                    }
                },
                "data": {
                    "country": "AUS",
                    "type": "DRIVER_LICENCE",
                    "completeNameMatch": "MATCH",
                    "initialNameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "dobDayMatch": "MATCH",
                    "dobMonthMatch": "MATCH",
                    "dobYearMatch": "MATCH",
                    "dobMatch": "MATCH",
                    "addressMatch": "MATCH",
                    "score": 10
                }
            }
        ]
```

#### Decision Details Labels

| Decision Type    | Label                          | Description                                                                                                                                                 |
| ---------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PASSED**       | **LOW_RISK**                   | No significant risk associated with the provided data. The identity details successfully match the Australian DVS registry.                                 |
| **REJECTED**     | **HIGH_RISK**                  | High risk associated with the provided data. The identity details are mismatched or potentially invalid.                                                    |
| **WARNING**      | **MEDIUM_RISK**                | Moderate risk associated with the provided data. A partial match or minor discrepancies were found.                                                         |
| **NOT_EXECUTED** | **PERMISSION_DENIED**          | The verification could not be performed because the required permissions or credentials are missing. Verify your API key and Australian DVS access rights.  |
| **NOT_EXECUTED** | **BAD_REQUEST**                | The verification could not be performed because the request is malformed or required parameters are missing (for example, mandatory card numbers or names). |
| **NOT_EXECUTED** | **PRECONDITION_NOT_FULFILLED** | The verification could not be performed because one or more preconditions were not met.                                                                     |
| **NOT_EXECUTED** | **TECHNICAL_ERROR**            | The verification could not be performed due to an unexpected server-side error or an issue communicating with the external DVS registry.                    |

#### Data

| Parameter             | Type      | Possible Values              | Description                                                                     |
| --------------------- | --------- | ---------------------------- | ------------------------------------------------------------------------------- |
| **country**           | `string`  | `AUS`                        | Country where the Government Check is performed.                                |
| **type**              | `string`  | `DRIVER_LICENCE`, `PASSPORT` | Type of identity document used for the verification.                            |
| **completeNameMatch** | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the complete name matches the government record.              |
| **initialNameMatch**  | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the initials match the government record.                     |
| **firstNameMatch**    | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the first name matches the government record.                 |
| **lastNameMatch**     | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the last name matches the government record.                  |
| **nationalIdMatch**   | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the document or licence number matches the government record. |
| **dobDayMatch**       | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the day of birth matches the government record.               |
| **dobMonthMatch**     | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the month of birth matches the government record.             |
| **dobYearMatch**      | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the year of birth matches the government record.              |
| **dobMatch**          | `string`  | `MATCH`, `NOT_MATCH`         | Overall result of the date of birth comparison.                                 |
| **addressMatch**      | `string`  | `MATCH`, `NOT_MATCH`         | Indicates whether the address matches the government record.                    |
| **score**             | `integer` | `10`, `20`, `30`             | Summary verification score (`10` = Pass, `20` = Warning, `30` = Reject).        |

---

# Phone Verification

https://documentation.jumio.ai/docs/references/riskSignals/phoneVerification

# Phone Verification

Phone Verification enables our customers to assess the risk of a provided phone number. Phone verification is a fundamental risk check that analyzes a phone number to provide an overall risk. This adds phone intelligence as a layer of defense to fraud prevention.

Phone verification provides the overall risk and reputation of a phone number by looking at the risk and usage of patterns of the phone number along with metadata around the type of phone.

## Use Case

For those with onboarding and account login workflows who wish to understand and assess the risk of a given phone number.

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../references/credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

To use Prepared Data with phone verification as a standalone capability use workflow key 10065.
| **Key** | **Type** | **Mandatory** | **Description** |
|----------------|----------|---------------|------------------------------------------------------------------|
| phoneNumber | String | yes | Phone number of the subject in [E.164 format](https://en.wikipedia.org/wiki/E.164). **Must include country code.** |

## Example Prepared Data Body

```
{
 "phoneNumber": "+65644***8"
}
```

## Response

```
capabilities ": {
  "phoneVerification": [{
    "id": "94d8b738-07c2-45b8-8b7d-5e5f5dc89947",
    "credentials": [{
      "id": "48655c2f-5e5f-46e0-bb42-22c980c630fd",
      "category": "DATA"
    }],
    "decision": {
      "type": "PASSED",
      "details": {
        "label": "LOW_RISK"
      }
    },
    "data": {
      "phoneType": "MOBILE",
      "carrier": "Vi",
      "blocked": false,
      "riskInsights": {
        "relativeRisk": [
            "LOW ACTIVITY"
        ],
        "applicationToPersonTraffic": [
          "SEEN IN THE LAST 1 DAY",
          "LOW LONG-TERM ACTIVITY",
          "NO RANGE ACTIVITY"
        ],
        "personToPersonTraffic": [
          "NO P2P DATA ANALYZED"
        ]
      }
    }
  ]
```

### Decision Details Labels

<details>
| **Decision Type**   | **Label**            | **Description**                                    |
|---------------------|----------------------|----------------------------------------------------|
| PASSED              | LOW_RISK             |  The provided data matched.                                                                                            |
| REJECTED            | HIGH_RISK            | The provided data did not match what was on record. See [Data](./phoneVerification#data) for additional information.                                                    |
| WARNING             | MEDIUM_RISK          |  If one of the names or DOB does not match, it is medium risk. |
| NOT_EXECUTED        | PERMISSION_DENIED    |  Cannot be executed because the required permissions or credentials are missing. Verify your API key and access rights.                                                     |
| NOT_EXECUTED      | BAD_REQUEST                |  Malformed or missing required parameters. Ensure that all mandatory fields are included and correctly formatted before retrying.               |
| NOT_EXECUTED      | PRECONDITION_NOT_FULFILLED | Preconditions were not met to process the data.                |
| NOT_EXECUTED      | TECHNICAL_ERROR            | Verify the provided data is correct and retry, or contact [Support](https://support.jumio.com/s/).             |
</details>

### Data

<details>
| **Parameter**                       | **Type**          | **Note**                                                        |
|-------------------------------------|-------------------|-----------------------------------------------------------------|
| phoneType                           | string            | Possible values: `FIXED_LINE`, `INVALID`, `MOBILE`, `OTHER`, `PAGER`, `PAYPHONE`, `PERSONAL`, `PREPAID`, `TOLLFREE`, `VOIP` |
| carrier                             | string            | Phone Carrier Name                                             |
| blocked                             | boolean           | `True` / `False`                                                |
| riskInsights.relativeRisk           | string array      | The risk category. This is determined based on weighting the risk and trust signals indicated by the other risk insights. See Relative Risk Values. |
| riskInsights.applicationToPersonTraffic | string array      | Reasons specific to application-to-person messaging (a2p). These are automated messages sent to a human, such as verification codes, appointment reminders, etc. See Application to Person Values. |
| riskInsights.personToPersonTraffic  | string array      | Not used at this time. The value will always be `NO P2P DATA ANALYZED` |

</details>

#### Relative Risk Values

<details>

| **Value**                        | **Description**                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------- |
| `low activity`                   | Not enough activity or attributes to classify the transaction as either risky or trustworthy. |
| `low regular activity`           | Trustworthy category, based on past behavior.                                                 |
| `regular activity`               | Most trustworthy category, based on past behavior.                                            |
| `low-risk irregular activity`    | Risky category, based on past behavior.                                                       |
| `medium-risk irregular activity` | High-risk category, based on past behavior.                                                   |
| `high-risk irregular activity`   | Highest-risk category, based on past behavior.                                                |
| `irregular number type`          | This number has risky static attributes (like VOIP phone type or being on a blocklist).       |

</details>

#### Application to Person Values

<details>
| **Category**      | **Value**                            | **Description**                                                                              |
|-------------------|--------------------------------------|----------------------------------------------------------------------------------------------|
| Activity          | `no long-term activity`              | Much less than expected activity, or none at all, for this number over the past 90 days.      |
| Activity          | `high long-term activity`            | More than expected activity for this number over the past 90 days.                            |
| Activity          | `high short-term activity`           | More than expected activity for this number over the last 24 hours.                           |
| Activity          | `moderate long-term activity`        | Expected activity for this number over the past 90 days.                                     |
| Activity          | `moderate short-term activity`       | Expected activity for this number over the last 24 hours.                                    |
| Activity          | `sparse long-term activity`          | Sparse, regular volume of verification traffic on this number over the past 90 days.         |
| Activity          | `continuous long-term activity`      | Continuous, regular volume of verification traffic on this number over the past 90 days.     |
| Activity          | `very high long-term activity`       | Very high volume of verification traffic on this number over the past 90 days.               |
| Activity          | `no activity`                        | Very low volume of verification traffic, or none at all, was ever observed on this number.   |
| Activity          | `low long-term activity`             | Low volume of verification traffic on this phone number over the past 90 days.               |
| Activity          | `low short-term activity`            | Low volume of verification traffic on this phone number over the past 24 hours.              |
| Activity          | `low activity`                       | Less than expected activity for this number.                                                 |
| Range              | `no range activity`                  | Very little activity, or none at all, for a risky range that this number belongs to.         |
| Range              | `low range activity`                 | Some activity for a risky range that this number belongs to.                                 |
| Range              | `moderate short-term range activity` | Significant activity for a risky range that this number belongs to over the last 24 hours.   |
| Range              | `moderate long-term range activity`  | Significant activity for a risky range that this number belongs to over the past 90 days.    |
| Range              | `high short-term range activity`     | Very significant activity for a risky range that this number belongs to over the last 24 hours. |
| Range              | `high long-term range activity`      | Very significant activity for a risky range that this number belongs to over the past 90 days. |
| Range              | `very high long-term range activity` | Extremely significant activity for a risky range that this number belongs to over the past 90 days. |
| Range              | `very high short-term range activity`| Extremely significant activity for a risky range that this number belongs to over the last 24 hours. |
| Risky Services    | `moderate activity on risky services`| Significant activity on this number to or from risky services over the past 90 days.         |
| Risky Services    | `high activity on risky services`    | Very significant activity on this number to or from risky services over the past 90 days.    |
| Risky Services    | `long-term activity on risky services`| Verification traffic on risky services on this number over the past 90 days.                 |
| Risky Services    | `short-term activity on risky services`| Verification traffic on risky services on this number over the past 24 hours.                |
| Risky Services    | `high long-term activity on risky services`| High volume of verification traffic on risky services on this number over the past 90 days.   |
| Risky Services    | `high short-term activity on risky services`| High volume of verification traffic on risky services on this number over the past 24 hours.  |
| Risky Services    | `long-term range activity on risky services`| Verification traffic on risky services on the range this number belongs to over the past 90 days. |
| Risky Services    | `short-term range activity on risky services`| Verification traffic on risky services on the range this number belongs to over the past 24 hours. |
| Risky Services    | `high long-term range activity on risky services`| High volume of verification traffic on risky services on the range this number belongs to over the past 90 days. |
| Risky Services    | `high short-term range activity on risky services`| High volume of verification traffic on risky services on the range this number belongs to over the past 24 hours. |
| Risky Services    | `very high short-term activity on risky services`| Very high volume of verification traffic on risky services on this number over the past 90 days. |
| Risky Services    | `very high long-term activity on risky services`| Very high volume of verification traffic on risky services on this number over the past 24 hours. |
| Risky Services    | `very high short-term range activity on risky services`| Very high volume of verification traffic on risky services on the range this number belongs to over the past 90 days. |
| Risky Services    | `very high long-term range activity on risky services`| Very high volume of verification traffic on risky services on the range this number belongs to over the past 24 hours. |
| Other              | `machine-like activity`               | Behavior pattern that suggests this number is being used by a bot.                             |
| Other              | `machine-like range activity`         | Extremely high volume of verification traffic in a very short period (less than 1 hour) on the range this number belongs to. |
| Recency            | `seen in the last 1 day`               | This number was seen in verification traffic in the last 1 day.                               |
| Recency            | `seen in the last 7 days`              | This number was seen in verification traffic in the last 7 days.                              |
| Recency            | `seen in the last 15 days`             | This number was seen in verification traffic in the last 15 days.                             |
| Recency            | `seen in the last 1 month`             | This number was seen in verification traffic in the last 1 month.                             |
| Recency            | `seen in the last 2 months`            | This number was seen in verification traffic in the last 2 months.                            |
| Recency            | `seen in the last 3 months`            | This number was seen in verification traffic in the last 3 months.                            |
| Recency            | `seen more than 3 months ago`          | This number was not seen in verification traffic in the last 3 months.                       |

</details>

---

# SSN Verification

https://documentation.jumio.ai/docs/references/riskSignals/ssnVerification

# SSN Verification

The Jumio eKYC SSN (Social Security Number) verification service allows a customer to submit personal identifiable information from applicants within the United States. The SSN verification service confirms that a name, address, and Social Security Number are valid and connected to the end user.

This service connects to US data sources such as credit bureaus, SSA, utilities, telecom, USPS, bell companies, and other proprietary sources.

![image](./img/SSN_Verification.png)

| **Service Name** | **Description**                                                                                                                                     | **Required Fields**                                  | **Verifiable Fields**                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| SSN Verification | Input is verified against the US data sources such as credit bureaus, SSA, utilities, telecom, USPS, bell companies, and other proprietary sources. | Name, Address and SSN; Optional: Date of Birth (DOB) | `Name`, `Address`, `SSN`, `DOB`, `Phone`, `Deceased Indicator` |

## Supported Credentials

The following values can be uploaded as Prepared Data. Alternatively, they can be extracted by an upstream capability in a workflow.

<details>
| **Key**                   | **Type**       | **Mandatory** | **Description**                                      |
|---------------------------|----------------|---------------|------------------------------------------------------|
| firstName                 | string         | yes           | First name of the subject                            |
| lastName                  | string         | yes           | Last name of the subject                             |
| middleName                | string         | no            | Middle name of the subject                           |
| paternalSurname           | string         | no            | Paternal surname of the subject                      |
| maternalSurname           | string         | no            | Maternal surname of the subject                      |
| sex                       | string         | no            | Sex of the subject (e.g., M - Male, F - Female)       |
| email                     | string         | no            | Email address of the subject                         |
| phoneNumber               | string         | no            | Phone number of the subject in E.164 format          |
| ipAddress                 | string         | no            | IP address of the subject                            |
| socialSecurityNumber      | string         | yes           | Social Security Number (4 or 9 digits)               |
| dateOfBirth               | LocalDate      | no            | Date of birth in YYYY-MM-DD format                   |
| address                   | Object         | yes           | Only the fields mentioned below are required         |
| address.line1             | string         | yes           | Address line 1                                       |
| address.line2             | string         | yes           | Address line 2                                       |
| address.city              | string         | yes           | City of the subject                                  |
| address.postalCode        | string         | yes           | Postal code (Zip code)                               |
| address.subdivision       | string         | yes           | Subdivision (State)                                  |
| address.country           | string         | yes           | Country in ISO Alpha 3 Code format                   |

</details>

### Example Prepared Data Body

```
{
    "firstName": "xxxxx",
    "lastName": "xxxx",
    "middleName": "",
    "sex": "M",
    "nationality": "",
    "phoneNumber2": "",
    "phoneNumber": "+555****333",
    "ipAddress": "54.190.251.42",
    "socialSecurityNumber": "123*****",
    "dateOfBirth": "1970-01-31",
    "address": {
      "line1": "123 main street",
      "postalCode": "9***6"
        }
  }
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see Viewing or Retrieving Workflow Transactions.

Example Response

```
ekycSsnVerification": [
     {
         "id": "4da5f259-aaed-4fd9-8283-6a02d5a18476",
         "credentials": [
             {
                 "id": "a94b913f-3fde-4f98-898f-88a0cbaef8b8",
                 "category": "DATA"
             }
         ],
         "decision": {
             "type": "WARNING",
             "details": {
                 "label": "MEDIUM_RISK"
             }
         },
         "data": {
             "addressMatch": "match",
             "nameMatchToSsn": "match",
             "nameMatchToAddress": "partial-match",
             "phoneMatch": "no-match",
             "ssnMatch": "match",
             "dateOfBirthMatch": "no-match",
             "isDeceased": false,
             "isSSNIssuedPriorYOB": false
         }
}
```

#### Decision Details Labels

<details>
| **Decision Type**           | **Label**     | **Description**                                             |
|-----------------------------|---------------|-------------------------------------------------------------|
| NOT_EXECUTED                | PRECONDITION_NOT_FULFILLED | Provided data is incorrectly formatted.                    |
| NOT_EXECUTED                | NOT_ENOUGH_DATA | Required data is not available.                            |
| NOT_EXECUTED                | TECHNICAL_ERROR | The service encountered an error and was unable to process the request. |
| PASSED                      | LOW_RISK      | Provided data matches available records.                   |
| WARNING                     | MEDIUM_RISK   | Partial matches of provided name to address.               |
| REJECTED                    | HIGH_RISK     | Provided data does not match available records.            |

</details>

#### Data

<details>
| **Key**                         | **Type**    | **Description**                                                                                 |
|----------------------------------|-------------|-------------------------------------------------------------------------------------------------|
| addressMatch                     | string      | **match**, **no-match**, **partial-match**                                                       |
| nameMatchToSsn                   | string      | **match**, **no-match**, **partial-match**                                                       |
| nameMatchToAddress               | string      | **match**, **no-match**, **partial-match**                                                       |
| phoneMatch                       | string      | **match**, **no-match**, **partial-match**                                                       |
| ssnMatch                         | string      | **match**, **no-match**, **partial-match**                                                       |
| dateOfBirthMatch                 | string      | **match**, **no-match**, **partial-match**                                                       |
| isDeceased                       | string      | The SSN belongs to a deceased person: **true**, **false**                                        |
| isSSNIssuedPriorYOB              | string      | The SSN was issued by the SSA prior to the provided Year of Birth: **true**, **false**           |
</details>

---

# Geo IP Verification

https://documentation.jumio.ai/docs/references/riskSignals/geoIPVerification

# Geo IP Verification

Geo IP Verification provides an overall risk and reputation assessment of an IP address associated with an end user.

## Supported Credentials

The IP address can be uploaded as [Prepared Data](../../references/credentials/#prepared-data). In this case you are expected to obtain the IP address prior to initiating the Jumio transaction. For example you can use to use Geo IP Verification as a standalone service by using workflow key 10118 and uploading the IP address as prepared data.

Alternatively, if you are using Geo IP Verification in a workflow that requires other credentials, and are acquiring those credentials through the Web Client or one of the SDKs, Jumio can obtain the IP address from the end-user device with no additional calls from your integration. For example you can use Geo IP Verification along with the standard IDIV service by using workflow key 10120. The end-user experience with the web client or SDK integration will be the same as the standard IDIV service, and no additional integration effort is required.

| **Key**   | **Type** | **Mandatory** | **Description**                                                             |
| --------- | -------- | ------------- | --------------------------------------------------------------------------- |
| ipAddress | string   | Yes           | The IP address entered as a string. Either IPv4 or IPv6 format is accepted. |

### Example Prepared Data Body

```
{
    "ipAddress": "122.23.23.233"
}
```

### Response

Response data is available for transactions that include the risk signal. For information on transaction data see [Viewing or Retrieving Workflow Transactions](../../developer-resources/retrieval).

```
  "capabilities": {
    "geoIpVerification": [
      {
        "id": "8a1d3dde-f1e5-4832-96c7-1389ad122ab1",
        "credentials": [
          {
            "id": "1230b511-6e82-4c01-a7a3-4e3bcd3a37b1",
            "category": "DATA"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "LOW_RISK"
          }
        },
        "data": {
          "country": "USA",
          "state": "WA",
          "city": "Fort Lauderdale",
          "isp": "Google",
          "organization": "Google",
          "latitude": 26.1995,
          "longitude": -80.0984,
          "accuracyRadius": 1000,
          "anonymous": true,
          "anonymousVpn": true,
          "satelliteProvider": true
        }
      }
    ]
  }
```

### Decision Details Labels

<details>
| **Decision Type** | **Label**    | **Description**                                                                 |
|-------------------|--------------|---------------------------------------------------------------------------------|
| PASSED            | LOW_RISK     | No significant risk of fraudulent activity is associated with the IP address.   |
| REJECTED          | HIGH_RISK    | Significant risk of fraudulent activity is associated with the IP address. See the Data fields for additional information. |
| WARNING           | MEDIUM_RISK  | Moderate risk of fraudulent activity is associated with the IP address. See the Data fields for additional information. |
| NOT_EXECUTED      | TECHNICAL_ERROR | Verify the provided data is correct and retry, or contact [Support](https://support.jumio.com/s/).              |
</details>

### Data

<details>
| **Key**                        | **Type**           | **Description**                                                                            |
|---------------------------------|--------------------|--------------------------------------------------------------------------------------------|
| country                         | string             | Alpha-3 standard country code of IP address                                                 |
| state                           | string             | 2 letter symbol code specifying state                                                      |
| city                            | string             | Name of the city of the IP address                                                         |
| isp                             | string             | Name of the Internet Service Provider                                                      |
| organization                    | string             | Organization of the Internet Service Provider                                              |
| accuracyRadius                  | integer            | Accuracy in kilometers of IP address location from provided coordinates                     |
| latitude                        | number (double)    | Latitude of the IP address                                                                  |
| longitude                       | number (double)    | Longitude of the IP address                                                                 |
| torExitNode*                    | boolean            | true when the IP address is a Tor Browser Exit Node                                        |
| anonymous                       | boolean            | Whether the IP address is associated with an anonymizer such as a VPN or other proxy        |
| anonymousVPN                       | boolean            | Specifically indicates whether the IP address is using an anonymous VPN service.        |
| proxyType                       | string             | Returned if a proxy is used. Example: ANONYMOUS, RESIDENTIAL, PUBLIC                       |
| userType                        | string             | Specifies the behavior observed with typical users. Example: BUSINESS, RESIDENTIAL, HOSTING, CAFE, CELLULAR |
| highBillingPostalCodeVelocity*  | boolean            | The IP address has been used to submit transactions with many different billing addresses in a short period of time. |
| highEmailVelocity*              | boolean            | The IP address has been used to submit transactions with many different email addresses in a short period of time. |
| highIssuerIdVelocity*           | boolean            | The IP address has been used to submit transactions with a high number of Issuer IDs (credit cards, prepaid cards etc.). |
| highRiskDevicesActivity*        | boolean            | The IP address has been used by a high risk device.                                        |
| highRiskEmailsActivity*         | boolean            | A high risk email address was seen on this IP address in past network transactions.         |
| highRiskNetworkActivity*        | boolean            | High risk actors are seen on this IP address.                                              |
</details>

:::note \* Only provided if the value is true, indicating potential fraud.
:::

---

# eKYC Checks

https://documentation.jumio.ai/docs/references/riskSignals/eKYCcheck

# eKYC Checks

eKYC Checks provide a comprehensive global check on individual data elements such as name, address, date of birth, phone number or national ID (if provided). Checks provide a match/partial/no match response. This supports account onboarding use cases such as opening a bank account or a gaming account where you need to verify that the name, address, dateOfBirth, ID, and/or phone number are valid.

eKYC Checks supports both 1+1 and 2+2 checks.

- A 1+1 check looks for a single match of the input data against sources per country.
- A 2+2 checks and looks for two matches of the input data against different sources within the same country.

## Prerequisite

The [Create or Update Accounts](../../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) request body may include an optional ekycCheck object that includes a searchType value. Allowed values are:

- one if requesting a **1+1 check**
- two if requesting a **2+2 check**

If the object is not included in the request body the default value is one.

:::note
The `vendorReferenceId` is available only for Canada 2+2 (Dual Process Method) Check. This returns the vendor transaction reference required to support FINTRAC Dual Process compliance and audit requirements.

Please contact your sales representative to enable this option.
:::

### Example Account Request Body

```
{
    "customerInternalReference": "myCompany",
    "workflowDefinition": {
        "key": 10148,
        "capabilities": {
            "ekycCheck": {
                "searchType": "one"
            }
        }
    },
    ...
}
```

## Supported Credentials

The following values can be uploaded as [Prepared Data](../../references/credentials/#prepared-data). Alternatively, they can be extracted by an upstream capability in a workflow.

To use Prepared Data with eKYC Checks as a standalone capability use workflow key 10148.

<details>
| **Key**            | **Type**        | **Mandatory** | **Description**                                                                         |
|--------------------|-----------------|---------------|-----------------------------------------------------------------------------------------|
| firstName          | string          | yes           | First name of the subject.                                                              |
| lastName           | string          | yes           | Last name of the subject.                                                               |
| dateOfBirth                | string          | no            | Date of birth, in YYYY/MM/DD format.                                                    |
| address            | object          | yes           |                                                                                         |
| address.line1      | string          | yes           | Address line 1 (Street address)                                                         |
| address.line2      | string          | no            | Address line 2 (Apartment, Suite, etc.)                                                  |
| address.city       | string          | yes           | City of residence as it appears on the Id.                                              |
| address.postalCode | string          | yes           | Postal or zip code.                                                                     |
| address.subdivision| string          | no            | City subdivision of residence as it appears on the Id.                                  |
| address.country    | string          | yes           | Country in ISO-3166-1 Alpha-3 Code format.                   |
| phoneNumber        | string          | no            | Phone number of the subject in E.164 format. Country code is required.                  |
| email              | string          | no            | Optimal to include.                                                                     |
| id                 | object          | no            | See next row.                                                                            |
| id.idNumber        | string          | no            | National ID number.                                                                     |
| id.type            | string          | no            | Type of national ID.                                                                    |

</details>

## Example: Prepared Data Body

```
{
  "firstName": "B***",
  "lastName": "S****",
  "email": "b***j@gmail.com",
  "dateOfBirth": "1977-01-01",
  "phoneNumber": "+91-9880001234",
  "id": {
    "idNumber": "VIMK98**27MDFLN***",
    "type": "ID_CARD"
  },
  "address": {
    "line1": "34",
    "postalCode": "560029",
    "city": "",
    "state": "",
    "subdivision": "",
    "country": "MEX"
  }
}
```

## Example Response of 1+1 check

```
"ekycCheck": [
            {
                "id": "427accd1-c23f-4c6c-ba91-b85d84fe681c",
                "credentials": [
                    {
                        "id": "61cf2916-97cd-4f39-b0c3-c1379812d9b5",
                        "category": "DATA",
                        "label": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "LOW_RISK"
                    }
                },
                "data": {
                    "completeNameMatch": "MATCH",
                    "initialNameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "addressMatch": "MATCH",
                    "houseNumberMatch": "MATCH",
                    "thoroughfareMatch": "MATCH",
                    "cityMatch": "MATCH",
                    "stateMatch": "MATCH",
                    "zipOrPinCodeMatch": "MATCH",
                    "dateOfBirthMatch": "NOT_MATCH",
                    "dateOfBirthDayMatch": "NOT_MATCH",
                    "dateOfBirthMonthMatch": "NOT_MATCH",
                    "dateOfBirthYearMatch": "MATCH",
                    "phoneMatch": "MATCH",
                    "datasourceType": "Commercial",
                    "searchType": "1+1",
                    "matchType": "1+1"
                    "datasourceSummary": [
                        {
                            "completeNameMatch": "MATCH",
                            "initialNameMatch": "MATCH",
                            "firstNameMatch": "MATCH",
                            "lastNameMatch": "MATCH",
                            "addressMatch": "MATCH",
                            "houseNumberMatch": "MATCH",
                            "thoroughfareMatch": "MATCH",
                            "cityMatch": "MATCH",
                            "stateMatch": "MATCH",
                            "zipOrPinCodeMatch": "MATCH",
                            "dateOfBirthYearMatch": "MATCH",
                            "phoneMatch": "MATCH",
                            "source": "CMM1"
                        },
                },
```

## Example Response of 2+2 check

```
"capabilities": {
        "ekycCheck": [
            {
                "id": "b4b30e84-fcf6-4286-9c94-5ba81a20c084",
                "credentials": [
                    {
                        "id": "292125ae-24b4-4d70-8311-c0329967563d",
                        "category": "DATA",
                        "label": "DATA"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "LOW_RISK"
                    }
                },
                "data": {
                    "completeNameMatch": "MATCH",
                    "initialNameMatch": "MATCH",
                    "firstNameMatch": "MATCH",
                    "lastNameMatch": "MATCH",
                    "nationalIdMatch": "MATCH",
                    "addressMatch": "MATCH",
                    "houseNumberMatch": "MATCH",
                    "thoroughfareMatch": "MATCH",
                    "cityMatch": "MATCH",
                    "stateMatch": "MATCH",
                    "zipOrPinCodeMatch": "MATCH",
                    "dateOfBirthMatch": "NOT_MATCH",
                    "dateOfBirthDayMatch": "NOT_MATCH",
                    "dateOfBirthMonthMatch": "NOT_MATCH",
                    "dateOfBirthYearMatch": "MATCH",
                    "phoneMatch": "MATCH",
                    "datasourceType": "Commercial,Postal",
                    "searchType": "2+2",
                    "matchType": "2+2",
                    "vendorReferenceId": "WS-8979396.2026.5.25.16.38.32.444",
                    "datasourceSummary": [
                        {
                            "completeNameMatch": "MATCH",
                            "initialNameMatch": "MATCH",
                            "firstNameMatch": "MATCH",
                            "lastNameMatch": "MATCH",
                            "addressMatch": "MATCH",
                            "houseNumberMatch": "MATCH",
                            "thoroughfareMatch": "MATCH",
                            "cityMatch": "MATCH",
                            "stateMatch": "MATCH",
                            "zipOrPinCodeMatch": "MATCH",
                            "dateOfBirthYearMatch": "MATCH",
                            "phoneMatch": "MATCH",
                            "source": "CMM2"
                        },
                        {
                            "completeNameMatch": "MATCH",
                            "initialNameMatch": "MATCH",
                            "firstNameMatch": "MATCH",
                            "lastNameMatch": "MATCH",
                            "addressMatch": "MATCH",
                            "houseNumberMatch": "MATCH",
                            "thoroughfareMatch": "MATCH",
                            "cityMatch": "MATCH",
                            "stateMatch": "MATCH",
                            "zipOrPinCodeMatch": "MATCH",
                            "dateOfBirthDayMatch": "NOT_MATCH",
                            "dateOfBirthMonthMatch": "NOT_MATCH",
                            "dateOfBirthYearMatch": "NOT_MATCH",
                            "source": "PST1"
                        }
                    ]
                },
```

### Decision Details Labels

<details>

| **Decision Type** | **Label**                  | **Description**                                 |
| ----------------- | -------------------------- | ----------------------------------------------- |
| PASSED            | LOW_RISK                   | No significant risk associated with the data.   |
| REJECTED          | HIGH_RISK                  | High risk associated with the data.             |
| WARNING           | MEDIUM_RISK                | Moderate risk associated with the data.         |
| NOT_EXECUTED      | VALIDATION_FAILED          | The data provided failed validation.            |
| NOT_EXECUTED      | NOT_ENOUGH_DATA            | Not enough data to process the request.         |
| NOT_EXECUTED      | PRECONDITION_NOT_FULFILLED | Preconditions were not met to process the data. |
| NOT_EXECUTED      | TECHNICAL_ERROR            | There was an error in processing the request.   |

</details>

### Data

<details>
| Parameter                | Type     | Description                                                                 |
|--------------------------|----------|-----------------------------------------------------------------------------|
| completeNameMatch        | string   | "MATCH", "NOT_MATCH": The match status of the combined first and last name values. |
| initialNameMatch         | string   | "MATCH", "NOT_MATCH": The match status of the first initial.                 |
| firstNameMatch           | string   | "MATCH", "NOT_MATCH": The match status of the first name.                    |
| lastNameMatch            | string   | "MATCH", "NOT_MATCH": The match status of the last name.                     |
| nationalIdMatch          | string   | "MATCH", "NOT_MATCH": The match status of the ID. National ID may not always be supported in countries. |
| addressMatch             | string   | "MATCH", "NOT_MATCH": The match status of the complete address.              |
| houseNumberMatch         | string   | "MATCH", "NOT_MATCH": The match status of the house number.                  |
| thoroughfareMatch        | string   | "MATCH", "NOT_MATCH": The match status of the thoroughfare.                  |
| cityMatch                | string   | "MATCH", "NOT_MATCH": The match status of the address city.                  |
| zipOrPinCodeMatch        | string   | "MATCH", "NOT_MATCH": The match status of the address zip or PIN code.       |
| dateOfBirthMatch         | string   | "MATCH", "NOT_MATCH": The match status of the entire date of birth.          |
| dateOfBirthDayMatch      | string   | "MATCH", "NOT_MATCH": The match status of the date of birth day.             |
| dateOfBirthMonthMatch    | string   | "MATCH", "NOT_MATCH": The match status of the date of birth month.           |
| dateOfBirthYearMatch     | string   | "MATCH", "NOT_MATCH": The match status of the date of birth year.            |
| phoneMatch               | string   | "MATCH", "NOT_MATCH": The match status of the phone number.                  |
| datasourceType           | string   | The country and the type of data source. Possible types: Credit, Government, Commercial, Consumer, Utility, Proprietary, Telco, Postal. Multiple sources may be listed, separated by commas. |
| searchType               | string   | "2+2", "1+1": Whether search is looking for 1 database match (1+1) or 2 database matches (2+2). |
| matchType                | string   | "2+2", "1+1": Whether a MATCH must be found in 1 database or two databases.  |
| vendorReferenceId        | string   | Vendor transaction reference returned for Canada 2+2 (Dual Process Method) checks. This supports FINTRAC Dual Process compliance and audit requirements. Available only when enabled for your account. Please contact your sales representative to enable this option.  |
| datasourceSummary        | object   | Shows the specific data sources used in the transaction. Multiple datasource summary sections may be listed for 2+2. |
| completeNameMatch        | string   | "MATCH", "NOT_MATCH": The match status of the combined first and last name values. |
| initialNameMatch         | string   | "MATCH", "NOT_MATCH": The match status of the first initial.                 |
| firstNameMatch           | string   | "MATCH", "NOT_MATCH": The match status of the first name.                    |
| lastNameMatch            | string   | "MATCH", "NOT_MATCH": The match status of the last name.                     |
| nationalIdMatch          | string   | "MATCH", "NOT_MATCH": The match status of the ID. National ID may not always be supported in countries. |
| addressMatch             | string   | "MATCH", "NOT_MATCH": The match status of the complete address.              |
| houseNumberMatch         | string   | "MATCH", "NOT_MATCH": The match status of the house number.                  |
| thoroughfareMatch        | string   | "MATCH", "NOT_MATCH": The match status of the thoroughfare.                  |
| cityMatch                | string   | "MATCH", "NOT_MATCH": The match status of the address city.                  |
| zipOrPinCodeMatch        | string   | "MATCH", "NOT_MATCH": The match status of the address zip or PIN code.       |
| dateOfBirthMatch         | string   | "MATCH", "NOT_MATCH": The match status of the entire date of birth.          |
| dateOfBirthDayMatch      | string   | "MATCH", "NOT_MATCH": The match status of the date of birth day.             |
| dateOfBirthMonthMatch    | string   | "MATCH", "NOT_MATCH": The match status of the date of birth month.           |
| dateOfBirthYearMatch     | string   | "MATCH", "NOT_MATCH": The match status of the date of birth year.            |
| phoneMatch               | string   | "MATCH", "NOT_MATCH": The match status of the phone number.                  |
| source                   | string   | "PST1": Displays the type of data source for the transaction. Examples - PST1 (Postal data source 1). Multiple sources may be listed. |
</details>

---

# Services and Workflows

https://documentation.jumio.ai/docs/references/servicesAndworkflow/services-workflow

# Workflow Fundamentals

A Jumio workflow is a business process definition that orchestrates calls to one or more Jumio service(s) or risk signal(s). Each serviceClosed or risk signalClosed is a step in the workflow. Each step is a sub-flow that orchestrates one or more Jumio capabilities. A capabilityClosed is a modular service that handles a specific task.

A workflow also defines the credentials that will be evaluated during the process.

Jumio provides workflows that meet the requirements of many customers. For example,

- [Standard Services](../../references/servicesAndworkflow/standardService/standardServices) are each available as standalone workflows.
- Custom workflows can be designed with a Jumio Solutions Engineer (SE) to integrate [risk signals](../../references/riskSignals/overviewRiskSignals) based on your requirements.

For more details, refer to:

- [Integrating Jumio Services](/docs/developer-resources/API/Integration_Intro) for introductory information on how workflows are used in Jumio transactionsClosed.
- [Identification Document and Identity Verification (IDIV) Workflow](/docs/references/servicesAndworkflow/standardService/IDIVService) for a detailed description of one of Jumio's standard workflows.
- [Creating or Updating Accounts](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts) for information on how to specify the workflow to use for a transaction associated with an end-user accountClosed.

---

# Standard Service

https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/standardServices

# What are Standard Services?

The standard services include the workflows such as Identity and Selfie Verification (ID+ Selfie Verification) and Authentication.

The following table lists some standard Jumio services that can be used as standalone workflows or as steps in other workflows.
:::info
Please coordinate with your Jumio Account Manager to ensure you have the appropriate access to this service for the workflow to function as expected.
:::

| **Service**                                            | **Standalone Workflow Key** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                         | **Credentials**                                                                                         | **Capabilities**                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ID + Selfie Verification**                           | 10549                       | Includes both ID Verification and Identity Verification. Takes a government-issued ID (e.g., passport, driver’s license, or national ID card) and a selfie as credentials. It also requires [uploading supporting data](/docs/developer-resources/API/uploadingSupportData). Verifies that the government-issued ID is authentic and valid, the selfie is of a real person, and the person in the selfie is the same person that is pictured on the ID. | [ID](../../credentials/#id), [Selfie](../../credentials/#selfie), [Facemap](../../credentials/#facemap) | [Usability](../../capabilities/usability), [Extraction](../../capabilities/extraction), [Image Checks](../../capabilities/image-checks), [Data Checks](../../capabilities/data-checks), [Liveness](../../capabilities/liveness), [Similarity](../../capabilities/similarity)                                                      |
| **ID Verification**                                    | 10166                       | Verifies that a government-issued photo ID (e.g., passport, driver’s license, or national ID card) is authentic and valid. It also requires [uploading supporting data](/docs/developer-resources/API/uploadingSupportData)                                                                                                                                                                                                                             | [ID](../../credentials/#id)                                                                             | [Usability](../../capabilities/usability), [Extraction](../../capabilities/extraction), [Image Checks](../../capabilities/image-checks), [Data Checks](../../capabilities/data-checks)                                                                                                                                            |
| **ID + Selfie Verification, plus Watchlist Screening** | 10551                       | All the same functionality as ID & Identity Verification (10547) plus watchlist screening. ID & Identity Verification are performed first. If no fraud is detected, the [Watchlist screening](../../capabilities/watchlist) capability is called to screen the user against global and regional sanctions and watchlists, to identify PEPs.                                                                                                             | [ID](../../credentials/#id), [Selfie](../../credentials/#selfie), [Facemap](../../credentials/#facemap) | [Usability](../../capabilities/usability), [Extraction](../../capabilities/extraction), [Image Checks](../../capabilities/image-checks), [Data Checks](../../capabilities/data-checks), [Liveness](../../capabilities/liveness), [Similarity](../../capabilities/similarity), [Watchlist screening](../../capabilities/watchlist) |
| **Authentication**                                     | 10014                       | Compares a new selfie to an existing face map. For additional information see [authentication Workflow](../../servicesAndworkflow/standardService/authenticationWorkflow).                                                                                                                                                                                                                                                                              | [Selfie](../../credentials/#selfie), [Facemap](../../credentials/#facemap)                              | [Authentication](../../capabilities/authentication-capabilities)                                                                                                                                                                                                                                                                  |
| **Document Proof**                                     | 10170                       | Jumio Document Verification enables your customers to quickly scan and upload documents such as utility bills, credit card statements, bank statements, or Social Security cards, even if the documents are crumpled or creased. It also requires [uploading supporting data](/docs/developer-resources/API/uploadingSupportData). Relevant data is extracted from the document and may be used with other services or risk signals.                    | [Document](../../credentials/#document)                                                                 | [Usability](../../capabilities/usability), [Extraction](../../capabilities/extraction), [Image Checks](../../capabilities/image-checks)                                                                                                                                                                                           |
| **ID Capture and Storage**                             | 10172                       | Extracts and stores data from a government-issued ID. It also requires Uploading Supporting Data.                                                                                                                                                                                                                                                                                                                                                       | [ID](../../credentials/#id)                                                                             | [Usability](../../capabilities/usability), [Extraction](../../capabilities/extraction)                                                                                                                                                                                                                                            |

---

# ID + Selfie Verification

https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/IDIVService

# Identity and Selfie Verification Workflow

**Identity and Selfie Verification Workflow** is commonly used during the onboarding of new users, especially when entering into sensitive relationships. It ensures that the user is a real, verified identity and confirms that the individual is indeed the person described by the provided ID. It majorly comprises of,

- Evaluates a government-issued identification document (ID) to verify that it is valid.
- Evaluates a “selfie” to verify that it is of an actual live person.
- Compares the selfie to the picture on the ID to verify that they are the same person.

## Account Creation or Update

All Jumio Platform transactions are associated with an accountClosed. The account is nothing more than a unique identifier that is used to associate the transactions and credentials for a unique identity. If you are onboarding a new user and this is the first Jumio transaction executed for the user, then you would create a new account.

:::tip
While ID + Selfie Verification transactions are often executed as the first transaction associated with an account, there are valid scenarios where you would run ID + Selfie Verification on an existing account. An example of that would be if you performed an email verification and/or address verification on the user prior to the ID + Selfie Verification. Simple verifications are often faster and less expensive than a full ID + Selfie Verification transaction, so it may be worthwhile to perform an initial verification to eliminate known bad actors prior to incurring the expense of the ID + Selfie Verification transaction. In this case you would create the account for the initial verification, and then update the account to run the IDIV transaction if the user appears to be legitimate.
:::

Creating or updating an account is always done with a call to the Accounts REST API. ([Learn more](/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts))

### Account Response

The response to the request to create or update an account contains the information you need to proceed with the workflow, including:

- The URL and authorization token for the Jumio Web Client.
- You use this when your end-user is working in a web browser.
- The authorization token (JWT) for initializing the Jumio SDK implementation in the mobile apps you have implemented. Your organization implements the SDKs when your end-users use a mobile app.
- A list of the credentials that will be uploaded during the customer journey. These include:
  - [Government-issued ID document](/docs/references/credentials/#document)
  - [Selfie](/docs/references/credentials#selfie)
  - [Facemap](/docs/references/credentials#facemap) (a facemap is created and uploaded as part of the customer journey when your Jumio integration uses either the Web Client or the mobile SDKs. If your integration uses the raw REST APIs, you cannot upload a facemap).

### Sample Account Creation Request and Response

Following are sample request and response bodies, in JSON format, for the account creation API call.

**Account Creation Request Body**

```
{
    "customerInternalReference":"myCompany",
    "callbackUrl":"https://portal.mycompany.com/callback",
    "workflowDefinition":{
        "key": 10549
    }
```

**Account Creation Response Body**

```
{
    "timestamp": "2022-11-28T23:45:02.536Z",
    "account": {
        "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
    },
    "web": {
        "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&amp;locale=en-US"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
    },
    "workflowExecution": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "credentials": [
            {
                "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            },
            {
                "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            }
        ]
    }
}
```

## ID+Selfie Verification Customer Journey

The customer journeyClosed is usually managed by the Jumio Web Client and/or Mobile SDKs. When you integrate Jumio with your web or mobile applications you redirect your end-users to the UI screens Jumio provides for guiding them through the process of taking pictures of the ID and taking the selfie. The images are automatically uploaded to Jumio and associated with the account.

Optionally you can upload supporting data you have already collected from the end user, such as a phone number, address, or email address. Providing this information enhances fraud detection increases the probability of correctly matching the end user with other data sources.

:::tip
If you already have a Jumio customer account and would like to experience the ID+Selfie Verification customer journey, you can use the [Jumio Showcase app](/docs/portals/settings/IDVSettings#app-showcase) from your personal device. Log in to the Jumio Portal and go to **_*Settings > Identity Verification > App Showcase*_** for details.
:::

### Uploading Supporting Data

If you are using a version of the ID+Selfie Verification workflow that supports uploading supporting data you upload it as Prepared Data.

### Launching the Web Client

If you are implementing the Jumio Web Client, the URL including the authorization token is available from the Account response body:

```
"web": {
        "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&amp;locale=en-US"
},
```

### Initializing the SDKs

If you are using a Jumio SDK, the authorization token for initializing the SDK is also available from the Account response body:

```
"sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
},
```

### Uploading ID and Selfie Credentials

It is possible to develop your own implementation of the customer journey. In that case you are responsible for guiding the end user to provide the required ID and Selfie, and then using the URLs and token provided in the Account response body to upload the credentials to Jumio.

:::caution
If you implement your own customer journey, you cannot upload a [Facemap](/docs/references/credentials/credentials#facemap). The reliability of the [Liveness](/docs/references/capabilities/liveness) capability will be reduced, since it has only the single [Selfie](/docs/references/credentials/credentials#selfie) credential to work with. In the example below, notice that the JSON object for the FACEMAP credential only supports the WEB and SDK channels, and does not provide an api object.
:::

```
    "workflowExecution": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "credentials": [
            {
                "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            },
            {
                "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            }
        ]
    }
```

## ID+Selfie Verification Steps and Capabilities

When the customer journey has been completed successfully the workflow is executed on the Jumio servers.

Each capability renders an independent decision about the credentials it evaluates. The overall decision returned by the workflow is based on an evaluation of the capability decisions.

- **[Usability](/docs/references/capabilities/usability)**: The usability capability is the first service called by the workflow. It provides a number of checks on each of the images that were uploaded during the customer journey. The checks verify that the images are suitable for further evaluation. A decision is rendered for each image. If the decision is something other than PASSED then a label is provided with a reason for why it did not pass.

- **[Extraction](/docs/references/capabilities/extraction)**: The extraction capability extracts the relevant data values from the government-issued ID. These values are then used by the data checks capability. Exactly what values are extracted depends on the country and type of ID.

- **[Image Checks](/docs/references/capabilities/image-checks)**:
  The image checks capability evaluates the government-issued ID to ensure that it is valid and authentic.

- **[Data Checks](/docs/references/capabilities/data-checks)**:
  The data checks capability runs a number of fraud checks against the extracted data, selfie, and facemap.

- **[Similarity](/docs/references/capabilities/similarity)**:
  The similarity capability compares the image in the selfie to the picture on the government-issued ID.

- **[Liveness](/docs/references/capabilities/liveness)**:
  If a Facemap is uploaded during the customer journey (Web Client and mobile SDK integrations only) the Facemap is evaluated to ensure that the subject is a live person.

## Handling the IDIV Response

The workflow transaction generates data that you can access and use to determine subsequent actions to take regarding the account. The data can be viewed manually in the Jumio Portal, or obtained by Calling Retrieval APIs. The data includes:

- Metadata about the transaction, including:

  - Transaction ID : The unique identifier for the transactionClosed.
  - Account ID : The unique identifier for the end user accountClosed.
  - Initiated : The UTC timestamp when the end user started the customer journeyClosed.
  - Started : The UTC timestamp when the workflow execution started, following the call to finalize after all credentials were uploaded.
  - Completed : The UTC timestamp when the transaction was completed, the decision was available, and the documents saved.
  - Token Expiry : The UTC timestamp when the authorization token for uploading credentials expired.

- The overall workflow decision and risk score.
- Results from each capability, including the capability decision, labels describing why the decision was made, and the credentials that were evaluated.
- URLs for downloading the credentials that were evaluated.
  The information is also available from the retrieval API response, as shown in the following example:

<details>
<summary>Click to expand the code</summary>

```
{
    "workflow": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "status": "PROCESSED",
        "definitionKey": "10549",
        "userReference": "MyUser",
        "customerInternalReference": "MyCompany"
    },
    "account": {
        "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
    },
    "createdAt": "2022-11-28T23:45:02.528Z",
    "startedAt": "2022-11-28T23:50:37.221Z",
    "completedAt": "2022-11-28T23:50:55.232Z",
    "credentials": [
        {
            "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
            "category": "SELFIE",
            "parts": [
                {
                    "classifier": "FACE",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                }
            ]
        },
        {
            "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
            "category": "FACEMAP",
            "parts": [
                {
                    "classifier": "FACEMAP"
                },
                {
                    "classifier": "LIVENESS_1",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_1"
                },
                {
                    "classifier": "LIVENESS_3",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_3"
                },
                {
                    "classifier": "LIVENESS_2",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_2"
                },
                {
                    "classifier": "LIVENESS_5",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_5"
                },
                {
                    "classifier": "LIVENESS_4",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_4"
                },
                {
                    "classifier": "LIVENESS_6",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_6"
                }
            ]
        },
        {
            "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
            "category": "ID",
            "parts": [
                {
                    "classifier": "FRONT",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT"
                },
                {
                    "classifier": "BACK",
                    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                }
            ]
        }
    ],
    "decision": {
        "type": "WARNING",
        "details": {
            "label": "WARNING"
        },
        "risk": {
            "score": 50.0
        }
    },
    "steps": {
        "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/steps"
    },
    "capabilities": {
        "extraction": [
            {
                "id": "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
                "credentials": [
                    {
                        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "DRIVING_LICENSE",
                    "subType": "REGULAR_DRIVING_LICENSE",
                    "issuingCountry": "USA",
                    "firstName": "JOHN",
                    "lastName": "DOE",
                    "dateOfBirth": "1964-08-20",
                    "expiryDate": "2026-08-20",
                    "issuingDate": "2020-08-20",
                    "documentNumber": "A12345676",
                    "state": "CA",
                    "gender": "M",
                    "currentAge": "58"
                }
            }
        ],
        "similarity": [
            {
                "id": "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
                "credentials": [
                    {
                        "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                        "category": "SELFIE"
                    },
                    {
                        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "MATCH"
                    }
                },
                "data": {
                    "similarity": "MATCH"
                }
            }
        ],
        "liveness": [
            {
                "id": "789f4e4a-7c2f-4764-a98d-c519d082ba6d",
                "validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/FACEMAP",
                "credentials": [
                    {
                        "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                        "category": "SELFIE"
                    },
                    {
                        "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                },
                "data": {
                    "type": "JUMIO_STANDARD",
                    "predictedAge": 44,
                    "ageConfidenceRange": "14-67"
                }
            }
        ],
        "dataChecks": [
            {
                "id": "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
                "credentials": [
                    {
                        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ],
        "imageChecks": [
            {
                "id": "b336a404-7775-4793-9cf6-30a7e5be1d0b",
                "credentials": [
                    {
                        "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                        "category": "SELFIE"
                    },
                    {
                        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "WARNING",
                    "details": {
                        "label": "REPEATED_FACE"
                    }
                },
                "data": {
                    "faceSearchFindings": {
                        "status": "DONE",
                        "findings": [
                            "22771260-8cb0-42a2-a38a-d8f853063cc2",
                            "27232651-4b18-4cf1-8d4a-df0451abc717",
                            "9541ae91-834e-4914-a30d-6534fed4eb6d",
                            "9414413d-2c76-44d2-9052-8876fa327a02"
                        ]
                    }
                }
            }
        ],
        "usability": [
            {
                "id": "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
                "credentials": [
                    {
                        "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                        "category": "ID"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
                "credentials": [
                    {
                        "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                        "category": "FACEMAP"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            },
            {
                "id": "e991586b-3345-4a2d-bfc3-1690ccb477b3",
                "credentials": [
                    {
                        "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                        "category": "SELFIE"
                    }
                ],
                "decision": {
                    "type": "PASSED",
                    "details": {
                        "label": "OK"
                    }
                }
            }
        ]
    }
}

```

</details>

---

# Authentication Workflow

https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/authenticationWorkflow

# Authentication Workflow

When an end user you have already onboarded returns to your platform, use Jumio Authentication to verify they are the same person. Jumio Authentication captures a new selfie and compares it to the existing reference selfie already associated with the user’s account.

Typically, the reference selfie is the one collected during the initial onboarding process using the Identification Document and [Identity and Selfie Verification](../../servicesAndworkflow/standardService/IDIVService) workflow.

Depending on your organization’s data retention policy (see [Data Settings](../../../portals/settings/IDVSettings#data-settings)), the reference selfie is:

Stored on Jumio’s servers and associated with the user’s account if it is still within the configured retention period.

Deleted from Jumio’s servers if it is beyond the retention period. In that case, if you wish to run authentication, you must have stored the reference selfie on your own servers and upload it before performing authentication with the new selfie.

When someone claiming to be an end-user you have already onboarded returns to your platform, use Jumio Authentication to make sure they really are the same person. Jumio Authentication captures a fresh [Selfie](../../../references/credentials/#selfie) and [Facemap](../../../references/credentials/#facemap) and compares them to an existing Facemap that is already associated with the end-user account.

Typically the existing Facemap is the one that was acquired when the end user was first onboarded using the [Identification Document and Identity Verification (IDIV) Workflow](../../servicesAndworkflow/standardService/IDIVService). Depending on your organization's Data Retention policy (See [Data Settings](../../../portals/settings/IDVSettings#data-settings)) that Facemap is:

- Stored on Jumio's servers, and associated with the accountClosed if it is within the configured Data retention period.
- Facemap data is deleted from Jumio's servers once it exceeds the configured data retention period. Please note that with Jumio Liveness, it is no longer possible to download and store facemap data.

:::info
You must record and retain the account ID generated by the on-boarding transaction. The account ID value can be obtained from the Portal or from the API responses. For additional information see [Creating or Updating Accounts](../../../developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts).
:::

When you have an existing end user account with an existing Facemap, the process to authenticate the same user is as follows:

- Update the Account to Initiate an Authentication Transaction
- Complete the Customer Journey for the Authentication Transaction
- Retrieve the Decision

## Update the Account to Initiate an Authentication Transaction

Use the [PUT](https://documentation.jumio.ai/developer-resources/API/account) request for the Accounts API to update the existing end user account. The account ID value saved from the on-boarding transaction is used as a path parameter in the request URL.

In the request body, specify workflow key 10014 to use the standard Authorization workflow.

:::tip
Workflow 10014 uses the Authentication capability to compare a newly-acquired Facemap to the existing Facemap. If you require a custom workflow with additional services or risk signals contact your Jumio representative.
:::

**Example Request Body**

```
{
"customerInternalReference":"transaction_1234",
  "workflowDefinition":{
  "key": 10014
  }
}
```

### Providing the End-User Consent

If your integration uses one of the [Mobile SDKs](/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile) with a custom user interface you can use the original consent obtained when the end user was onboarded instead of requiring the end user to provide an explicit consent for each authentication transaction. In this case you must have recorded the timestamp from the onboarding, and be able to use it to set the userConsent values, as shown in the example below. The original consent can be valid for a maximum of 3 years. Beyond that the end user must explicitly provide the consent, as described [here](https://documentation.jumio.ai/docs/developer-resources/API/end-user-consent).

```
{
   "customerInternalReference":"transaction_1234",
   "workflowDefinition":{
     "key": 10014
   },
   "userConsent":
     "consent": {
       "obtained": "yes",
       "obtainedAt": "2022-07-20T17:20:35.000Z"
     }
  }
}
```

## Complete the Customer Journey for the Authentication Transaction

Authentication requires your integration to use either the [Web Client](../../../developer-resources/web-client/web-client.md) or one of the [Mobile SDKs](/docs/developer-resources/SDKs/mobile-sdk/introduction-mobile). A new Facemap is required, which cannot be uploaded through the REST APIs. See [Credential Acquisition](../../../developer-resources/API/credential-acquisition) for additional information.

The end user is guided to take the new Selfie and Facemap. When they have been successfully uploaded the workflow is finalized.

## Retrieve the Decision

If your integration has a [callback](../../../developer-resources/callback) service it will be notified when the transaction is complete. Alternatively you can call the [Transaction Status API](https://documentation.jumio.ai/developer-resources/api/status-endpoint) to determine if the transaction has been PROCESSED.

Once the transaction has completed you can call the [Workflow Details API](../../../developer-resources/retrieval#workflow-details) to retrieve the decision and other workflow data.

<details>
<summary>Example Details Response</summary>
```
{
  "workflow": {
    "id": "UUID",
    "status": "PROCESSED",
    "definitionKey": "10014",
    "customerInternalReference": "transaction_1234"
  },
  "account": {
    "id": "UUID"
  },
  "createdAt": "2023-04-19T17:54:28.218Z",
  "startedAt": "2023-04-19T17:55:15.170Z",
  "completedAt": "2023-04-19T17:55:16.126Z",
  "credentials": [
    {
      "id": "UUID",
      "category": "SELFIE",
      "parts": [
        {
          "classifier": "FACE",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/c4daab5f-bbe7-4fea-8d0e-1e6a9fa0094a/parts/FACE"
        }
      ]
    },
    {
      "id": "UUID",
      "category": "FACEMAP",
      "parts": [
        {
          "classifier": "FACEMAP"
        },
        {
          "classifier": "LIVENESS_1",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_1"
        },
        {
          "classifier": "LIVENESS_3",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_3"
        },
        {
          "classifier": "LIVENESS_2",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_2"
        },
        {
          "classifier": "LIVENESS_5",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_5"
        },
        {
          "classifier": "LIVENESS_4",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_4"
        },
        {
          "classifier": "LIVENESS_6",
          "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_6"
        }
      ]
    }
  ],
  "decision": {
    "type": "PASSED",
    "details": {
      "label": "PASSED"
    },
    "risk": {
      "score": 0.0
    }
  },
  "steps": {
    "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/a6692412-a1e1-4fbc-a3fa-79c210af25b6/steps"
  },
  "capabilities": {
    "usability": [
      {
        "id": "UUID",
        "credentials": [
          {
            "id": "UUID",
            "category": "SELFIE"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      },
      {
        "id": "UUID",
        "credentials": [
          {
            "id": "UUID",
            "category": "FACEMAP"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        }
      }
    ],
    "authentication": [
      {
        "id": "UUID",
        "validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/FACEMAP",
        "credentials": [
          {
            "id": "UUID",
            "category": "FACEMAP"
          }
        ],
        "decision": {
          "type": "PASSED",
          "details": {
            "label": "OK"
          }
        },
        "data": {
          "type": "JUMIO_STANDARD"
        }
      }
    ]
  }
}
```
</details>

---

# Authentication On-Premises

https://documentation.jumio.ai/docs/references/servicesAndworkflow/standardService/authenticationOnPremises

# Authentication On-Premises

Designed for organizations with strict Data Retention policies, **Authentication On-Premises offers the same functionality as the Authentication Workflow while ensuring end-user credentials are deleted after a defined timeframe**. As with the Authentication Workflow, when someone claiming to be an end-user you have already onboarded returns to your platform, a fresh Selfie and Facemap are captured and compared to an existing Facemap.

However, since the original Facemap generated by the onboarding process may have been deleted from Jumio's servers, you must upload the existing Facemap that will be used for the comparison. In this case you must have downloaded and stored the Facemap that was acquired as part of the end-user onboarding before it was deleted. You can then upload the stored Facemap and use it with the Authentication On-Premises workflow.

## Retrieve the Onboarding Facemap

After the end user has successfully onboarded, but before the credentials are deleted in accordance with your Data Retention policies, you can download the Facemap and store it for future use with Authentication On-Premises.

:::caution
Your tenant must be configured to allow downloading a Facemap. Contact Jumio Support to make sure that the Allow download of facemap option is enabled.
:::

When Allow download of facemap is enabled the [Workflow Details API](/docs/developer-resources/retrieval#workflow-details) response from the on-boarding workflow includes the URL you can use to retrieve the Facemap as a single binary file, refer [GET parts API](../../../developer-resources/API/retrieval).

Download and store the Facemap file, along with the account ID so they can be accessed as needed for subsequent authentications.

Example FACEMAP href

```
   "credentials": [
      {
         ...
      },
      {
         "id": "4915434a-9b0f-4bbf-b088-dfea00b4b680",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/FACEMAP"
            },
...
```

## Update the Account to Initiate an Authentication On-Premises Transaction

Use the PUT request for the Accounts API to update the existing end user account. The account ID value saved from the on-boarding transaction is used as a path parameter in the request URL.

In the request body, specify workflow key 10071 to use the standard Authorization On-Premises workflow.

:::note
Workflow 10071 uses the Authentication capability to compare a newly-acquired Facemap to a Facemap you upload using the API. If you require a custom workflow with additional services or risk signals contact your Jumio representative.
:::

The response body will include three credential objects:

- A FACEMAP that will have allowed channels for WEB and SDK. This is the new FACEMAP that will be generated as part of the WEB or SDK customer journey.
- A FACEMAP with the API allowed channel, and an api:parts:facemap URL you can use to upload the stored FACEMAP.
- A SELFIE that will have allowed channels for WEB and SDK. This is the new SELFIE that will be generated as part of the WEB or SDK customer journey.

Example Request Body

```
{
    "customerInternalReference":"transaction_1234",
    "workflowDefinition":{
    "key": 10071
    }
}
```

Example Response Credentials

```
{
...
   "workflowExecution": {
      "id": "UUID",
      "credentials": [
         {
            "id": "UUID",
            "category": "FACEMAP",
            "allowedChannels": [
               "WEB",
               "SDK"
            ]
         },
         {
            "id": "UUID",
            "category": "FACEMAP",
            "allowedChannels": [
               "API"
            ],
            "api": {
               "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAxA0btkxpLjOI7DxsjKDRInYWkBiUogIe5Oi7gA69cb_sv152Fxe-dFvUaRQIHI7VwxO7a1UxS1JAhYYgUumKBWG9BS4R6txUpj41-MSXs2qdCpZWBjD2qkIJQ8StDUgl_xY_R_uJ36WPXtel_mcoHlOp_ByjRtm79JGYwYFTxjBCZpUIUbBOOiOY9uUd37Azm5chvsAAAA.We0X_lp4xFxKS8C4nz5nY5y13R9UJvm4uaobVof5o8qCV4eBA-bXmPkSiEAaqRNGAnXfp5fdZSgz5zxIJUprzg",
               "parts": {
                  "facemap": "https://api.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/078e9c6b-e2d9-4c41-8c28-627106387d31/credentials/eda8ebae-8c84-4fa0-8f9d-6538e907e04f/parts/FACEMAP"
               },
               "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/078e9c6b-e2d9-4c41-8c28-627106387d31"
            }
         },
         {
            "id": "UUID",
            "category": "SELFIE",
            "allowedChannels": [
               "WEB",
               "SDK"
            ]
         }
      ]
   }
}
```

## Upload the Stored Facemap

After the account is updated but before the customer journey is initiated, upload the stored Facemap using a POST request with the `api:parts:facemap` URL in the response to the account update.

:::warning
Do not make the call to finalize the workflow after uploading the Facemap. Instead, once the Facemap is successfully uploaded, initiate the customer journey as you would with any other WEB Client or SDK workflow.
:::

## Retrieve the Decision

If your integration has integrated a [Callback](https://documentation.jumio.ai/docs/developer-resources/callback) service it will be notified when the transaction is complete. Alternatively you can call the [Transaction Status API](../../../developer-resources/API/retrieval) to determine if the transaction has been PROCESSED.

Once the transaction has completed you can call the [Workflow Details API](https://documentation.jumio.ai/developer-resources/api/retrieval) to retrieve the decision and other workflow data.

<details>
<summary>Example Details Response</summary>
```
{
   "workflow": {
      "id": "UUID",
      "status": "PROCESSED",
      "definitionKey": "10071",
      "customerInternalReference": "MyCompany"
   },
   "account": {
      "id": "UUID"
   },
   "createdAt": "2023-04-27T21:17:44.771Z",
   "startedAt": "2023-04-27T21:20:22.086Z",
   "completedAt": "2023-04-27T21:20:22.915Z",
   "credentials": [
      {
         "id": "UUID",
         "category": "SELFIE",
         "parts": [
            {
               "classifier": "FACE",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/7b9f5a06-76bf-483c-ab9c-041fc3cff2c6/parts/FACE"
            }
         ]
      },
      {
         "id": "UUID",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP"
            },
            {
               "classifier": "LIVENESS_1",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_1"
            },
            {
               "classifier": "LIVENESS_3",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_3"
            },
            {
               "classifier": "LIVENESS_2",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_2"
            },
            {
               "classifier": "LIVENESS_5",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_5"
            },
            {
               "classifier": "LIVENESS_4",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_4"
            },
            {
               "classifier": "LIVENESS_6",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_6"
            }
         ]
      },
      {
         "id": "UUID",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP"
            }
         ]
      }
   ],
   "decision": {
      "type": "PASSED",
      "details": {
         "label": "PASSED"
      },
      "risk": {
         "score": 0.0
      }
   },
   "steps": {
      "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/334179b3-196f-4a11-a7bf-f3d5e9e4ec4f/steps"
   },
   "capabilities": {
      "usability": [
         {
            "id": "UUID",
            "credentials": [
               {
                  "id": "UUID",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         },
         {
            "id": "UUID",
            "credentials": [
               {
                  "id": "UUID",
                  "category": "SELFIE"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         },
         {
            "id": "UUID",
            "credentials": [
               {
                  "id": "UUID",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         }
      ],
      "authentication": [
         {
            "id": "UUID",
            "validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/FACEMAP",
            "credentials": [
               {
                  "id": "UUID",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            },
            "data": {
               "type": "JUMIO_STANDARD"
            }
         }
      ]
   }
}
```
</details>