Retrieving results¶

This page describes requests, common fields, and response handling rules. Fields and examples for individual technologies are available through the results index and the section menu.

Request results from the client system backend. You can track completion through the flow.end webhook; after an interface signal, also verify the result with a server-side request. The response contains the current session state and available results, including intermediate results.

Full result¶

POST https://kyc.biometric.vision/api/flows/sessions/result/

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

Lightweight result¶

POST https://kyc.biometric.vision/api/flows/sessions/result/light/

curl --request POST \
  --url 'https://kyc.biometric.vision/api/flows/sessions/result/light/' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --compressed \
  --data '{
    "session_id": "<SESSION_ID>",
    "api_key": "<FLOW_API_KEY>"
  }'

Light is a response variant, not an HTTP method. Both endpoints above use POST with a JSON body. These routes do not support query parameters for retrieving results.

Compatibility with legacy routes¶

The following legacy API routes are also available in the current code. They use the same output schemas, null exclusion rules, session ownership checks, and rate limit.

For these GET methods, the Workflow key is named flow_api_key, not api_key. POST is not defined for the legacy light route. For new integrations, use the POST routes in the examples above.

Authorization and parameters¶

Authorization uses api_key in the request body: the key identifies the Workflow, and session_id must belong to that Workflow. No additional Authorization or X-API-Key is required for these two methods.

HTTP responses¶

Large responses support gzip compression (Accept-Encoding: gzip; the examples request it with --compressed).

Field interpretation rules¶

The tables specify the type of the value actually transmitted. If a field allows a missing value, the API excludes it from JSON; this also applies to fields in nested schemas. Therefore, result: false, a missing result, and a missing technology block are different states.

• A required field is present when its parent object is successfully serialized.
• When a value is available means the field allows null in the source data, but the key is excluded from the response in that case. An empty string, false, 0, {}, and [] are not removed merely because they are empty or falsy.
• Removing null from schema fields does not mean cleaning arbitrary JSON. Within dynamic dictionaries and arrays, null may remain and differs from a missing key.
• A missing block does not establish the cause: verification may not have started, a record may not have been created, or the technology may not be part of the session. A block may appear before verification is complete, sometimes as {}.
• A UUID is transmitted as a string. IINs, BINs, document numbers, and phone numbers are strings: preserve leading zeros.
• number is a JSON number; Liveness, Face2Face, and NPCK prediction scores are transmitted as strings, not numbers.

A nested field is required only when its parent object is present. Dynamic JSON has no fixed set of keys unless explicitly stated.

Response structure¶

The root response object.

Presence requirements are specified separately for each field. The technology result fields listed below are also fields of the root object.

Technology results index¶

Individual blocks have type object and are excluded if the corresponding record does not exist. The three arrays at the end of the table are returned as [] if there are no records. Block presence depends on stored results, not only on the current technologies list.

The codes in the table are defaults in the project configuration; a deployed service may override them. Different variants of a technology may share a block. This response has no separate persons_result, array of all Liveness attempts, or results for each Liveness model. Session creation metadata, session context, and validity period are also outside this contract.

Technologies¶

Parent: technologies[].

The list reflects the current Workflow configuration, not an immutable snapshot taken at session creation. Disabled technologies are excluded.

Device information¶

Parent: request_sessions[].

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Identical sets of all the listed values are merged; completely empty records are excluded. This is neither a request history nor an attempt count. Do not interpret the item order as the order of visits.

Session status, outcome, and errors¶

The session status, boolean outcome, and individual check data answer different questions.

Field: status.

The spelling and case of allowed values are shown exactly.

flow_session_result returns false for every status except FINISHED and APPROVED. For these two statuses, the related Workflow technology results are also checked, except for the persons technology:

• a missing expected result relation produces false;
• a recorded failure reason or an explicit result: false in the selected result produces false;
• a missing result value does not by itself mean false; for a relation with multiple records, having no records is also not an independent negative condition in this calculation.

The outcome check uses Workflow technologies without the same active-only filter applied to technologies. Therefore, you cannot reconstruct flow_session_result by simply applying a logical AND to all visible result values. APPROVED also does not guarantee flow_session_result: true.

A technology's result reflects its rules and configuration. For example, AML may be accepted despite a match if rejection on a match is disabled; some checks may accept service unavailability. A failure reason may still be retained, leaving the aggregate outcome negative. KZ Info and ERD have no separate result at all: check the retrieval status, data, and error.

Failure reasons¶

Parents: *.failure_reason (except Address) and flow_session_failure_reasons[].

Address is an exception: address_result.failure_reason is a UUID string; see the Address section.

Values of failure_reason.type.

flow_session_failure_reasons[].type is a free-form string that combines technology categories with session categories (OTHER, EXPIRED).

The aggregate error array contains session errors, followed by errors from selected technology results in Workflow order. It is not a complete retry history; items have no technology code, error UUID, or timestamp. Duplicates are possible. Use the technology's own block to associate a reason with a check.

Examples of diagnostic combinations are provided in the failure reasons reference. Do not make a decision based only on detail text. result: false does not guarantee that failure_reason is present, and result: true does not guarantee that no error is present.

Incomplete sessions and retries¶

Retrieving results does not require a terminal status. During verification, partial data, empty arrays, and blocks without result may be available; flow_session_result: false at this point does not mean a final rejection. Statuses and dates may change in the next response.

For the aggregate outcome and error array, relations with multiple records are evaluated using one selected record, even when the public block returns an array. For IP checks and questionnaires, do not assume this selects the most recent attempt.

