# @seontechnologies/seon-id-verification

> An advanced SDK for natural person identification through document scanning, facial recognition, designed for secure and efficient user verification.

Latest version **2.2.0** (published 2026-11-19) · SEE LICENSE IN https://seon.io/resources/legal-and-security/legal/#terms-of-service license · 0 weekly downloads

## Install

```sh
npm install @seontechnologies/seon-id-verification
pnpm add @seontechnologies/seon-id-verification
yarn add @seontechnologies/seon-id-verification
bun add @seontechnologies/seon-id-verification
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2026-11-19 |
| First published | 2024-05-16 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN https://seon.io/resources/legal-and-security/legal/#terms-of-service |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 1 |
| Unpacked size | 53.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | SEON Technologies |
| Maintainers | balintdali, mate.kungl, gzsamboki-seon, zoltan.toth, zsomborbarabas, robert.orsulics, seontechnologies-publisher |
| Keywords | identification SDK, document scanning, facial recognition, user verification, KYC, security, identity verification, anti-fraud, biometric authentication, personal identification, authentication SDK, SEON, compliance |

## Links

- npm: https://www.npmjs.com/package/@seontechnologies/seon-id-verification
- npm.io page: https://npm.io/package/@seontechnologies/seon-id-verification

## Dependencies (1)

- [eventemitter3](https://npm.io/package/eventemitter3.md) ^5.0.1

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 2.2.0 (latest) — 2026-11-19
- 2.0.0-beta.3 (beta) — 2025-08-13
- 0.1.8-experimental.12 (experimental) — 2024-11-12
- 2.1.0 — 2025-11-04
- 2.0.0 — 2025-08-19
- 2.0.0-beta.2 — 2025-08-01
- 1.4.0 — 2025-07-14
- 1.3.0 — 2025-06-10
- 1.3.0-beta.1 — 2025-06-10
- 1.2.0 — 2025-05-12
- 1.1.0 — 2025-03-25
- 1.0.0 — 2025-03-11
- 0.1.10 — 2025-02-14
- 0.1.10-beta.3 — 2025-02-13
- 0.1.10-beta.2 — 2025-02-13
- … 24 more at https://npm.io/package/@seontechnologies/seon-id-verification/versions

## README

# SEON ID Verification SDK for Web

Our SDK offers a comprehensive suite of features designed to cater to a wide range of document validation and recognition needs. Below is a breakdown of the key features available:

## 💡 Features

**🤖 Document Validation and Content Verification**

- **Document Type Recognition:** Automatically identifies the type of document presented, whether it's an ID card, passport, driver's license, or any other official document.
- **Content Validation:** Extracts and validates the textual information from documents, ensuring the data's integrity and accuracy. This includes checking the validity of names, dates, document numbers, and other critical information.
- **Forgery Detection:** Utilizes advanced algorithms to detect and alert on any signs of tampering or forgery within the document, ensuring the authenticity of the presented documents.
- **Proof of Address Flow:** Verifies the provided proof of address documents, by extracting and validating the textual information to ensure the address's accuracy and authenticity.

**👨 Facial Recognition**

- **Identity Verification:** Compares the facial image on the document with the person presenting it to ensure they are the same individual, enhancing security and preventing identity fraud.
- **Liveness Detection:** Detects real-time presence and distinguishes between a live person and a spoofing attempt, such as using photographs or videos, to ensure that the verification process is secure.

<!-- **✌️ Hand Gesture Recognition**

- **Gesture Control:** Enables interaction with devices or applications through simple hand gestures, making the user interface more intuitive and accessible.
- **Complex Gesture Recognition:** Our SDK can recognize complex hand gestures, offering sophisticated controls for applications requiring nuanced interactions.
- **Real-time Processing:** Processes and recognizes hand gestures in real-time, ensuring a seamless and responsive user experience. -->

---

## 🚀 Installation

Install the SDK in your project:

```bash
npm install @seontechnologies/seon-id-verification
```

---

## 🛠️ Migration Guide: v1.x.x → v2.0.0

To upgrade to v2.0.0, run:

```bash
npm install @seontechnologies/seon-id-verification@^2.0.0
```

### 1. Style Import No Longer Needed

**v1.x.x:**

```js
import '@seontechnologies/seon-id-verification/styles';
```

**v2.0.0:**  
This import is no longer required. All necessary styles are included automatically.

### 2. Initialization Changes

- **v1.x.x:**
  You could use `SeonIdVerification.initialize(config)` and then call `SeonIdVerification.start()`.
- **v2.0.0:**
  The `initialize` method is no longer required. You can pass the configuration directly to `start`:

```js
SeonIdVerification.start({
  /* configuration options */
});
```

> **Note:**
>
> - `initialize` is still available for backward compatibility, but is not required if you pass the configuration directly to `start`.
> - `initialize` is no longer async, so you do not need to use `await` or `.then()` with it.

### 3. Configuration Object Changes

Key differences in v2.0.0:

- `licenseKey`, `referenceId`, `type`, and `templateId` are now top-level properties (not nested under `SEONCustomerData`).
- The `SEONCustomerData` object is now renamed to `customerData` and contains only user/customer-specific fields. (such as `email`, `phoneNumber`, `name`, etc.).

**Before (v1.x.x):**

```js
SeonIdVerification.initialize({
  baseUrl: 'https://idv-eu.seon.io',
  SEONCustomerData: {
    licenseKey: 'YOUR_LICENSE_KEY',
    referenceId: 'YOUR_REFERENCE_ID',
    email: 'user@example.com'
  }
});
```

**After (v2.0.0):**

```js
SeonIdVerification.start({
  baseUrl: 'https://idv-eu.seon.io',
  licenseKey: 'YOUR_LICENSE_KEY',
  referenceId: 'YOUR_REFERENCE_ID',
  customerData: {
    email: 'user@example.com'
  }
});
```

See the updated `FlowConfiguration` and `customerData` sections below for details.

### 4. Event Name Changes

- `start` → `started`
- `completedSuccess`, `completedPending`, `completedFailed` → now all trigger the `completed` event with an additional completion type/status argument.
- New events:
  - `opened`: Flow UI opened
  - `closed`: Flow UI closed

**Example:**

```js
SeonIdVerification.on('completed', (status) => {
  // status: 'success' | 'pending' | 'failed', or undefined when the result isn't known yet (async, or polling ran out)
});
```

---

## ⚡️ Quick Start

### Basic Initialization

```js
import { SeonIdVerification } from '@seontechnologies/seon-id-verification';

