Session creation and metadata¶

Create a separate session for each verification attempt. The client system backend sends the selected Workflow API KEY, receives a single-use session_id, and passes it to Remote, Widget, or WebView.

Create a session¶

POST https://kyc.biometric.vision/api/flows/sessions/create/
Content-Type: application/json

Minimal request:

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/create/' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "<FLOW_API_KEY>"
  }'

A successful response returns HTTP 201 Created and contains:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LC", "DR2", "F2F"]
}

Do not reuse a session_id for multiple independent attempts or users.

Session metadata¶

The metadata object lets you pass data already known to the client system, prefill technology fields, provide a reference photo, or associate the session with an existing person. Metadata is supplied when creating the session and does not add technologies to the Workflow.

You can omit metadata if the Workflow settings do not require it. The exception is report sending: when enabled, you must supply extra.iin.

Supply the sections needed for your scenario. Do not use metadata or extra as arbitrary storage for custom fields: the session creation request has a fixed metadata schema.

Face2Face¶

If the client system already has a user photo, pass it in Base64 for comparison:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "face2face": {
      "photo1": "<BASE64_IMAGE>"
    }
  }
}

The supplied photo is used in a Workflow where Face2Face runs together with Liveness, E-Document, or Document Recognition.

Supply a plain Base64 string without the data:image/...;base64, prefix. An image URL or a storage file key cannot be used in the session creation request.

If the Workflow includes DSI or DSS, you cannot supply face2face.photo1: session creation will fail with HTTP 400. If person.alias is also supplied, the photo in face2face.photo1 takes precedence over the person's photo.

E-Document¶

E-Document metadata can prefill the IIN and phone number, prevent the user from changing them, and skip the data entry screen when all conditions are met.

To skip the data entry screen, provide both the IIN and phone number, set changeable: false for both fields, and set skip_input: true:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "edocument": {
      "iin": {
        "value": "<SUBJECT_IIN>",
        "changeable": false
      },
      "phone": {
        "value": "<SUBJECT_PHONE>",
        "changeable": false
      },
      "skip_input": true
    }
  }
}

The user proceeds directly to entering the OTP code from 1414. If you supply skip_input: true without meeting all the conditions above, the backend rejects session creation with HTTP 400.

To display the data entry screen with prefilled values, supply skip_input: false. For each supplied iin or phone object, provide a non-empty value; changeable: false prevents the user from editing that field, while true allows it.

The defaults in the table describe the form behavior documented in the integration guides. When these parameters are omitted, the backend does not insert changeable or edocument.skip_input into the stored metadata. Supply them explicitly in the request to control the scenario.

Digital Signature Identifier¶

The ds_identifier metadata prefills the signer's details:

To control editing, use objects with value and changeable, as in the example below. The string format is also supported, but it does not let you set changeable for the field. If changeable is omitted, the backend does not add it to the metadata; the true default in the table describes the form behavior.

The IIN must contain 12 digits. Supply the phone number as digits only, without +, spaces, or separators. To keep the data entry screen, explicitly set skip_input: false:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "ds_identifier": {
      "iin": {
        "value": "<SUBJECT_IIN>",
        "changeable": true
      },
      "phone": {
        "value": "<SUBJECT_PHONE>",
        "changeable": true
      },
      "skip_input": false
    }
  }
}

Uploading documents for signing and retrieving a CMS signature are separate Digital Signature operations and are not part of session creation.

GBDUL¶

The gbdul metadata lets you specify the organization's BIN in advance to retrieve data from the State Database of Legal Entities, including in a digital signature scenario for a legal entity.

To prefill the BIN and prevent the user from changing it, supply:

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "gbdul": {
      "bin": {
        "value": "<ORGANIZATION_BIN>",
        "changeable": false
      },
      "skip_input": false
    }
  }
}

If changeable is omitted or set to true, the user can enter or change the BIN. The backend does not insert an omitted changeable into the metadata. skip_input controls whether data entry is skipped; the actual GBDUL request runs during the technology step, not during session creation.

KZ Info¶

The kz_info.iin field supplies the user's known IIN. In the KZ Info scenario with an alternative data retrieval method, it is used when the technology request itself does not specify an IIN.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "kz_info": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

This IIN also takes precedence in the shared session IIN lookup used, depending on the scenario, by GBDFL, Address, RPN, and PPS. It is not automatically inserted into every field of every technology: for example, it does not replace edocument.iin.value or extra.iin, which is required for report sending.

ERD¶

The erd.iin field lets you supply an IIN for the ERD scenario. Metadata is returned to the verification interface when the session starts; the ERD verification request separately accepts the IIN in the personal_number field. Supplying metadata alone does not start verification.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "erd": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

