# Glossary

This section contains supplementary materials on terminology and key concepts of the NV Global platform and the KYC module.

***

## Glossary of Terms

### General Concepts

**KYC (Know Your Customer)** — a remote identity verification process using documents and photos, including anti-fraud checks and additional database validations. In the NV Global platform, this is a separate module with its own API and WebSDK.

**KYC Session** — a single user verification according to a defined scheme (for example, “passport + selfie with document”). All uploaded images, recognition results, errors, and statuses are tied to a `sessionId`.

**Scheme (schema, `schemaId`)** — a KYC verification workflow: a set of steps (document, selfie, Liveness, database checks, etc.) and settings (limits, anti-fraud, callbacks). In WebSDK you must specify `schemaId`.

**Scenario (`scenarioId`)** — deprecated name for a KYC scheme; use `schemaId` in new integrations.

**Client** — the end user (individual) of your service who is undergoing the KYC verification. Do not confuse with the integrator account on the NV Global platform.

***

### WebSDK and Frontend

**WebSDK** — a JavaScript library for embedding the KYC widget into a website or SPA (React etc.). Handles camera capture, image uploads, and communication with the KYC backend.

**KYC Widget** — a ready-made popup/modal where the user passes all KYC steps: photographing the document, taking a selfie, passing Liveness.

**`KYCWidget.setupKYC(...)`** — the main method for initializing the widget in the browser. Accepts a config (schemaId, clientKey, theme, callbacks) and opens the widget.

**`schemaId`** — the identifier of a verification scheme configured in the Dashboard. Required parameter for WebSDK.

**`clientKey` (WebSDK)** — a string up to 36 characters, defined on your side and passed encrypted into the widget. Used to associate KYC sessions with your users/applications and to filter them later in API.

**`clientUser`** — an optional string up to 36 characters previously used as an additional client identifier. Usually not required in new integrations; `clientKey` is enough.

**`closeCb`** — a callback triggered when the widget closes (success, error, or manual close).

**`successCb(payload)`** — callback triggered when the KYC scenario completes successfully. `payload` contains brief session info; detailed data must be retrieved through the REST API `/kyc/session/status`.

**Theme (`theme`)** — widget appearance: `light` or `dark`. Can be used to match your product’s branding.

***

### REST API and Backend

**REST API KYC** — a set of HTTP methods for creating sessions, uploading images, checking statuses, and retrieving session lists. Main methods:\
`/kyc/session/create`, `/kyc/process`, `/kyc/session/status`, `/kyc/sessions`, `/kyc/sessions/filter`.

**`/kyc/process`** — accepts images (document, selfie, etc.), performs recognition, and stores results in the session. Can operate in `sync` or `async` mode.

**`/kyc/session/status`** — retrieves the current session status and detailed results for each step (document, selfie, face matching, etc.).

**`/kyc/sessions`** — returns a list of all KYC sessions with brief info and nested results.

**`/kyc/sessions/filter`** — returns sessions filtered by status, errors, date range, `clientKey`, `schemaId`, database checks, and more.

**JWT Token** — a temporary access token returned by `/user/login`. Sent in the header `Authorization: Bearer ...` and required for all protected API methods.

**Permanent Token / Access Token** — long-term token created via `/token/create` and listed in `/tokens`. Convenient for server-side integrations and service tasks.

**Webhook (callback URL)** — your HTTP endpoint where the platform sends notifications when a KYC session is completed. The request body may be encrypted; decryption must be done on your side using a pre-shared key.

***

### Identifiers and Entities

**`sessionId`** — unique identifier of a KYC session. Used in all status and log API requests.

**`clientId`** — identifier of the client in the KYC system (may differ from your `userId`).

**`clientKey` (in API responses)** — the original value (up to 36 characters) that you supplied when encrypting on your backend. Used to link a KYC session with your user or application.

**Person List** — a logical collection of person records that can be used to compare new images: `/person`, `/persons`, `/person/list/*`.

**Person (person)** — a record in the person list containing data fields (`fields`), face data, and optionally vector embeddings.

**Data Source Group** — logical grouping of image/video sources. Managed via `/source/groups`, `/source/group/create`, `/source/group/update`, etc.

**Data Source** — a specific image source associated with a group (camera, integration, project). May have auto-addition settings and target features (`feature_check`).

***

### Liveness and Face Processing

**Liveness Check** — algorithms confirming that a live person is in front of the camera, not a photo, video, or synthetic image (deepfake). Uses analysis of frame sequences, micro-movements, textures, and artifacts.

**Active Liveness** — requires the user to perform actions (head turns, gaze direction changes, etc.), and the system verifies correctness.

**Passive Liveness** — requires only one or several frames without explicit actions, yet the system determines whether a real person is present.

**Face Matching** — evaluates similarity between two or more faces on different images (document ↔ selfie, selfie ↔ selfie, selfie with document ↔ document). In KYC results, this is shown as a separate block with a match score.

**Face Vector** — a numeric representation of a face image (embedding), used for fast similar-face search. In API referred to as `embeddings` and used, for example, in `/vector/search`.

**Fusion Vector** — combined vector representation of a person’s face across multiple images. Created using `/person/fusion` to improve search robustness.

***

### OCR, Documents, and Anti-Fraud

**OCR (Optical Character Recognition)** — recognition of text fields in documents (name, dates, document number, place of birth, etc.). The `ocr` block in KYC responses includes `title`, `value`, `conf`, and status.

**MRZ (Machine Readable Zone)** — machine-readable zone of a document (usually two or three lines at the bottom of passports/IDs) containing encrypted data and checksums.

**Anti-Fraud Checks** — detectors identifying document and image spoofing: screen photos (`display`), printed copies (`image printed`), edited images (`image edited`), face substitution, logical inconsistencies, and more.

**Black List** — list of undesirable persons or records; if matched, an error `[fraud] black list` is returned.

**KYC Error Codes** — standardized text codes (e.g., `[general] bad image`, `[document] text fields not visible`, `[fraud] mobile device`) explaining the cause of failure. Full list is available in a separate error reference.

***

### External Databases and Scoring

**External Checks** — additional queries to governmental, tax, judicial, sanction, and other data sources (bankruptcies, sanctions, debts, etc.). These checks may affect the final KYC session status.

**Financial Scoring** — risk assessment based on credit bureau data and additional sources (e.g., default scoring for short-term loans).

**KYC Session Status** — final verification status: `success`, `failed`, `idle`, or sometimes `suspicious`. `success` is possible only when all critical checks pass (document, face, Liveness, anti-fraud, external bases).