SeonIdVerification.initialize({
  baseUrl: 'https://idv-eu.seon.io', // or https://idv-us.seon.io
  licenseKey: 'YOUR_LICENSE_KEY',
  referenceId: 'YOUR_REFERENCE_ID',
  language: 'en',
  templateId: 'YOUR_TEMPLATE_ID',
  customerData: {...},
  // ...other configuration options
});

// Start the verification flow
SeonIdVerification.start();
```

You can also omit the `initialize` call and pass the configuration object directly to the `start` method.

### Rendering Modes

The SDK supports several rendering modes:

- **fullscreen**: Open the flow in fullscreen mode (default)
- **inline**: Embed the flow in a specific container (`containerId` required)
- **popup**: Open the flow in a popup window

**Example (inline):**

```js
SeonIdVerification.initialize({
  ...config,
  renderingMode: 'inline',
  containerId: 'idv-container',
});
```

---

## 🛠️ Configuration Reference

### `FlowConfiguration` Reference

The main configuration object (`FlowConfiguration`) supports:

- `baseUrl` (required): API base URL
- `licenseKey` (required): Your SEON IDV license key
- `referenceId` (required): Unique reference for the verification flow
- `language`: UI language (e.g., 'en')
- `type`: Verification type (e.g., 'registration', 'login')
- `templateId`: Template identifier
- `customerData`: Additional customer/user info
- `theme`: Theme configuration
- `alwaysTransferFromDesktop`: Force desktop to mobile transfering
- `renderingMode`: 'inline' | 'fullscreen' | 'popup' (default: 'fullscreen')
- `containerId`: DOM element ID to mount the flow (required if `renderingMode` is 'inline')

See TypeScript types in `src/types/FlowConfiguration.ts` for advanced options.

### `customerData` Reference

The `customerData` object allows you to pass additional user/customer information to the verification flow. This can improve the verification experience and is often required for compliance.

- `email`: User's email address
- `phoneNumber`: User's phone number
- `name`: User's full name
- `userId`: Internal user identifier
- `countryISOCode`: ISO country code, e.g., 'US'
- `address`: User's address
- `dateOfBirth`: Object with user's date of birth
  - `day`: Day of birth (number)
  - `month`: Month of birth (number)
  - `year`: Year of birth (number)
- `postalCode`: Postal code
- `additionalProperties`: Object with extra key-value pairs

**Example:**

```js
customerData: {
  email: 'user@example.com',
  phoneNumber: '+1234567890',
  name: 'John Doe',
  userId: 'user-123',
  countryISOCode: 'US',
  address: '123 Main St, New York, NY',
  dateOfBirth: {
    day: 1,
    month: 1,
    year: 1990
  },
  postalCode: '10001',
  additionalProperties: {
    loyaltyId: 'abc-123',
    customField: 'value'
  }
}
```

---

## 📣 Events

You can listen for key events during the verification flow:

- `opened`: Flow UI opened
- `closed`: Flow UI closed
- `started`: Verification started
- `submitted`: User finished submitting; only the Done tap is left (with status)
- `completed`: Verification completed (with status)
- `cancelled`: Flow cancelled by user
- `error`: Error occurred (with error code)

**About `submitted`:**

- Fires when the user has finished submitting and only the Done tap is left. It does not close the flow; `completed` still follows on Done.
- It carries the same value `completed` will carry.
- It does not guarantee that every upload succeeded. It fires once the upload attempts have finished, including failed ones.
- It can fire more than once for the same run (page reload, returning user), so handlers should be idempotent.

**Popup mode:** if the user closes the popup after `submitted`, the SDK emits `completed` with the value from `submitted` (instead of `cancelled`), then `closed`. If the popup is closed before `submitted`, it still emits `cancelled`, then `closed`. Done followed by closing the window never emits a second `completed`.

**Example:**

```js
SeonIdVerification.on('submitted', (status) => {
  // User is done; only the Done tap is left
  // status: 'success' | 'pending' | 'failed', or undefined when the result isn't known yet (async, or polling ran out)
});
SeonIdVerification.on('completed', (status) => {
  // Handle completion
  // status: 'success' | 'pending' | 'failed', or undefined when the result isn't known yet (async, or polling ran out)
});
SeonIdVerification.on('error', (errorCode) => {
  // Handle error
});
```

## 🖍️ Styling

You can customize the appearance of the verification UI using the `theme` property in your `FlowConfiguration` object.

### `theme` Reference

The `theme` object supports the following fields:

- `light`: Light mode theme overrides
  - `baseTextOnLight`: Text color on light backgrounds
  - `baseTextOnDark`: Text color on dark backgrounds
  - `baseAccent`: Accent color
  - `baseOnAccent`: Text color on accent backgrounds
  - `logoUrl`: URL for custom logo in light mode
- `dark`: Dark mode theme overrides
  - `baseTextOnLight`: Text color on light backgrounds
  - `baseTextOnDark`: Text color on dark backgrounds
  - `baseAccent`: Accent color
  - `baseOnAccent`: Text color on accent backgrounds
  - `logoUrl`: URL for custom logo in dark mode
- `fontFamily`: Font family for the UI
- `fontUrl`: URL for the custom font
- `fontWeight`: Font weights to use

**Notes:**

- All color values should be valid CSS color strings (hex, rgb, hsl, etc.).
- The theme is applied within the iframe, so parent app CSS does not affect the verification UI.
- All properties are optional.
- For advanced branding, contact SEON support.

**Example:**

```js
{
  theme: {
    light: {
      baseTextOnLight: '#3e5a93',
      baseTextOnDark: 'rgb(255, 255, 255)',
      baseAccent: '#467024',
      baseOnAccent: 'rgb(255, 255, 255)',
      logoUrl: 'https://example.com/light-logo.png',
    },
    dark: {
      baseTextOnLight: '#dbfff1',
      baseTextOnDark: 'rgb(255, 255, 255)',
      baseAccent: 'hsl(52 86% 46% / 1)',
      baseOnAccent: '#11361c',
      logoUrl: 'https://example.com/dark-logo.png',
    },
    fontFamily: 'cursive',
    fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
    fontWeight: '400 500 600 700 800 900',
  }
}
```

**Notes:**

- All color values should be valid CSS color strings (hex, rgb, hsl, etc.).
- The theme is applied within the iframe, so parent app CSS does not affect the verification UI.
- For advanced branding, you may request a custom template or contact SEON support.

---

## 💻 Usage Example

![react](https://img.shields.io/badge/javascript-f0db4f?style=for-the-badge&logo=javascript&logoColor=white)

```javascript
import { SeonIdVerification } from '@seontechnologies/seon-id-verification';

