Silent Revalidation

MarkdownChatGPTClaude

Uses the Silent Revalidation engine, which analyzes the user's behavioral context within Unico's network effect and delivers the confidence signal for the current transaction. In other words, we deliver the confidence level of being the expected user in the transaction.

Prerequisites

Requires unico-webframe 3.28.2 or later, and a migrated integration — non-migrated tenants get a permanent rejection (see startSilentValidation errors).

Two ways to send this data on the Web SDK

Use initializeSDK + startSilentValidation when no camera is ever opened on this screen. Use setSilentInfo, documented in Monitoring Data Collection, when prepareSelfieCamera/prepareDocumentCamera already runs here. Both can be used on the same page.

startSilentValidation parameters

Parameter	Type	Required	Description
externalUserId	String	✅	User identifier in your system. Automatically hashed with SHA-256 before transmission, never sent in plain text.
useCase	String	—	Identifier for the flow or context running (e.g., "login", "password_recovery"). Transmitted as plain text.

Starting a Silent Revalidation

Step 1 — Implement initializeSDK

Call initializeSDK on the instance built by UnicoCheckBuilder, passing your UnicoConfig. It starts the device data collection in the background without opening a camera.

Required before startSilentValidation

If initializeSDK (or prepareSelfieCamera/prepareDocumentCamera) hasn't run on this page yet, startSilentValidation does not reject — it resolves without sending any data, and the validation silently does nothing. Always call initializeSDK first.

Call it as early as possible

initializeSDK must be called as early as possible on the page — ideally before the user is identified. Calling it later reduces background processing time and increases the chance of inconclusive authentication responses.

import { UnicoCheckBuilder, UnicoConfig, SDKEnvironmentTypes } from "unico-webframe";

const config = new UnicoConfig()
  .setHostname("<YOUR_HOSTNAME>")
  .setHostKey("<YOUR_HOST_KEY>");

const unicoCamera = new UnicoCheckBuilder()
  .setEnvironment(SDKEnvironmentTypes.UAT)
  .build();

unicoCamera.initializeSDK(config);

Step 2 — Implement startSilentValidation

After initializeSDK, associate the collection already in progress with the identified user by calling startSilentValidation with the externalUserId.

unicoCamera
  .startSilentValidation("external_user_id", "login")
  .then(() => {
    // Resolves even if initializeSDK never ran on this page — in that
    // case, no data was sent. Always call initializeSDK first.
  })
  .catch((error) => {
    // Rejects once initializeSDK has run — e.g. if the device data
    // collection isn't ready yet. See startSilentValidation errors below.
  });

See startSilentValidation errors for the full list of rejection codes.

If the validation happens at the start of the flow, for example at login, wait for the resolved promise before moving on to Step 3.

Step 3 — Create the process and authenticate

With validation in progress, create the verification process to complete the authentication. See API Reference ▸ API ▸ Create Process.

Include the same externalUserId sent in startSilentValidation from Step 2 in the request body — this is what allows the backend to correlate the process creation with the validation already in progress.

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "externalUserId": "external_user_id"
  }'

The response includes the silentAuth.result field with the authentication result:

{
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 3,
    "silentAuth": {
        "result": "yes"
    }
}

Field	Type	Description
silentAuth.result	string	yes or no — see possible values below.

silentAuth.result — possible values

Value	Meaning
yes	Authentication approved, user recognized with sufficient confidence, no additional capture needed.
no	Insufficient data to approve silently. Authenticating via biometrics (selfie) or another alternative method is recommended.