{"openapi":"3.0.0","info":{"description":"This is a Identification SaaS API specification","version":"2.0.0","title":"Identification SaaS","termsOfService":"https://verigram.ai","contact":{"email":"support@verigram.ai"},"license":{"name":"Verigram","url":"https://verigram.ai"}},"tags":[{"name":"Flow","description":"Flow management"},{"name":"Servicelogs","description":"Journals of service executions"},{"name":"Liveness","description":"Liveness verification service"},{"name":"Face","description":"Face recognition service"},{"name":"Resources","description":"Resources required for or produced by the execution of the services, directly or indirectly, like access_tokens, webhooks, media files, etc."}],"externalDocs":{"description":"Identification SaaS documentation","url":"https://support.verigram.ai/docs"},"servers":[{"url":"https://demo.verigram.kz"},{"url":"https://services.kz-ala-1.verigram.kz"}],"paths":{"/flow":{"post":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Flow"],"summary":"Create a new flow","description":"Initialize a new identity verification flow for a specific person.  Requires a person identifier and can be customized with specific  templates, locales, and initial data. Returns a unique flow identifier  and a 'vlink' — a URL to the hosted verification interface that can  be used for user redirection or embedded via iframe.\n","operationId":"createFlow","requestBody":{"$ref":"#/components/requestBodies/CreateFlowRequest"},"responses":{"201":{"$ref":"#/components/responses/FlowCreatedResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/flow/{flow_id}":{"get":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Flow"],"summary":"Retrieve detailed information about a specific flow","description":"Get the current state and configuration of a flow by its unique identifier.  Returns comprehensive details including the flow's current status,  execution progress (current step), configuration template, and any  input data provided. Access is restricted to the flow's owner.\n","operationId":"getFlow","responses":{"200":{"$ref":"#/components/responses/FlowDetailsResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/flow/{flow_id}/result":{"get":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Flow"],"summary":"Get flow result","description":"Retrieve the execution results of a completed or failed flow.  Returns a projected view of the results for all sessions  executed during the flow, associated with the person's identity.  Access is restricted to the flow's owner. Returns 404 if flow is not started  yet.\n","operationId":"getFlowResult","responses":{"200":{"$ref":"#/components/responses/FlowProjectionResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/journal/session/{session_id}":{"get":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Servicelogs"],"summary":"Get session result","description":"Retrieve detailed technical logs and results for a specific service session  (e.g., liveness check, document recognition). This endpoint  returns the session context and results.\n","operationId":"getSessionResult","responses":{"200":{"$ref":"#/components/responses/SessionProjectionResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/liveness2/session":{"post":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Liveness"],"summary":"Create new liveness session","description":"Create new liveness session. Pass the returned JSON object to the frontend  (web, android or ios libraries) so you can initialize and start the session.\n","operationId":"createNewLiveness2Session","requestBody":{"$ref":"#/components/requestBodies/Liveness2CreateSessionRequest"},"responses":{"201":{"$ref":"#/components/responses/Liveness2SessionCreatedResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/resources/file":{"get":{"security":[{"ApiKey":[],"ApiVersion":[]}],"tags":["Resources"],"parameters":[{"$ref":"#/components/parameters/FilterFileLabelExact"},{"$ref":"#/components/parameters/FilterPersonIdExact"},{"$ref":"#/components/parameters/FilterSessionIdExact"},{"$ref":"#/components/parameters/FilterFlowIdExact"}],"summary":"Download files","description":"Download files generated by services during verification processes.  It always returns a file from the latest session if the request is ambiguous. Combine the file label with only one of the next IDs - session ID, flow ID or  person ID. Specifying multiple IDs in a query string may cause an error. Returns the file as a binary stream.\n","operationId":"getFiles","responses":{"200":{"$ref":"#/components/responses/SaasFile"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"responses":{"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"Forbidden":{"description":"Request is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"Unprocessable":{"description":"Unprocessable request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"TooManyRequests":{"description":"Too many request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"UpstreamUnavailable":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaasErrorResponse"}}}},"Liveness2SessionCreatedResponse":{"description":"An object with session id and other info representing a Liveness2 session, that need to be passed to the frontend.","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","format":"uuid","description":"A token to be used in the frontend to authenticate the user"},"session_id":{"type":"string","description":"The identifier of the newly created session"},"person_id":{"type":"string","description":"The identifier of the person associated with the session"},"flow_id":{"type":"string","description":"The identifier of the flow associated with the session. Is generated automatically by the system if not passed when creating the session."},"created_at":{"type":"string","format":"date-time"},"attempts_left":{"type":"integer","description":"The number of attempts left for the session"}}}}}},"SessionProjectionResponse":{"description":"Detailed session projection result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionProjection"}}}},"FlowDetailsResponse":{"description":"Flow details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"FlowProjectionResponse":{"description":"Flow Projection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowProjection"}}}},"FlowCreatedResponse":{"description":"An object with flow id and link to the hosted frontend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFlowResponse"}}}},"SaasFile":{"description":"A file requested by identifier and/or labels","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}},"requestBodies":{"CreateFlowRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFlow"}}}},"Liveness2CreateSessionRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Liveness2CreateSession"}}}}},"parameters":{"ApiKey":{"name":"api_key","in":"query","description":"Api key. A public part of an access key","required":true,"schema":{"type":"string"}},"FilterPersonIdExact":{"name":"person_id","in":"query","description":"Filter by person_id.","required":false,"schema":{"type":"string","example":"person_id=JackDorsey"}},"FilterSessionIdExact":{"name":"session_id","in":"query","description":"Filter by session_id.","required":false,"schema":{"type":"string","example":"session_id=123ABCDE-S"}},"FilterFlowIdExact":{"name":"flow_id","in":"query","description":"Filter by flow_id.","required":true,"schema":{"type":"string","example":"01KMWYGEEVW2TH4Q4SFFFFFFF5-F"}},"FilterFileLabelExact":{"name":"label","in":"query","description":"Filter by file label.","required":true,"schema":{"type":"string","example":"bestframe","enum":["bestframe","liveness_video","liveness_alt_video","liveness_frames","doc_face_picture","doc_signature_picture","doc_original_front_img","doc_original_back_img","doc_original_img","face_enroll_img","face_verif_img","egov_doc_pdf","kisc_pii","kisc_raw_content","kisc_raw_headers","signed_doc","signed_docs","certificate","cert_status","esign_original_doc","client_card","signed_doc_ticket","doc_builder_template","doc_builder_data","doc_builder_pdf","doc_builder_pdfs"]}}},"schemas":{"SaasErrorResponse":{"type":"object","properties":{"error_code":{"type":"string","description":"Internal error code. Do not confuse it with HTTP status code.","example":"NOT_FOUND, UNKNOWN_DOC_TYPE, UNAUTHORIZED, INVALID_PAYLOAD"},"error_msg":{"type":"string","example":"Person ID is required"}}},"CreateFlow":{"type":"object","properties":{"person_id":{"$ref":"#/components/schemas/PersonId"},"callback_url":{"type":"string","format":"uri","description":"Frontend callback URL the user will be redirected to after the flow  is completed.\n"},"locale":{"type":"string","enum":["kk","ru","en"],"default":"en","description":"Locale. Default is English"},"input_data":{"$ref":"#/components/schemas/FlowInputData"},"template":{"$ref":"#/components/schemas/FlowTemplate"},"template_id":{"type":"string","description":"Template ID"}},"required":["person_id"]},"CreateFlowResponse":{"type":"object","properties":{"flow_id":{"type":"string","description":"Identifier of the created flow"},"vlink":{"type":"string","description":"An HTTP URL that can be used for user redirection or embedded within your frontend application via iframe or webview.\n"}}},"FlowInputData":{"type":"object","description":"Input data necessary for the steps of the pipeline","properties":{"iin":{"type":"string","description":"IIN of a person"},"phone_number":{"type":"string","description":"Phone number of a person"},"full_name":{"type":"string","description":"Full name of a person"},"card_number":{"type":"string","description":"Credit card number"},"bin_field":{"type":"string","description":"BIN of an organization"},"org_name":{"type":"string","description":"Organization name"}}},"FlowTemplate":{"type":"object","description":"Flow template definition","properties":{"pipeline":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStep"},"description":"A list of steps to be executed in the flow"},"ui":{"$ref":"#/components/schemas/FlowConfigUi"},"status_page":{"type":"boolean","description":"Whether to show the final status page"}},"required":["pipeline"]},"FlowConfigUi":{"type":"object","description":"Configuration for the UI of the flow","properties":{"theme":{"$ref":"#/components/schemas/FlowTheme"},"logo_url":{"type":"string","format":"uri","description":"URL of the custom logo","default":"https://s3.eu-central-1.amazonaws.com/saas-statics.verigram.ai/logos/logo_vg_color.svg"},"favicon_url":{"type":"string","format":"uri","description":"URL of the custom favicon","default":"https://docs.services.verigram.cloud/2.0/assets/favicon.png"},"translation":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"description":"Custom translations for the UI. Format is {locale: {key: value}}\n"},"css":{"type":"string","description":"Custom CSS for the UI"}}},"FlowTheme":{"type":"string","description":"UI theme name","enum":["default","bts"],"default":"default"},"PipelineStep":{"type":"object","description":"A single step in the flow pipeline","properties":{"service_name":{"$ref":"#/components/schemas/ServiceName"},"allow_failure":{"type":"boolean","description":"Whether the flow can continue if this step fails","default":false},"timeout":{"type":"integer","description":"Step timeout in seconds","minimum":10,"maximum":172800,"default":300},"max_retries":{"type":"integer","description":"Maximum number of retries for the step","minimum":1,"maximum":10,"default":5}},"required":["service_name"]},"PersonId":{"type":"string","description":"Identifier of a person associated with the session. Alphanumeric string.\n","minLength":6,"maxLength":48,"pattern":"^[a-zA-Z0-9_@.+-]*$"},"StateName":{"type":"string","enum":["created","processing","processed","reviewed"]},"SessionState":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/StateName"},"created_at":{"type":"string","format":"date-time"}}},"ServiceName":{"type":"string","enum":["verilive","verilive-one-shot","verilive-infrared","veriface","veridoc","kisc","redoc","egov-doc","aml-cft","flow-form","consent","veriphone","esign","kyc-list","otp","notification","device-filter","doc-preview","doc-builder","file-storage","client-card","erd","interrupter","language-selector","amlcft-service"]},"ExecutionStatus":{"type":"string","enum":["pass","fail","unknown"],"description":"The main status of a flow or a service. Helps to make a binary decision whether  the flow/service was successful or not. If \"pass\" - the flow/service was  successful, unsuccessful otherwise. \n"},"SessionProjection":{"description":"Object representing a session result in the more compact way for a consumer.\n","type":"object","properties":{"session_id":{"type":"string","description":"Unique identifier for the session."},"person_id":{"$ref":"#/components/schemas/PersonId"},"consumer_id":{"type":"string","description":"Identifier of the consumer who owns the session."},"flow_id":{"type":"string","description":"Identifier of the flow associated with the session."},"vlink_id":{"type":"string","description":"Identifier of the vlink associated with the session."},"api_version":{"type":"string","description":"The version of the API used to create and process this session."},"service_name":{"$ref":"#/components/schemas/ServiceName"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the session was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last update to the session's state."},"session_states":{"type":"array","items":{"$ref":"#/components/schemas/SessionState"},"description":"History of execution states reached by this session."},"result":{"oneOf":[{"$ref":"#/components/schemas/VeriliveResult"}],"description":"Detailed technical result object for the specific service."}}},"LivenessPipeline":{"description":"A list of actions to be performed by the liveness verification process.\n","example":[["zoom-in"],["zoom-out"],["turn-left","turn-right"]],"type":"array","items":{"type":"array","items":{"type":"string","enum":["zoom-in","zoom-out","turn-left","turn-right","turn-straight","smile","blink","tilt-up","tilt-down","shake","tongue-out","open-mouth"]}}},"Liveness2CreateSession":{"description":"Object representing a request body of creating a liveness session.","type":"object","properties":{"person_id":{"$ref":"#/components/schemas/PersonId"},"duration":{"type":"integer","minimum":120,"maximum":600,"description":"Duration of an access token generated for the session (in seconds)"},"flow_id":{"type":"string","description":"Flow ID to be used for the session"},"pipeline":{"$ref":"#/components/schemas/LivenessPipeline"},"platform":{"type":"string","enum":["web","android","ios"],"description":"A platform of a device where the session is going to be executed."},"max_retries":{"type":"integer","description":"Maximum number of retries for a session.","default":3,"minimum":0,"maximum":100}},"required":["person_id"]},"LivenessError":{"type":"string","enum":["timeout","model_prediction","no_face","closed_eyes","face_multiplicity_frame","face_multiplicity_session","face_in_blacklist","face_in_graylist","face_has_another_account","device_in_blacklist","high_velocity","virtual_camera_risk","desktop_session","origin_country_rejected","motion_inconsistency"]},"VeriliveResult":{"description":"Object representing a result of a Verilive (liveness detection) service session.\n","type":"object","properties":{"service_name":{"type":"string","enum":["verilive"]},"service_status":{"type":"string","enum":["real","attack","unknown"]},"error_codes":{"type":"array","items":{"$ref":"#/components/schemas/LivenessError"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/LivenessError"}},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"}}},"FlowServiceStatus":{"description":"Provides a summary of the execution status and results for a specific  service within a verification flow.\n","type":"object","properties":{"service_name":{"$ref":"#/components/schemas/ServiceName"},"session_id":{"type":"string","description":"Unique identifier for the service session."},"step_id":{"type":"string","description":"Identifier for the flow step associated with this service."},"session_status":{"$ref":"#/components/schemas/ExecutionStatus"},"session_state":{"$ref":"#/components/schemas/StateName"},"session_states":{"type":"array","items":{"$ref":"#/components/schemas/SessionState"},"description":"History of execution states reached by this session."},"frontend_session_status":{"type":"string","enum":["approved","denied","suspicious","reviewing","expired","failure","active","blacklisted","whitelisted"],"description":"Simplified status intended for display in the frontend application."},"session_result":{"oneOf":[{"$ref":"#/components/schemas/VeriliveResult"}],"description":"Detailed technical result object for the specific service."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the service was first initialized within the flow."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last status update for this service session."}}},"Flow":{"type":"object","description":"Comprehensive representation of a flow's current state and configuration.","properties":{"flow_id":{"type":"string","description":"Unique identifier of the flow."},"consumer_id":{"type":"string","description":"Identifier of the consumer who owns the flow."},"vlink":{"type":"string","description":"A hosted URL where the user can access the flow's user interface. Useful for direct redirection or embedding in iframes/webviews.\n"},"api_version":{"type":"string","description":"The version of the API used to create and process this flow.","example":"2.0.0"},"locale":{"type":"string","enum":["kk","ru","en"],"description":"Language code used for the flow's user interface."},"person_id":{"$ref":"#/components/schemas/PersonId"},"template":{"$ref":"#/components/schemas/FlowTemplate"},"test_flow":{"type":"boolean","description":"Indicates whether this is a test flow created with a sandbox API key."},"current_step_id":{"type":"string","description":"Identifier of the step currently being executed or waiting to be started."},"callback_url":{"type":"string","format":"uri","description":"URL where the user will be redirected upon completion of the flow."},"input_data":{"$ref":"#/components/schemas/FlowInputData"},"input_meta":{"$ref":"#/components/schemas/FlowInputMeta"},"template_id":{"type":"string","description":"Identifier of the template used for this flow configuration."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the flow was created."},"ttl":{"type":"integer","minimum":60,"maximum":31536000,"description":"Time-to-live for the flow in seconds."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last update to the flow's state."},"polled_at":{"type":"string","format":"date-time","description":"Timestamp when the flow's status was last polled by a client."},"started_at":{"type":"string","format":"date-time","description":"Timestamp when the flow execution actually started."},"current_step_started_at":{"type":"string","format":"date-time","description":"Timestamp when the current step execution began."},"ended_at":{"type":"string","format":"date-time","description":"Timestamp when the flow reached a final state (completed, failed, etc.)."},"flow_status":{"$ref":"#/components/schemas/ExecutionStatus"},"end_cause":{"$ref":"#/components/schemas/FlowEndCause"}},"required":["flow_id","consumer_id","vlink","person_id","template","flow_status"]},"FlowInputMeta":{"type":"object","description":"Metadata regarding the flow's initial environment.","properties":{"initial_device_type":{"type":"string","enum":["desktop","mobile"],"description":"Detected device type at the start of the flow."}}},"FlowEndCause":{"type":"string","description":"The reason why the flow ended. Returns \"completed\" when execution finishes  without errors, \"failed\" when a server error or unhandled exception occurs,  \"timeout\" when a specific step exceeds its allocated duration,  or \"disconnected\" when the flow terminates due to a lost network connection  or user intervention — a status applied automatically once the default  five-minute inactivity threshold is reached, provided at least one service session was successfully initialized.\n","enum":["completed","failed","timeout","disconnected"]},"FlowProjection":{"description":"A summarized result of a verification flow, including the status and  results of all service sessions executed within the flow. This projection  is optimized for display in a consumer's dashboard or management interface.\n","type":"object","properties":{"person_id":{"$ref":"#/components/schemas/PersonId"},"flow_id":{"type":"string","description":"Unique identifier for the flow."},"person_name":{"type":"string","description":"The full name of the person being verified. This field is populated  if a document recognition service was part of the flow and successfully  extracted the name.\n"},"iin":{"type":"string","description":"Individual Identification Number (IIN) of the person, if extracted."},"check_type":{"type":"string","enum":["auto","edited"],"description":"Indicates whether the verification result was determined automatically  or manually reviewed/edited by an operator.\n"},"country_code":{"type":"string","description":"Three-letter ISO 3166-1 alpha-3 country code (e.g., \"KAZ\")."},"end_cause":{"$ref":"#/components/schemas/FlowEndCause"},"flow_status":{"$ref":"#/components/schemas/ExecutionStatus"},"sessions_count":{"type":"integer","description":"The total number of service sessions (e.g., liveness checks, document  recognition) executed during the flow.\n"},"services_count":{"type":"integer","description":"The total number of unique services that were executed during the flow.\n"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the flow was first initialized."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the last update to any session within the flow."},"ended_at":{"type":"string","format":"date-time","description":"Timestamp when the flow reached its final state."},"service_statuses":{"type":"array","items":{"$ref":"#/components/schemas/FlowServiceStatus"},"description":"Detailed status and result summary for each service executed in the flow."}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Verigram-Api-Key"},"ApiVersion":{"type":"apiKey","in":"header","name":"X-Verigram-Api-Version"}}}}