E-Document, Document Recognition v2, and PPS results may be copied from a previous session when person data reuse is configured. This is indicated by status: "COPIED" and source_session. It is not a new retrieval of a document or photo. Copying depends on validity period settings and checks of the source result's eligibility.

Files in full and light responses¶

Base64 contains the file bytes without a data:...;base64, prefix. For document_pdf, these are PDF bytes; image types and extensions cannot be determined from field names alone. Light preserves field names and structure, replacing values with URL strings only in the locations listed.

A file field is available when a file is associated with the result. If no file exists, the field is excluded; the legacy Document Recognition images dictionary may remain {}, and the v2 image array may remain []. Some files appear later than other data or are not generated in the selected scenario.

URLs are generated by the storage system; S3 uses signed access. The expiry time is not included in the response or fixed by this API. Do not save a URL as a permanent address: request a fresh result when needed. A URL does not guarantee that the file has not been deleted; the full response additionally requires successful file reads to generate Base64.

Registry request statuses¶

This table explains common status meanings. Each technology section specifies its own allowed set: not all technologies use every value.

Values of the status field for Address, GBDFL, GBDUL, PPS, and RPN.

Result enum values preserve the case shown in the table.

Successful result¶

Below are two complete responses for the same illustrative Liveness session. Additional metrics were not generated, so their fields are absent. The Base64 example uses a small synthetic PNG rather than a person's photo; the light URL is fictional.

Full response¶

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "FINISHED",
  "validated_at": "2026-09-01T10:00:00Z",
  "finished_at": "2026-09-01T10:01:00Z",
  "flow_session_result": true,
  "technologies": [
    {
      "code": "LDD",
      "name": "Liveness check",
      "description": "Face verification by changing distance"
    }
  ],
  "liveness_result": {
    "result": true,
    "prediction": "0.9800",
    "face_photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aWQAAAABJRU5ErkJggg=="
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Light response¶

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "FINISHED",
  "validated_at": "2026-09-01T10:00:00Z",
  "finished_at": "2026-09-01T10:01:00Z",
  "flow_session_result": true,
  "technologies": [
    {
      "code": "LDD",
      "name": "Liveness check",
      "description": "Face verification by changing distance"
    }
  ],
  "liveness_result": {
    "result": true,
    "prediction": "0.9800",
    "face_photo": "https://files.example.invalid/liveness/face.png?signature=EXAMPLE"
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Unsuccessful result¶

A complete response with a negative Liveness result. A 200 response from the method returning this JSON does not override flow_session_result: false.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "FAILED",
  "flow_session_result": false,
  "technologies": [
    {
      "code": "LDD",
      "name": "Liveness check",
      "description": "Face verification by changing distance"
    }
  ],
  "liveness_result": {
    "result": false,
    "failure_reason": {
      "type": "CALC_RESULT",
      "detail": "Low overall prediction"
    }
  },
  "request_sessions": [],
  "flow_session_failure_reasons": [
    {
      "type": "CALC_RESULT",
      "detail": "Low overall prediction"
    }
  ],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Intermediate response¶

A complete response before verification begins. The absence of the Liveness block here is expected.

{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "CREATED",
  "flow_session_result": false,
  "technologies": [
    {
      "code": "LDD",
      "name": "Liveness check",
      "description": "Face verification by changing distance"
    }
  ],
  "request_sessions": [],
  "flow_session_failure_reasons": [],
  "ip_check_results": [],
  "questionnaire_results": [],
  "otp_results": []
}

Result fragments¶

The JSON examples on technology pages are fragments of the root object, not complete responses. All numbers and names are illustrative; the examples are not intended to be sent to APIs that start checks.

A copied v2 recognition result in light format; dynamic text may contain null:

• document_recognition_v2_result: JSON example.

E-Document without files and with reused dates:

• edocument_result: JSON example.

An accepted GBDUL error and an Address error in a different format:

• gbdul_result: JSON example.
• address_result: JSON example.

The PPS photo remains a URL in both variants, and a file question may have no value:

• pps_result: JSON example.
• questionnaire_results: JSON example.

Retrieved empty KZ Info and ERD responses, and completed OTP verification:

• kz_info_result: JSON example.
• erd_result: JSON example.
• otp_results: JSON example.

Other document and face comparison formats (light response fragments; these blocks do not have to occur in the same session):

• face2face_result: JSON example.
• npck_result: JSON example.
• edocument_child_result: JSON example.
• mxdocument_result: JSON example.
• mrz_result: JSON example.

{
  "document_recognition_result": {
    "result": true,
    "first_name": "EXAMPLE",
    "last_name": "SAMPLE",
    "images": {}
  }
}

Waiting for a registry response and retrieved information (dynamic JSON is deliberately not presented as a universal schema):

• gbdfl_result: JSON example.
• rpn_result: JSON example.
• tunduk_result: JSON example.
• aml_result: JSON example.

Identification, signing, and IP checks:

• ds_identifier_result, ds_signer_result: JSON example.
• ip_check_results: JSON example.

Process the response¶

1. Check the HTTP status and associate the response id with your application and the original session_id.
2. Consider the session status, flow_session_result, and the state of the relevant technologies. Do not treat an intermediate false as a final rejection.
3. Distinguish missing fields, empty containers, empty strings, and explicit negative values.
4. For files, use the full/light table; do not try to decode every file field as Base64.
5. When requesting results again, account for updates to the selected record and newly available results. Do not use this response as a complete attempt history.