The report generator can also use erd.iin as an IIN source if extra.iin and kz_info.iin are not supplied.

OTP¶

The otp.phone_number field specifies a phone number for the separate OTP technology. It does not configure E-Document OTP codes from 1414 or replace edocument.phone or ds_identifier.phone.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "otp": {
      "phone_number": "<SUBJECT_PHONE_WITH_PLUS>"
    }
  }
}

The code is sent when the OTP technology is called. The phone number in the send request takes precedence; if it is omitted, the backend uses metadata.otp.phone_number. If neither source contains a phone number, no code is sent and the OTP result receives the FAILED status with the reason phone_number_missing.

Additional metadata¶

The extra.iin field supplies the user's IIN for generating PDF reports, including signed Liveness and Face2Face reports.

If the Send signed report setting is enabled in the Workflow configuration, a non-empty metadata.extra.iin is required when creating the session. An IIN in another metadata section does not satisfy this check.

When generating a report, extra.iin is used first. If it is absent, the generator can also obtain the IIN from other metadata or technology results. Whether extra.iin specifically is required at creation therefore depends on the Send signed report setting.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "extra": {
      "iin": "<SUBJECT_IIN>"
    }
  }
}

Person¶

The metadata.person.alias field lets you find an existing person or save an alias when collecting data for a new person. Supply a valid, non-expired alias of an existing person or a new unique identifier from the client system. To work with persons, the Workflow must include the PS technology with the corresponding features configured.

{
  "api_key": "<FLOW_API_KEY>",
  "metadata": {
    "person": {
      "alias": "<PERSON_ALIAS>"
    }
  }
}

You do not need to pass the alias type separately. The system processes the value as follows:

• when the session starts, the system searches for a person by a non-expired alias value within the organization that owns the Workflow; expired aliases are excluded from the search;
• after the session finishes successfully, if person collection is enabled, the system asynchronously creates or updates a person using the collected data, including the supplied alias;
• if no matching person exists, a new one is created; a new alias from metadata is saved with the custom type. The session creation request itself does not create a person.

Result reuse is enabled by the Skip technology with existing Document result setting and depends on whether the stored results are eligible, including validity period restrictions. Using the person's photo for Face2Face is enabled by the Use person's photo for F2F comparison setting; an expired or deleted photo is not used as the default photo. If face2face.photo1 is supplied, the person's photo is not added for comparison.

See Persons for details on person collection and data reuse.

Metadata validation and errors¶

When creating a session, the backend validates the request structure and additional conditions for using metadata. Successful session creation does not mean that government services have verified the data or that the technologies have been completed.

The edocument.skip_input conditions do not automatically apply to ds_identifier or gbdul: session creation does not perform an equivalent check of the combination of skip_input, value, and changeable for these sections. For kz_info.iin, erd.iin, gbdul.bin.value, extra.iin, and otp.phone_number, session creation also does not separately validate the value format beyond checking the field type. Supply valid data for the corresponding technology.

Violating the additional conditions returns HTTP 400 with the code invalid_flow_session_metadata. For example, if you set edocument.skip_input: true but allow the IIN to be edited:

{
  "message": "Invalid metadata for session",
  "detail": "Value error, Both IIN and phone must have values and be non-changeable when skip_input is True",
  "code": "invalid_flow_session_metadata"
}

If you omit extra.iin while report sending is enabled:

{
  "message": "Invalid metadata for session",
  "detail": "Value error, IIN is required in extra metadata when report should be sent",
  "code": "invalid_flow_session_metadata"
}

Request structure and field type errors may be returned separately with HTTP 422. Handle errors using the HTTP status and code, when present; detail explains the specific cause.

Metadata in webhooks¶

Webhooks contain the session's stored metadata object. It may differ from the original request: fields with null values are excluded when saving, and some defaults are added according to the schema.

In particular, after the photo is uploaded, face2face.photo1 is replaced with the file's storage key. In a webhook, this field contains the key, not the original Base64 string or a ready-to-use image URL. Do not use it as a download URL.

Complete request¶

The following cURL example supplies person and E-Document metadata together. The examples in the other sections above are intended for their respective Workflow scenarios; you do not need to combine all sections in a single request. Replace the values in angle brackets with your own data before sending:

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/create/' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "<FLOW_API_KEY>",
    "metadata": {
      "person": {
        "alias": "<PERSON_ALIAS>"
      },
      "edocument": {
        "iin": {
          "value": "<SUBJECT_IIN>",
          "changeable": false
        },
        "phone": {
          "value": "<SUBJECT_PHONE>",
          "changeable": false
        },
        "skip_input": true
      }
    }
  }'

After receiving the session_id, pass it to the selected verification interface. Track session completion through Webhooks, and retrieve the final data through the results API.