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).
Last updated