---
updatedAt: 2026-07-07T17:42:21.000Z
agentTools:
projectIndex: https://docs.bynn.com/llms.txt
---
# Get next verification step
Checks next step for session in verification flow, this shall be polled after each completed action to check next step.
Websocket Part:
1. Connect to websocket\_url
2. Send subscribe message, example:
```json json
{
"command": "subscribe",
"identifier": "{\"channel\":\"BynnKycChannel\"}"
}
```
3. After subscribe message you will automaticly get the preflight payload, then you will get it on all event changes.\
Example:
```json json
{
"identifier": "{\"channel\":\"BynnKycChannel\"}",
"message": {
"extra_data": {},
"session": "cTMKciZaG4iv7FfRZk1nxRW1",
"session_id": "cTMKciZaG4iv7FfRZk1nxRW1",
"entity_id_state": "none_received",
"entity_id_document_type": "unknown",
"requirement": {
"requirement_type": "identity_document",
"status": "awaiting_receipt",
"flow_order": 100
},
"screen": {
"show": "scan_id_document_front_screen",
"parameters": {
"camera": "back",
"camera_quality": "ultra",
"allow_manual_upload": false,
"multipage": false,
"title": null,
"text": null
}
}
}
}
```
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "BYNN API",
"description": "The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Please use your **Private API Key** that looks like this `private_Nv7UpwQbSmWtUTiSWfw1bdHm` as the username and password in HTTP basic auth.",
"termsOfService": "https://bynn.com/terms",
"contact": {
"name": "BYNN Development Team",
"email": "hello@bynn.com",
"url": "https://docs.bynn.com"
},
"license": {
"name": "BYNN Documentation",
"url": "https://docs.bynn.com"
},
"version": "1.0"
},
"tags": [
{
"name": "sessions",
"description": "Operations about sessions"
}
],
"paths": {
"/sessions/{session_id}/preflight": {
"get": {
"summary": "Get next verification step",
"description": "Checks next step for session in verification flow, this shall be polled after each completed action to check next step.",
"parameters": [
{
"in": "path",
"name": "session_id",
"description": "Unique session token to do preflight request for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Get next verification step",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bynn_V1_Entities_Preflight"
}
}
}
},
"404": {
"description": "Invalid session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bynn_V1_Entities_Error"
}
}
}
},
"410": {
"description": "Session canceled or consent not given",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bynn_V1_Entities_Error"
}
}
}
},
"451": {
"description": "No consent given, please ask user for consent to process and store PII data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Bynn_V1_Entities_Error"
}
}
}
}
},
"tags": [
"sessions"
],
"operationId": "getSessionsSessionIdPreflight"
}
}
},
"servers": [
{
"url": "//api.bynn.com/v1"
}
],
"components": {
"schemas": {
"Bynn_V1_Entities_Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "validation_error",
"description": "Type of error"
},
"message": {
"type": "string",
"example": "Invalid parameters",
"description": "Error message"
}
},
"required": [
"type",
"message"
]
}
},
"required": [
"error"
],
"description": "Bynn_V1_Entities_Error model"
},
"Bynn_V1_Entities_Preflight": {
"type": "object",
"properties": {
"entity_id_document_type": {
"type": "string",
"enum": [
"id_card",
"passport",
"drivers_license",
"residence_permit"
],
"description": "Identified ID document type (only for ID documents). "
},
"entity_id_state": {
"type": "string",
"enum": [
"none_received",
"front_received_but_needs_resubmission",
"front_received_awaiting_back",
"front_received_and_back_received_but_back_needs_resubmission",
"id_received_awaiting_liveness",
"awaiting_liveness",
"awaiting_nfc",
"awaiting_poa",
"awaiting_pof",
"awaiting_a4_document",
"completed"
],
"description": "ID state (only for ID documents)."
},
"extra_data": {
"allOf": [
{
"$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreenExtraData"
}
],
"description": "Additional data derived from preflight analysis of the document/image."
},
"session_id": {
"type": "string",
"description": "Unique session token"
},
"screen": {
"allOf": [
{
"$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreen"
}
],
"description": "Preflight screen information, including the screen to display and its configuration parameters."
},
"requirement": {
"allOf": [
{
"$ref": "#/components/schemas/Bynn_V1_Entities_PreflightRequirement"
}
],
"description": "Requirement"
}
},
"required": [
"entity_id_document_type",
"entity_id_state",
"extra_data",
"session_id",
"screen",
"requirement"
],
"description": "Bynn_V1_Entities_Preflight model"
},
"Bynn_V1_Entities_PreflightScreenExtraData": {
"type": "object",
"properties": {
"detect_blur_and_bright_spot": {
"type": "object",
"description": "Detection results for image quality issues such as blur and bright spots. Contains detailed metrics if available."
},
"difficult_to_read": {
"type": "boolean",
"description": "Indicates whether the document or image is difficult to read due to poor quality or blurriness."
},
"entire_document_not_in_frame": {
"type": "boolean",
"description": "Indicates if the entire document is not captured within the frame."
},
"document_type": {
"type": "string",
"description": "The detected type of document, if applicable."
},
"wrong_side": {
"type": "boolean",
"description": "Indicates if the wrong side of the document has been captured."
},
"finger_cover": {
"type": "boolean",
"description": "Indicates whether a finger is covering part of the document."
}
},
"required": [
"detect_blur_and_bright_spot",
"difficult_to_read",
"entire_document_not_in_frame",
"document_type",
"wrong_side",
"finger_cover"
]
},
"Bynn_V1_Entities_PreflightScreen": {
"type": "object",
"properties": {
"show": {
"type": "string",
"enum": [
"waiting_for_previous_call_to_complete",
"consent_screen",
"scan_id_document_front_screen",
"scan_id_document_back_screen",
"scan_a4_document_screen",
"proof_of_address_screen",
"proof_of_funds_screen",
"nfc_capture_screen",
"liveness_screen",
"input_screen",
"qr_scan_screen",
"cancel_screen",
"completed_screen",
"successful_screen",
"rejected_screen",
"phone_verification_screen",
"email_verification_screen"
],
"description": "Screen to show."
},
"parameters": {
"allOf": [
{
"$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreenParams"
}
],
"description": "Configuration parameters for the preflight screen."
}
},
"required": [
"show",
"parameters"
]
},
"Bynn_V1_Entities_PreflightScreenParams": {
"type": "object",
"properties": {
"camera": {
"type": "string",
"enum": [
"back",
"front"
],
"description": "Indicating use of the back camera (main camera), of the front camera (selfie camera). If null, then no camera is allowed."
},
"camera_quality": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"ultra"
],
"description": "Camera image quality"
},
"allow_manual_upload": {
"type": "boolean",
"description": "Allow the user to upload an image or document already on the device"
},
"multipage": {
"type": "boolean",
"description": "If true, allow multiple pages to be scanned and upload when the user confirms the complete scan."
},
"autocapture": {
"type": "boolean",
"description": "If true, automatically capture the document when it is well-framed and in focus."
},
"title": {
"type": "string",
"description": "Title text to display at the top of the screen."
},
"text": {
"type": "string",
"description": "Additional text to display at the bottom of the screen."
}
},
"required": [
"camera",
"camera_quality",
"allow_manual_upload",
"multipage",
"autocapture",
"title",
"text"
]
},
"Bynn_V1_Entities_PreflightRequirement": {
"type": "object",
"properties": {
"requirement_type": {
"type": "string",
"enum": [
"identity_document",
"liveness",
"proof_of_address",
"proof_of_funds",
"phone_verification",
"email_verification"
],
"description": "Requirement type"
},
"status": {
"type": "string",
"enum": [
"preconditions_pending",
"not_checked",
"received",
"analyzed",
"passed",
"rejected",
"failed",
"matched",
"bypassed",
"manual_approved",
"manual_rejected",
"manual_review",
"manual_review_bynn",
"awaiting_receipt",
"could_not_check"
],
"description": "Status"
}
},
"required": [
"requirement_type",
"status"
]
}
}
}
}
```