Skip to content

Remote Workflow

Remote lets you add biometric verification to a product without building your own interface for document capture, liveness checks, and other technologies. Your backend creates a session for a preconfigured Workflow, and your frontend redirects the user to the Biometric.Vision page. After verification is complete, the backend retrieves the final result through the API.

A Workflow defines the technologies the user must complete and their order. A session represents one specific run of this scenario and associates the user's actions with the verification results.

Integration boundaries

Three parties take part in the integration:

  • the client system backend creates sessions, stores the API KEY, receives webhooks, and requests results;
  • the client system frontend receives only the session_id or a ready-to-use URL from the backend and redirects the user;
  • Biometric.Vision displays the verification interface, runs the Workflow technologies, and stores the session results.

Do not expose the API KEY to the browser

Create sessions and retrieve results only on the backend. The API KEY grants access to the Workflow and its session results, so it must not appear in JavaScript code, public-page query parameters, mobile applications, or client-side logs.

Before starting the integration, configure a Workflow and store its API KEY in your backend secrets. Each verification then consists of five steps:

  1. Create a separate session for the user's attempt.
  2. Redirect the user to the Remote URL containing the returned session_id.
  3. Wait for the user to complete the Workflow technologies.
  4. Detect session completion through a webhook or the user's return to the redirect URL.
  5. Request the result from the backend and make a business decision based on the technology results.
sequenceDiagram
    title Client system interaction with the biometric service

    participant AIS as Client system
    participant BIO as Biometric.Vision (KYC)
    participant USER as End user

    note over AIS: Precondition:<br/>Workflow created in the dashboard

    note over AIS,BIO: Step 1 — Session creation
    AIS->>+BIO: POST /flows/session/create/<br/>{api_key}
    BIO-->>-AIS: {session_id, technologies}

    note over AIS,USER: Step 2 — Redirect
    AIS->>USER: Redirect → https://remote.biometric.vision/flow/{session_id}

    note over BIO,USER: Step 3 — Biometric verification
    USER->>+BIO: Open flow page
    BIO->>USER: Verification UI

    loop Technologies
        BIO->>BIO: Liveness Detection
        BIO->>BIO: Document Recognition
        BIO->>BIO: Face2Face
    end

    BIO-->>-USER: Verification completed

    note over AIS,USER: Step 4 — Result retrieval trigger

    alt Option A: Webhook (server-to-server)
        BIO-)AIS: Webhook: flow.end<br/>{session_id, success, data}
        note right of AIS: Asynchronous notification<br/>to the configured URL
    else Option B: User redirect
        BIO->>USER: Redirect → redirect_url?session_id=...
        USER->>AIS: Navigate to the client system page
        note right of AIS: Client system receives session_id<br/>from the URL parameters
    end

    note over AIS,BIO: Step 5 — Result retrieval
    AIS->>+BIO: GET /flows/session/result/<br/>?session_id=...&flow_api_key=...
    BIO-->>-AIS: JSON result<br/>{liveness_result, doc_recognition_result,<br/>face2face_result, edocument_result}

    note over AIS: Process verification results

1. Prepare the Workflow

Create a Workflow in the dashboard and enable the required technologies. Their order in the Workflow configuration determines the sequence of screens shown to the user.

The server-side integration requires the selected Workflow's API KEY. Keep the mapping between each business scenario and its Workflow key in backend configuration. Before redirecting the user, the backend creates a separate session and passes the returned session_id to the frontend. When creating it, you can pass technology metadata or associate the session with an existing person. This is especially important when different products or user categories require different verification sets.

One Workflow is one verification contract

Changing the technology set affects new sessions created for this Workflow. If the calling code expects specific result blocks, coordinate the Workflow change with the backend release.

2. Redirect the user

After creating the session, build the Remote URL:

https://remote.biometric.vision/flow/<session_id>

The frontend can navigate in the current tab or open a separate window. In mobile browsers, open the window directly from a user action handler; otherwise, the browser may block it as a popup.

The URL supports these parameters:

Parameter Type Required Description
redirect URL No Return address after the technologies are complete
locale string No Remote UI language
isMobile boolean No Force a device type
documentType string No Document type; available values depend on the Workflow
from_session_id string No Previous session UUID for a linked-session scenario

Always encode redirect as an independent query parameter:

const remoteUrl = new URL(`https://remote.biometric.vision/flow/${sessionId}`)
remoteUrl.searchParams.set('redirect', 'https://example.com/verification/complete')
remoteUrl.searchParams.set('locale', 'en')

window.location.assign(remoteUrl.toString())

Supported locale values: kz, en, ru, my, de, es, fa, fr, it, ja, kg, ko, pt.

The newCabinet and oldCabinet values of the redirect parameter are reserved for internal use and must not be used in client integrations.

A redirect is not a verification result

The user's return only indicates that a client-side navigation occurred. Do not pass a final status from the browser into trusted business logic. After the return, use the session_id to let your backend request the result from Biometric.Vision.

3. Detect session completion

There are two ways to trigger result retrieval:

  • the flow.end webhook is suitable for the primary server-to-server scenario and does not depend on the user keeping the tab open;
  • returning to the redirect URL is useful for updating the user interface, but does not by itself guarantee that the result is ready.

In practice, support both channels. The webhook updates the application state on the backend, while the return page periodically requests it. If the result is not ready, poll every 2–3 seconds and limit the total wait time.

The webhook handler must be idempotent: redelivery of the same event must not repeat a business operation. Associate the event with an application by session_id, persist the processing state, and respond only after the state has been stored reliably.