SeonIdVerification.on('opened', () => {
  console.log('SDK opened');
});
SeonIdVerification.on('closed', () => {
  console.log('SDK closed');
});
SeonIdVerification.on('started', () => {
  console.log('Flow started');
});
SeonIdVerification.on('error', (err) => {
  console.log('Error code: ', err);
});
SeonIdVerification.on('submitted', (type) => {
  console.log('Flow submitted with type: ', type);
});
SeonIdVerification.on('completed', (type) => {
  console.log('Flow completed with type: ', type);
});

SeonIdVerification.initialize({
  baseUrl: 'YOUR_BASE_URL',
  customerData: {
    licenseKey: 'YOUR_LICENSE_KEY',
    referenceId: 'YOUR_REFERENCE_ID',
    type: 'id-verification',
    email: 'test-elek@seon.io',
    phoneNumber: '+36301234567',
    name: 'Test Elek',
    userId: 'test-elek',
    countryISOCode: 'us',
    address: '132, My Street, New York 12',
    templateId: 'YOUR_TEMPLATE_ID',
    dateOfBirth: {
      day: 1,
      month: 1,
      year: 2000,
    },
    postalCode: '12345',
    additionalProperties: {
      additionalProp1: 'value1',
      additionalProp2: 'value2',
      additionalProp3: 'value3',
    },
  },
  language: 'en',
});
SeonIdVerification.start();
```

## 🕸️ Browser Compatibility

| Browser             | Version |
| ------------------- | ------- |
| Chrome              | 96      |
| Safari              | 15      |
| Firefox             | 79      |
| Opera               | 82      |
| iOS Safari          | 15      |
| Android Browser     | 81      |
| Chrome for android  | 96      |
| Firefox for android | 79      |

## 📝 License Terms

The detailed license terms can be viewed at the following link: ®️[SEON License Terms](https://seon.io/resources/legal-and-security/legal/#terms-of-service).

---
_Source: https://npm.io/package/@seontechnologies/seon-id-verification · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
