{ "openapi": "3.1.0", "info": { "title": "zyphe-sdk", "description": "", "version": "3.2.0" }, "paths": { "/flows/{slug}/fullflow": { "get": { "tags": [ "Flows" ], "summary": "Get full flow details", "description": "Returns a flow by its slug, with its steps and their settings, as the verification reads it\nbefore it starts. Send `zypheAccessSig` when the flow only accepts signed links.", "operationId": "get_full_flow_details", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "slug", "in": "path", "description": "Flow slug", "required": true, "schema": { "type": "string" } }, { "name": "zypheAccessSig", "in": "query", "description": "Signed access token (JWS). Required only when flow signed access is enabled.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFullFlowResponse" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } } } }, "/flow/{flow_id}/vr/{verification_request_id}/get": { "get": { "tags": [ "Verification Requests" ], "summary": "Get a verification request", "description": "Returns one of the user's verification requests on a flow: its status, the step it belongs to,\nand the results recorded so far. Called with the user's session token.", "operationId": "get_verification_request", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "verification_request_id", "in": "path", "description": "Verification Request ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "sandbox", "in": "query", "description": "Whether to use sandbox mode", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVerificationRequestResponse" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "jwt-auth": [] } ] } }, "/sdk/flow/{flow_id}/vr/create": { "post": { "tags": [ "SDK: Verification Requests" ], "summary": "Create a verification session", "description": "Creates a verification request for a user on a flow and returns what the client needs to\nopen it: the verification request, the session token and access signature for the hosted\nflow, and the slug of the step to start from. Identify the user by email, by an external ID,\nor by a wallet.", "operationId": "createVerificationRequest", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkCreateVerificationRequestPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkCreateVerificationRequestResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/flow/{flow_id}/vr/next-step": { "get": { "tags": [ "SDK: Verification Requests" ], "summary": "Get the next verification step", "description": "Returns the next step the user has to complete on the flow, or `isCompleted: true` when there\nis none. Identify the user by email, by an external ID, or by a wallet. Use it to decide which\nstep to present, then call the matching submit endpoint.", "operationId": "getNextStep", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "email", "in": "query", "description": "Email address of the user whose verification progress should be queried.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "credentialType", "in": "query", "description": "Credential type for wallet or external-ID based resolution (`WALLET` or `EXTERNAL_ID`).", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CredentialType" } ] } }, { "name": "chain", "in": "query", "description": "Wallet chain. Required when `credentialType` is `WALLET`.", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiwxChain" } ] } }, { "name": "address", "in": "query", "description": "Wallet address. Required when `credentialType` is `WALLET`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "externalId", "in": "query", "description": "External identifier. Required when `credentialType` is `EXTERNAL_ID`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNextStepResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/flow/{flow_id}/vr/{verification_request_id}/dv/process-dv-document": { "post": { "tags": [ "SDK: Verification Requests" ], "summary": "Submit identity document images", "description": "Submits the front (and, for two-sided documents, back) images of an identity document for\nverification. Call this after `next-step` returns a document verification step.", "operationId": "sdk_process_dv_document", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "verification_request_id", "in": "path", "description": "Verification Request ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "description": "Use sandbox environment", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessIdentityDocumentPayload" } } }, "required": true }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessIdentityDocumentResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/flow/{flow_id}/vr/{verification_request_id}/dv/liveness-challenge": { "get": { "tags": [ "SDK: Verification Requests" ], "summary": "Get the liveness challenge", "description": "Returns the liveness challenge for the current verification request, with the upload URLs\nfor the capture. Use it to present the liveness capture to the user.", "operationId": "sdk_get_liveness_challenge", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "verification_request_id", "in": "path", "description": "Verification Request ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "description": "Use sandbox environment", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLivenessChallengeResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/flow/{flow_id}/vr/{verification_request_id}/dv/process-dv-liveness": { "post": { "tags": [ "SDK: Verification Requests" ], "summary": "Submit the liveness capture", "description": "Submits the liveness capture (selfie or video) for processing. Call this after completing the\nchallenge returned by `liveness-challenge`.", "operationId": "sdk_process_dv_liveness", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "verification_request_id", "in": "path", "description": "Verification Request ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "description": "Use sandbox environment", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessLivenessPayload" } } }, "required": true }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessLivenessResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/flow/{flow_id}/vr/{verification_request_id}/dv/process-dv-selection": { "post": { "tags": [ "SDK: Verification Requests" ], "summary": "Submit the document selection", "description": "Submits the user's document selection (country and document type) to complete the document\nselection step. Call this after `next-step` returns a `document-selection` step, then call\n`next-step` again to proceed.", "operationId": "sdk_process_dv_selection", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "verification_request_id", "in": "path", "description": "Verification Request ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "description": "Use sandbox environment", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentSelectionPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentSelectionResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/flow/{flow_id}/vr/completed": { "get": { "tags": [ "Verification Requests" ], "summary": "Get completed verification requests", "description": "Lists the verification requests the user has completed on a flow, one per completed step.\nCalled with the user's session token.", "operationId": "get_completed_verification_requests", "parameters": [ { "name": "flow_id", "in": "path", "description": "Flow ID", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationRequest" } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "jwt-auth": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/flow/{flow_slug}/list": { "get": { "tags": [ "SDK: Organizations" ], "summary": "List flow results", "description": "Lists the flow results of one flow, identified by its slug, with pagination and filters.", "operationId": "listFlowResults", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flow_slug", "in": "path", "description": "Flow slug to scope results to", "required": true, "schema": { "type": "string" } }, { "name": "pagination", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Pagination" }, "style": "form" }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrganizationFlowResultsResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/reminders/ubo/{recipient_index}": { "post": { "tags": [ "SDK: KYB" ], "summary": "Send a UBO KYC reminder", "description": "Sends, or sends again, the email that invites one of the case's beneficial owners to complete\ntheir identity verification (KYC). The owner is given by their position in the `ubos` list that\n\"Read a KYB case's officers\" returns, starting from 0. Only an owner with an email can be\ninvited. Useful when the flow does not send these invitations automatically.", "operationId": "sendUboKycReminder", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipient_index", "in": "path", "description": "Index of the UBO to send the KYC email to, matching the order in uboDefinitions", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerReminderResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/ubos": { "post": { "tags": [ "SDK: KYB" ], "summary": "Add UBOs to a KYB case (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos` instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.\n\nAdds one or more ultimate beneficial owners to an existing KYB case and answers with the KYB result.", "operationId": "addKybUbosDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result — the id of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKybPersonsPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybResult" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/ubos/{person_id}": { "delete": { "tags": [ "SDK: KYB" ], "summary": "Remove a UBO from a KYB case (deprecated)", "description": "**Deprecated.** Use `DELETE /sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos/{person_id}` instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.\n\nRemoves an ultimate beneficial owner from a KYB case by their stable id and answers with the KYB result.", "operationId": "removeKybUboDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result — the id of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "person_id", "in": "path", "description": "Stable id of the UBO to remove", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybResult" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/directors": { "post": { "tags": [ "SDK: KYB" ], "summary": "Add directors to a KYB case (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors` instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.\n\nAdds one or more directors to an existing KYB case and answers with the KYB result.", "operationId": "addKybDirectorsDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result — the id of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKybPersonsPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybResult" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/directors/{person_id}": { "delete": { "tags": [ "SDK: KYB" ], "summary": "Remove a director from a KYB case (deprecated)", "description": "**Deprecated.** Use `DELETE /sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors/{person_id}` instead. It takes the same body, and answers with the case's UBOs and directors after the change rather than the whole KYB result.\n\nRemoves a director from a KYB case by their stable id and answers with the KYB result.", "operationId": "removeKybDirectorDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result — the id of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "person_id", "in": "path", "description": "Stable id of the director to remove", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybResult" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/officers": { "get": { "tags": [ "SDK: KYB" ], "summary": "Read a KYB case's officers", "description": "The ultimate beneficial owners and the directors of the case, each with the stable id the\nofficer routes address them by.", "operationId": "getKybCaseOfficers", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCaseOfficersResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos": { "post": { "tags": [ "SDK: KYB" ], "summary": "Add UBOs to a KYB case", "description": "Adds one or more ultimate beneficial owners to an existing KYB case and answers with the case's officers as they stand after the change.", "operationId": "addKybUbos", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKybPersonsPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCaseOfficersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/ubos/{person_id}": { "delete": { "tags": [ "SDK: KYB" ], "summary": "Remove a UBO from a KYB case", "description": "Removes an ultimate beneficial owner from a KYB case by their stable id and answers with the case's officers as they stand after the change.", "operationId": "removeKybUbo", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "person_id", "in": "path", "description": "Stable id of the UBO to remove", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCaseOfficersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors": { "post": { "tags": [ "SDK: KYB" ], "summary": "Add directors to a KYB case", "description": "Adds one or more directors to an existing KYB case and answers with the case's officers as they stand after the change.", "operationId": "addKybDirectors", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddKybPersonsPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCaseOfficersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/directors/{person_id}": { "delete": { "tags": [ "SDK: KYB" ], "summary": "Remove a director from a KYB case", "description": "Removes a director from a KYB case by their stable id and answers with the case's officers as they stand after the change.", "operationId": "removeKybDirector", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "person_id", "in": "path", "description": "Stable id of the director to remove", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCaseOfficersResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/approve": { "post": { "tags": [ "SDK: KYB" ], "summary": "Approve a KYB result (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/decision` instead. Send `outcome: APPROVED`, with `reason`, `reasonCode` and `dueDiligenceLevel` as here. It answers with the decision rather than the KYB result.\n\nApproves the company's KYB case. The decision is recorded as taken with your API key. The case\nmust have completed its steps and have no unresolved screening match; otherwise the request\nfails with `400` and lists what is missing. An approved case cannot be decided again.", "operationId": "approveKybResult", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "KYB result ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveKybPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDecisionResponse" } } } }, "202": { "description": "The organization's approval matrix asks for a second signature: the approve was recorded as a decision proposal and the KYB result is unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDecisionResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/reject": { "post": { "tags": [ "SDK: KYB" ], "summary": "Reject a KYB result (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/decision` instead. Send `outcome: REJECTED` with the `reason`. It answers with the decision rather than the KYB result.\n\nRejects the company's KYB case with the reason you send. The decision is recorded as taken with\nyour API key. A rejected case cannot be decided again.", "operationId": "rejectKybResult", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "KYB result ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectKybPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDecisionResponse" } } } }, "202": { "description": "The organization's approval matrix asks for a second signature: the reject was recorded as a decision proposal and the KYB result is unchanged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDecisionResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/document-requests/on-demand": { "post": { "tags": [ "SDK: KYB" ], "summary": "Request a KYB document", "description": "Asks the business for one more document on a KYB case and returns the request. The document\nmust be one the flow marks as on demand; a document the flow already requires upfront is\nrefused. The business is notified by email.", "operationId": "requestKybDocument", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOnDemandDocumentPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDocumentRequest" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}": { "get": { "tags": [ "SDK: KYB" ], "summary": "Read a KYB case", "description": "Returns a KYB case as your dashboard shows it: its status, due-diligence level and risk rating,\nwho it is assigned to, what it is waiting on, and its decision history. The case ID is the same\nas the KYB result ID.", "operationId": "getKybCase", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetailResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb-cases/{case_id}/decision": { "post": { "tags": [ "SDK: KYB" ], "summary": "Decide a KYB case", "description": "Approves or rejects a KYB case. The decision is recorded as taken with your API key, and is\nfinal: a decided case cannot be decided again.\n\n- An approval needs the case to be ready for review (`READY_FOR_REVIEW`).\n- A rejection needs a `reason`.\n- Answers `200` with the decision. When your organization's approval rules require a second\n signature, it answers `202` instead: the decision waits until a team member with the required\n role confirms it in the dashboard.", "operationId": "decideKybCase", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "case_id", "in": "path", "description": "The ID of the KYB case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideCasePayload" } } }, "required": true }, "responses": { "200": { "description": "The case is decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecidedCaseResponse" } } } }, "202": { "description": "A second signature is needed; a proposal was recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecidedCaseResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get flow result details", "description": "Returns one flow result: who it belongs to, its status, and the result of every step the user\ncompleted (document verification, liveness, proof of address, screening, forms, KYB and the\nothers). The per-step result endpoints return each step's full detail.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are JSON (`application/json`).", "operationId": "getFlowResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "kyc-flow" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResult" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/dv/{dv_result_id}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get document verification result details", "description": "Returns the full result of one document verification step, with the document images and the\ndata read from the document.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are a length-delimited protobuf stream (`application/x-protobuf-stream`). Document images and related media are in the stream, not in webhooks.", "operationId": "getDocumentVerificationResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "flow-slug" }, { "name": "dv_result_id", "in": "path", "description": "The ID of the DV result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/x-protobuf-stream": { "schema": { "type": "string" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/poa/{poa_result_id}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get proof of address result details", "description": "Returns the full result of one proof of address step, with the address document the user\nuploaded and the data read from it.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are a length-delimited protobuf stream (`application/x-protobuf-stream`). The address-document image is in the stream, not in webhooks.", "operationId": "getProofOfAddressResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "flow-slug" }, { "name": "poa_result_id", "in": "path", "description": "The ID of the POA result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/x-protobuf-stream": { "schema": { "type": "string" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/wallet/{wallet_result_id}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get wallet result details", "description": "Returns the result of one wallet step: the wallet address and chain the user proved they\ncontrol, the signed message, and the step's status.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are JSON (`application/json`).", "operationId": "getWalletResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "flow-slug" }, { "name": "wallet_result_id", "in": "path", "description": "The ID of the wallet result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResult" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/phone/{phone_result_id}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get phone result details", "description": "Returns the result of one phone step: the phone number the user verified and the step's status.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are JSON (`application/json`).", "operationId": "getPhoneResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "flow-slug" }, { "name": "phone_result_id", "in": "path", "description": "The ID of the phone result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneResult" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/flow-results/{flow_result_id}/flow/{flow_slug}/form/{form_result_id}/details": { "get": { "tags": [ "SDK: Organizations" ], "summary": "Get form result details", "description": "Returns the answers the user gave in one form step, section by section, with the step's status\nand any risk tags the answers assigned.\n\nRequires a Secret API key (`zyphe_sk_`) in the `x-api-key` header. Publishable keys are rejected.\n\nThe organization must have the Export API product (`EXPORT_API`) enabled. Otherwise the request fails with HTTP 403 (`product_not_active`).\n\nSuccessful responses are JSON (`application/json`).", "operationId": "getFormResultDetails", "parameters": [ { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" }, { "name": "organization_id", "in": "path", "description": "The ID of the organization", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_result_id", "in": "path", "description": "The ID of the flow result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "flow_slug", "in": "path", "description": "The slug of the flow", "required": true, "schema": { "type": "string" }, "example": "flow-slug" }, { "name": "form_result_id", "in": "path", "description": "The ID of the form result", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResult" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "x-api-key": [] } ] } }, "/sdk/organizations/{organization_id}/aml/screen": { "post": { "tags": [ "SDK: AML" ], "summary": "Screen a person or company (AML)", "description": "Screens a person or a company against sanctions, politically exposed persons (PEP) and other\nwatchlists, and returns the matching entries in the format named by `format`. The result is\nreturned as found: no risk score is computed and nothing is stored. Each call is charged.", "operationId": "sdkScreenAml", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkAmlScreenRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkAmlScreenResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/transactions": { "post": { "tags": [ "Transaction Monitoring" ], "summary": "Submit a transaction for monitoring", "description": "Records a payment event, checks it against your organization's monitoring rules, and answers\nright away with the decision (`ALLOW`, `REVIEW` or `BLOCK`), the rules that matched and any\nalerts raised. Sending the same `externalId` again returns the first answer without checking or\ncharging the transaction twice, so it is safe to retry. Each new transaction is charged.", "operationId": "sdkIngestTransaction", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TmIngestTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TmIngestTransactionResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/transactions/{transaction_id}": { "get": { "tags": [ "Transaction Monitoring" ], "summary": "Get a monitored transaction", "description": "Returns a transaction submitted for monitoring: its payment status, the decision and risk\nprobability, the rules that matched, and any alerts it raised.", "operationId": "sdkGetTransaction", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_id", "in": "path", "description": "Transaction ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TmTransactionResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] }, "patch": { "tags": [ "Transaction Monitoring" ], "summary": "Update a transaction's payment status", "description": "Sets the payment status of a monitored transaction: `PENDING`, `SETTLED`, `FAILED`, `CANCELED`\nor `REVERSED`. A transaction that failed, was canceled or was reversed stops counting towards the\namount and frequency limits of your rules. Sending the same update again is safe.", "operationId": "sdkUpdateTransactionStatus", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transaction_id", "in": "path", "description": "Transaction ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TmUpdateTransactionStatusRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TmTransactionResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/tin-checks": { "get": { "tags": [ "SDK: TIN Check" ], "summary": "List TIN checks", "description": "Lists your organization's TIN checks, newest first, whether they were run from the dashboard,\nwith an API key, or on a KYB submission. Each check comes with its results, and the TIN is\nmasked to its last four digits. Filter by `flowResultId` to get the checks of a KYB result.", "operationId": "sdkListTinChecks", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "query", "description": "Page size (default 50, max 200).", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "verificationRequestId", "in": "query", "description": "Only the checks run on this KYB anchor's verification request.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "flowResultId", "in": "query", "description": "Only the checks run on this flow result's verification requests: the checks of its KYB\nresult. A KYB result of a split flow names no verification request of its own, so this is\nhow the dashboard finds them. Ignored when `verificationRequestId` is given.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TinCheckListResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] }, "post": { "tags": [ "SDK: TIN Check" ], "summary": "Run a TIN check", "description": "Checks whether a US Taxpayer Identification Number (SSN or EIN) and a name match IRS records.\nThe same check can also validate a US mailing address and look up a FATCA GIIN. A check that\nreturns an answer is charged in credits (\"Get the price of a TIN check\" tells how many); a TIN\nrefused as invalid or an unavailable check costs nothing. In sandbox, checks are free and\nanswered from sample data, and `mock` lets you choose the answer.", "operationId": "sdkRunTinCheck", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTinCheckRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TinCheckResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/tin-checks/quote": { "get": { "tags": [ "SDK: TIN Check" ], "summary": "Get the price of a TIN check", "description": "What the next check costs this organization, in credits. Zero in the sandbox.", "operationId": "sdkGetTinCheckQuote", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TinCheckQuoteResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "402": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/tin-checks/{check_id}": { "get": { "tags": [ "SDK: TIN Check" ], "summary": "Get one TIN check", "description": "The check with everything it found. `404` when the id is unknown in this organization and\nenvironment.", "operationId": "sdkGetTinCheck", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "check_id", "in": "path", "description": "TIN check ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TinCheckResponse" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/reminders/ubo/{recipient_index}": { "post": { "tags": [ "SDK: KYB" ], "summary": "Send a UBO KYC reminder (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/reminders/ubo/{recipient_index}` instead: it does the same, addressed by the case ID.\n\nSends, or sends again, the email that invites one of the case's beneficial owners to complete\ntheir identity verification (KYC). The owner is given by their position in the `ubos` list that\n\"Read a KYB case's officers\" returns, starting from 0. Only an owner with an email can be\ninvited. Useful when the flow does not send these invitations automatically.", "operationId": "sendUboKycReminderDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result, which is also the ID of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipient_index", "in": "path", "description": "Index of the UBO to send the KYC email to, matching the order in uboDefinitions", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerReminderResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } }, "/sdk/organizations/{organization_id}/kyb/{kyb_result_id}/document-requests/on-demand": { "post": { "tags": [ "SDK: KYB" ], "summary": "Request a KYB document (deprecated)", "description": "**Deprecated.** Use `POST /sdk/organizations/{organization_id}/kyb-cases/{case_id}/document-requests/on-demand` instead: it does the same, addressed by the case ID.\n\nAsks the business for one more document on a KYB case and returns the request. The document\nmust be one the flow marks as on demand; a document the flow already requires upfront is\nrefused. The business is notified by email.", "operationId": "requestKybDocumentDeprecated", "parameters": [ { "name": "organization_id", "in": "path", "description": "Organization ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kyb_result_id", "in": "path", "description": "The ID of the KYB result, which is also the ID of its case", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sandbox", "in": "query", "required": true, "schema": { "type": "boolean" }, "style": "form" }, { "name": "locale", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Locale" }, "style": "form" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOnDemandDocumentPayload" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDocumentRequest" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaxeError" } } } } }, "deprecated": true, "security": [ { "api-key": [] } ] } } }, "components": { "schemas": { "ActionConfig": { "oneOf": [ { "type": "object", "description": "Set the status of a verification result.\nThe target step is automatically inferred from the most recent DV/Liveness result.", "required": [ "value", "actionType" ], "properties": { "actionType": { "type": "string", "enum": [ "setStatus" ] }, "value": { "$ref": "#/components/schemas/ActionStatus", "description": "The new status value." } } }, { "type": "object", "description": "Route execution to another flow based on conditions.", "required": [ "target_flow_id", "actionType" ], "properties": { "actionType": { "type": "string", "enum": [ "flowRouter" ] }, "target_flow_id": { "type": "string", "format": "uuid", "description": "The target flow ID to route to." } } }, { "type": "object", "description": "Assign custom risk tags to the current flow result.\nTags are stored on the FlowResult and included in the next risk score computation.", "required": [ "tag_ids", "actionType" ], "properties": { "actionType": { "type": "string", "enum": [ "assignRiskTags" ] }, "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of the RiskTagWeight rows (must belong to this org or be global)." } } } ], "description": "Configuration for an action node.\n\nEach variant represents a different action type with its specific configuration.", "discriminator": { "propertyName": "actionType" } }, "ActionStatus": { "type": "string", "description": "Status values that can be set via workflow actions.\n\nThis enum represents the possible status values that can be set\nvia the SetStatus action in workflow nodes.", "enum": [ "REQUIRES_MANUAL_REVIEW" ] }, "ActionStepOutput": { "type": "object", "description": "Action step output for tracking action node execution in workflow.", "required": [ "executed", "timestamp" ], "properties": { "executed": { "type": "boolean" }, "redirectUrl": { "type": [ "string", "null" ], "description": "Optional redirect information for flow router actions" }, "targetFlowId": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional target flow ID for flow router actions" }, "timestamp": { "type": "string", "format": "date-time" }, "token": { "type": [ "string", "null" ], "description": "Optional token for the target flow" } } }, "AddKybPersonInput": { "type": "object", "description": "A single UBO/director to add to an existing KYB result.", "required": [ "firstName", "lastName", "dateOfBirth", "country", "gender" ], "properties": { "country": { "type": "string" }, "dateOfBirth": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "When present, the person is sent a KYC invitation and must complete full KYC for the\nKYB to be approvable. When absent, the person is screened by name only (AML) and is not\nnotified — a clean name-AML result is sufficient (and required) for that person." }, "firstName": { "type": "string" }, "gender": { "type": "string" }, "lastName": { "type": "string" } } }, "AddKybPersonsPayload": { "type": "object", "description": "Request body for `POST.../kyb-cases/{case_id}/ubos` and `.../directors`.", "required": [ "persons" ], "properties": { "persons": { "type": "array", "items": { "$ref": "#/components/schemas/AddKybPersonInput" } } } }, "AddressData": { "type": "object", "required": [ "flat", "houseNumber", "building", "street", "city", "postalCode", "country" ], "properties": { "addressLine": { "type": [ "string", "null" ] }, "building": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "flat": { "type": "string" }, "houseNumber": { "type": "string" }, "postalCode": { "type": "string" }, "street": { "type": "string" } } }, "AdverseMediaAbsence": { "type": "string", "description": "Why a screening carries no adverse media.", "enum": [ "NO_PROVIDER", "PROVIDER_UNAVAILABLE", "NOT_PERFORMED" ] }, "AdverseMediaProviderKind": { "type": "string", "description": "The adverse-media screening source used for a screening. Your organization's own selection\napplies when set, otherwise the platform default. `NONE`, the default, means no adverse-media\nscreening is performed: it is an opt-in feature.", "enum": [ "NONE", "VERIFY", "ONE_MEDIA_CHECK", "GROK", "DILISENSE" ] }, "AdverseMediaProviderSource": { "type": "string", "description": "Which tier decided the adverse-media provider a screening used.\n\nReported alongside the resolved provider so an operator reading the admin surface can tell\n\"this organization chose this\" from \"this organization is following the platform\", and so a\nstored value nobody can parse any more is visible as the fallback it is rather than passing\nfor a deliberate setting.", "enum": [ "organization", "platform", "unrecognized" ] }, "AgentResearchTerms": { "type": "object", "description": "What an organization allows the reviewer to research, per flow.\n\nOff until an organization turns it on, under a platform ceiling read at each run and never\npinned into a manifest — a limit an organization lowers takes effect on the next run, not on the\nnext case.", "properties": { "enabled": { "type": "boolean", "description": "`false` — the default — means no research is attempted at all, whatever the limits say." }, "maxSearches": { "type": "integer", "format": "int32", "description": "The most hosted searches one run may issue. `0` turns the web search off while leaving the\npurchased tools on.", "minimum": 0 }, "spendLimit": { "type": "integer", "format": "int32", "description": "The most, in CREDITS, one run may spend buying answers. `0` is a real setting: research\nthat adopts what the organization already holds and buys nothing.", "minimum": 0 } } }, "AmlAdverseMediaArticle": { "type": "object", "description": "A news article found by adverse-media screening for the subject of an AML result, with its\nsource, publication details, topics and, when available, a relevance score.", "required": [ "title", "snippet", "url", "source", "language" ], "properties": { "eventGroup": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "locations": { "type": "array", "items": { "type": "string" } }, "publishedDate": { "type": [ "string", "null" ], "format": "date-time" }, "relevanceScore": { "type": [ "number", "null" ], "format": "double" }, "snippet": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" } } }, "AmlAdverseMediaCategoryCount": { "type": "object", "description": "Number of adverse-media articles the screening provider filed under one of its topic\ncategories (for example `financial_crime` or `terrorism`). Labels are provider-specific and\nmay change, so show them to reviewers rather than building logic on them.", "required": [ "label", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "label": { "type": "string" } } }, "AmlAdverseMediaResult": { "type": "object", "description": "Adverse-media screening outcome attached to an AML result.", "required": [ "provider", "checkedAt", "hasHit", "totalArticleCount", "totalEventCount" ], "properties": { "articles": { "type": "array", "items": { "$ref": "#/components/schemas/AmlAdverseMediaArticle" } }, "categoryCounts": { "type": "array", "items": { "$ref": "#/components/schemas/AmlAdverseMediaCategoryCount" }, "description": "Per-category article counts as the provider reported them, when it reports any.\n\nEmpty for providers that return no category breakdown, and on every result persisted\nbefore this field existed." }, "checkedAt": { "type": "string", "format": "date-time" }, "hasHit": { "type": "boolean", "description": "Whether the screening returned any adverse-media articles (the gating signal)." }, "provider": { "$ref": "#/components/schemas/AdverseMediaProviderKind", "description": "Provider that produced the result." }, "totalArticleCount": { "type": "integer", "minimum": 0 }, "totalEventCount": { "type": "integer", "minimum": 0 }, "windowStart": { "type": [ "string", "null" ], "format": "date-time", "description": "The earliest publication date the check considered. `None` means the whole index was\nsearched.\n\nStored because it is half the question: \"no financial-crime coverage\" over three years\nand over all history are different answers, and a count read back without the window it\nwas taken in is a number with no claim attached." } } }, "AmlAgentReview": { "type": "object", "description": "Outcome of the latest automated AI review of this screening: the verdict, the action actually\ntaken, the rationale and the remaining risk score. When `suggested` is `true` the verdict is\nonly a suggestion for a human reviewer. It applies to the current screening only and no longer\ncounts once the subject is re-screened.", "required": [ "reviewedAt", "verdictAction", "enactedAction", "rationale", "residualRiskScore", "suggested" ], "properties": { "enactedAction": { "$ref": "#/components/schemas/AmlAgentReviewAction", "description": "The action actually enacted, post-guard and post-normalization." }, "policyVersion": { "type": [ "string", "null" ], "description": "Version of the review policy used, on older reviews only. Newer reviews report\n`promptVersions` instead." }, "promptVersions": { "type": "object", "description": "Version of each prompt used to reach the verdict, keyed by prompt type, so the review can be\ntraced. Empty on older reviews, which report `policyVersion` instead.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "rationale": { "type": "string" }, "residualRiskScore": { "type": "number", "format": "float" }, "reviewedAt": { "type": "string", "format": "date-time" }, "suggested": { "type": "boolean", "description": "True when the agentic mode gated the action out (Suggest): the verdict is a suggestion\nfor a human reviewer, nothing was enacted." }, "verdictAction": { "$ref": "#/components/schemas/AmlAgentReviewAction", "description": "The Judge's verdict action." } } }, "AmlAgentReviewAction": { "type": "string", "description": "The action an automated review decided on: `approve`, `requestClarification` or `escalate`\n(hand over to a human reviewer).", "enum": [ "approve", "requestClarification", "escalate" ] }, "AmlCheckSummary": { "type": "object", "required": [ "totalEntities", "highestRiskScore", "highestRiskLevel", "hasPep", "hasSanctions", "highRiskEntitiesCount" ], "properties": { "hasAdverseMedia": { "type": "boolean", "description": "Whether the adverse-media screening for this subject returned any articles. `false` when no\narticles were found or adverse media was not screened." }, "hasPep": { "type": "boolean" }, "hasSanctions": { "type": "boolean" }, "highRiskEntitiesCount": { "type": "integer", "minimum": 0 }, "highestRiskLevel": { "$ref": "#/components/schemas/RiskLevel" }, "highestRiskScore": { "type": "integer", "format": "int32" }, "totalEntities": { "type": "integer", "minimum": 0 } } }, "AmlCompanyQueryMetadata": { "type": "object", "required": [ "companyName" ], "properties": { "companyName": { "type": "string" }, "country": { "type": "string" }, "registrationNumber": { "type": "string" } } }, "AmlEntityResponse": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/FieldWithControl" }, "birthCountry": { "$ref": "#/components/schemas/FieldWithControl" }, "birthDate": { "$ref": "#/components/schemas/FieldWithControl" }, "birthPlace": { "$ref": "#/components/schemas/FieldWithControl" }, "country": { "$ref": "#/components/schemas/FieldWithControl" }, "email": { "$ref": "#/components/schemas/FieldWithControl" }, "firstName": { "$ref": "#/components/schemas/FieldWithControl" }, "gender": { "$ref": "#/components/schemas/FieldWithControl" }, "lastName": { "$ref": "#/components/schemas/FieldWithControl" }, "match": { "type": "boolean" }, "middleName": { "$ref": "#/components/schemas/FieldWithControl" }, "name": { "$ref": "#/components/schemas/FieldWithControl" }, "nationality": { "$ref": "#/components/schemas/FieldWithControl" }, "occupancies": { "type": "array", "items": { "$ref": "#/components/schemas/AmlOccupancy" } }, "phone": { "$ref": "#/components/schemas/FieldWithControl" }, "position": { "$ref": "#/components/schemas/FieldWithControl" }, "sanctions": { "type": "array", "items": { "$ref": "#/components/schemas/AmlSanction" } }, "score": { "type": "number", "format": "double" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AmlSource" } }, "title": { "$ref": "#/components/schemas/FieldWithControl" }, "topics": { "$ref": "#/components/schemas/FieldWithControl" } } }, "AmlEntityResult": { "type": "object", "required": [ "entity", "matchScore", "match", "riskScore", "isPep", "hasSanctions", "riskTopics", "riskCountries", "riskPositions", "riskRelationships" ], "properties": { "entity": { "$ref": "#/components/schemas/AmlEntityResponse" }, "hasSanctions": { "type": "boolean" }, "isPep": { "type": "boolean" }, "match": { "type": "boolean" }, "matchScore": { "type": "number", "format": "double" }, "riskCountries": { "type": "array", "items": { "type": "string" } }, "riskPositions": { "type": "array", "items": { "type": "string" } }, "riskRelationships": { "type": "array", "items": { "type": "string" } }, "riskScore": { "$ref": "#/components/schemas/RiskScore" }, "riskTopics": { "type": "array", "items": { "type": "string" } } } }, "AmlModerationStatus": { "type": "string", "enum": [ "approved", "rejected", "escalated" ] }, "AmlOccupancy": { "type": "object", "properties": { "endDate": { "$ref": "#/components/schemas/FieldWithControl" }, "post": { "type": "array", "items": { "$ref": "#/components/schemas/AmlPosition" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AmlSource" } }, "startDate": { "$ref": "#/components/schemas/FieldWithControl" }, "status": { "$ref": "#/components/schemas/FieldWithControl" } } }, "AmlOrganization": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/FieldWithControl" }, "description": { "$ref": "#/components/schemas/FieldWithControl" }, "name": { "$ref": "#/components/schemas/FieldWithControl" }, "summary": { "$ref": "#/components/schemas/FieldWithControl" } } }, "AmlPosition": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/FieldWithControl" }, "description": { "$ref": "#/components/schemas/FieldWithControl" }, "dissolutionDate": { "$ref": "#/components/schemas/FieldWithControl" }, "inceptionDate": { "$ref": "#/components/schemas/FieldWithControl" }, "name": { "$ref": "#/components/schemas/FieldWithControl" }, "numberOfSeats": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "organization": { "type": "array", "items": { "$ref": "#/components/schemas/AmlOrganization" } }, "subnationalArea": { "$ref": "#/components/schemas/FieldWithControl" }, "summary": { "$ref": "#/components/schemas/FieldWithControl" }, "topics": { "$ref": "#/components/schemas/FieldWithControl" } } }, "AmlQueryMetadata": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "dateOfBirth": { "type": [ "string", "null" ], "description": "`None` when the subject was screened on name alone. This records what was actually queried,\nso a reviewer can tell a name-only screening from one that matched on a birth date too." }, "firstName": { "type": "string" }, "gender": { "type": [ "string", "null" ], "description": "The gender actually used in the screening query, after normalization. Absent when no gender\nwas declared, or when the declared value could not be mapped and was left out of the query." }, "lastName": { "type": "string" } } }, "AmlResult": { "type": "object", "required": [ "id", "pep", "sanctions", "createdAt", "updatedAt" ], "properties": { "adverseMedia": { "type": "boolean", "description": "Whether adverse-media screening for this subject returned a hit. `false` when there was no\nhit or adverse media was not screened." }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlRiskResult" } ] }, "id": { "type": "string", "format": "uuid" }, "namedPersonRef": { "type": [ "string", "null" ], "format": "uuid", "description": "For a name-only (email-less) UBO/director screening, the screened person's stable id\n(the `UboDefinition`/`DirectorDefinition` `id`); lets consumers correlate this AML row to\nits named person. `None` for verification-request-backed rows (person/company screenings)." }, "pep": { "type": "boolean" }, "sanctions": { "type": "boolean" }, "subjectType": { "$ref": "#/components/schemas/AmlSubjectType", "description": "Whether the screened subject is a person (`PERSON`) or a company (`COMPANY`)." }, "updatedAt": { "type": "string", "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "AmlRiskMetadata": { "type": "object", "required": [ "summary", "checkedAt", "controls" ], "properties": { "adverseMedia": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlAdverseMediaResult", "description": "Adverse-media screening outcome for this subject, when screening ran.\n`None` for results produced before adverse-media screening was wired." } ] }, "adverseMediaRequested": { "type": [ "boolean", "null" ], "description": "What the screening's ORDER asked for, recorded verbatim: `Some(true)` when a KYB case asked\nfor adverse media, `Some(false)` when it explicitly declined, `None` when nobody asked and\nthe path's own default applied.\n\nA refresh re-screens under the order the original screening ran under, and the order is the\nonly thing that can say what that was. Inferring it from the OUTCOME — \"it carries adverse\nmedia, so somebody must have asked\" — reads a legacy company screening, which always\nattaches, as case-ordered, and cannot tell a case that declined from a case that never\nasked at all.\n\n`None` on every row written before this field existed, which is the same thing it means on\na new one: nobody asked, so the path's default applies, exactly as it did." }, "adverseMediaUnavailable": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AdverseMediaAbsence", "description": "Why adverse-media results are missing when a KYB case requested them: `NO_PROVIDER` (no\nadverse-media screening is configured) or `PROVIDER_UNAVAILABLE` (the screening could not be\nperformed). Absent when adverse media was not requested or was returned." } ] }, "agentReview": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlAgentReview", "description": "Latest agentic review of this screening, when the AML review pipeline ran.\n`None` on results the agent never reviewed (and on all pre-existing rows)." } ] }, "checkedAt": { "type": "string", "format": "date-time" }, "companyQuery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlCompanyQueryMetadata" } ] }, "controls": { "type": "array", "items": { "$ref": "#/components/schemas/ResultControlOperation" } }, "moderation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlModerationStatus", "description": "The manual moderation decision currently applied to this screening result. Absent when the\nresult has not been moderated; it is cleared when the subject is re-screened. The full\nhistory of moderation actions is in `controls`." } ] }, "query": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlQueryMetadata" } ] }, "summary": { "$ref": "#/components/schemas/AmlCheckSummary" } } }, "AmlRiskResult": { "type": "object", "required": [ "entities", "metadata" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/AmlEntityResult" } }, "metadata": { "$ref": "#/components/schemas/AmlRiskMetadata" } } }, "AmlSanction": { "type": "object", "properties": { "authority": { "$ref": "#/components/schemas/FieldWithControl" }, "authorityId": { "$ref": "#/components/schemas/FieldWithControl" }, "country": { "$ref": "#/components/schemas/FieldWithControl" }, "date": { "$ref": "#/components/schemas/FieldWithControl" }, "duration": { "$ref": "#/components/schemas/FieldWithControl" }, "endDate": { "$ref": "#/components/schemas/FieldWithControl" }, "listingDate": { "$ref": "#/components/schemas/FieldWithControl" }, "program": { "$ref": "#/components/schemas/FieldWithControl" }, "reason": { "$ref": "#/components/schemas/FieldWithControl" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AmlSource" } }, "startDate": { "$ref": "#/components/schemas/FieldWithControl" }, "status": { "$ref": "#/components/schemas/FieldWithControl" }, "unscId": { "$ref": "#/components/schemas/FieldWithControl" } } }, "AmlSource": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "AmlSubjectType": { "type": "string", "description": "The screened subject of an AML result. DTO mirror of the DB `AmlSubjectType` entity enum\n(converted via `From`); lets consumers tell a company AML result\nfrom a person one. Defaults to `Person` (every result predating this field was a person).", "enum": [ "PERSON", "COMPANY" ] }, "ApiKeyType": { "type": "string", "enum": [ "PUBLISHABLE", "SECRET" ] }, "ApproveKybPayload": { "type": "object", "description": "Request body of the SDK's deprecated `POST /sdk/organizations/{organization_id}/kyb/{kyb_result_id}/approve`.\n\nBoth humans and the KYB agent use this endpoint to complete a KYB review.\nThe caller is responsible for running the appropriate pre-approval guard\nbefore calling this endpoint.", "properties": { "dueDiligenceLevel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DueDiligenceLevel", "description": "The due-diligence tier this file was investigated at, recorded onto\n`KybResult.metadata.dueDiligenceLevel` as part of the approval. Approval is the moment the\ndecision is actually made, so the approver is the one who records it. Omit it to keep an\nalready-recorded level; when nothing is recorded yet, `standard` is written — the level\nmost businesses genuinely sit at, and never `simplified`, which is a positive finding about\nthe subject rather than a default." } ] }, "reason": { "type": [ "string", "null" ], "description": "Optional reason / summary for the approval decision. Stored on the KYB\nresult and visible in the audit trail." }, "reasonCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCaseDecisionReasonCode", "description": "The closed vocabulary beside the free text.\n\nOptional, and optional on purpose: a clean approval owes no reason at all, so it cannot be\nmade to owe a code either. Where a reason IS owed and no code is sent, the decision is\nrecorded as `OTHER` — the honest answer for a decision nobody classified." } ] } } }, "AssignedRiskTag": { "type": "object", "description": "A single custom risk tag that was assigned to a flow result by the flow builder.", "required": [ "id", "tag", "weight" ], "properties": { "addedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this derivation last became active. Informational; `None` for legacy rows." }, "definitionKey": { "type": [ "string", "null" ], "description": "Stable key of the score definition the matched `ScoreTag` row belongs to (e.g. `risk`,\n`aml`, or a custom key). `None` on rows persisted before this field existed — consumers\ntreat that as unknown (the frontend falls back to the default `risk` definition)." }, "id": { "type": "string", "format": "uuid" }, "removedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Tombstone. `None` == active. This is the active predicate." }, "source": { "$ref": "#/components/schemas/RiskTagSource", "description": "Provenance / reference key. Absent in legacy rows → `Legacy` (sticky)." }, "tag": { "type": "string" }, "weight": { "type": "number", "format": "double" } } }, "AssignedRiskTags": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedRiskTag" }, "description": "The custom risk tags assigned to a flow result, including removed ones (which carry a removal\ntime)." }, "AssigneePayload": { "oneOf": [ { "type": "object", "required": [ "identityId", "kind" ], "properties": { "identityId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "IDENTITY" ] } } }, { "type": "object", "description": "`ORG_ADMIN` | `ORG_OPERATOR` | `AML_OFFICER` — the roles that may moderate.", "required": [ "role", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "ROLE" ] }, "role": { "type": "string" } } } ], "description": "Whom a subject is handed to: a named person, or whoever holds an existing role.", "discriminator": { "propertyName": "kind" } }, "AuditAction": { "type": "string", "description": "The action recorded by an audit log entry (e.g. `FLOW_CREATED`).", "enum": [ "VIEWED", "CREATED", "UPDATED", "DELETED", "AUTH_LOGIN", "AUTH_LOGIN_FAILED", "AUTH_LOGOUT", "AUTH_PASSWORD_CHANGED", "AUTH_PASSKEY_REGISTERED", "AUTH_MAGIC_LINK_REQUESTED", "AUTH_PASSWORD_RESET_REQUESTED", "AUTH_EMAIL_VERIFIED", "IDENTITY_ROLE_CHANGED", "IDENTITY_DEACTIVATED", "IDENTITY_DELETED", "ORG_CREATED", "ORG_SETTINGS_UPDATED", "ORG_MEMBER_INVITED", "ORG_MEMBER_REMOVED", "ORG_MEMBER_ROLE_CHANGED", "ORG_INVITE_REVOKED", "API_KEY_CREATED", "API_KEY_UPDATED", "API_KEY_DELETED", "BOT_CREATED", "BOT_DELETED", "BOT_TOKEN_REGENERATED", "FLOW_CREATED", "FLOW_UPDATED", "FLOW_LINK_CREATED", "FLOW_DELETED", "FLOW_STEP_ADDED", "FLOW_STEP_UPDATED", "FLOW_STEP_DELETED", "FLOW_SHARED", "FLOW_SHARE_REVOKED", "PARTNER_INVITED", "PARTNER_INVITE_ACCEPTED", "PARTNER_INVITE_REVOKED", "PARTNER_INVITE_REJECTED", "VR_CREATED", "VR_STATUS_CHANGED", "VR_MANUALLY_REVIEWED", "DV_RESULT_REVIEW_REQUESTED", "VR_CANCELLED", "DV_RESULT_STATUS_CHANGED", "DV_RESULT_MANUAL_REVIEW", "DV_RESULT_REPLAYED", "AML_RESULT_STATUS_CHANGED", "AML_RESULT_MODERATED", "AML_FIELD_REVIEWED", "AML_AGENT_REVIEWED", "AML_SCREENED", "TIN_CHECK_RUN", "POA_RESULT_STATUS_CHANGED", "SPID_RESULT_STATUS_CHANGED", "FORM_RESULT_STATUS_CHANGED", "FORM_RESULT_SUBMITTED", "KYB_APPLICATION_SUBMITTED", "KYB_DOCUMENT_REQUEST_CREATED", "KYB_DOCUMENT_UPLOADED", "KYB_CLARIFICATION_SUBMITTED", "KYB_DOCUMENT_REQUEST_REVIEWED", "KYB_ASSIGNED", "KYB_STAGE_CHANGED", "KYB_COMMUNICATION_SENT", "KYB_MODERATION_STATUS_UPDATED", "KYB_PEP_SANCTIONS_STATUS_UPDATED", "KYB_REPORT_UPLOADED", "KYB_AUTO_COMPLETED", "KYB_APPROVED", "KYB_MANUAL_REVIEW_DECISION", "KYB_VERIFICATION_FIELD_OVERRIDDEN", "KYB_DOCUMENT_CHECK_OVERRIDDEN", "KYB_METADATA_PATCHED", "KYB_SCREENING_STRATEGY_CHANGED", "KYB_BUSINESS_INFORMATION_EDITED", "KYB_UBOS_ADDED", "KYB_UBO_REMOVED", "KYB_DIRECTORS_ADDED", "KYB_DIRECTOR_REMOVED", "KYB_AGENT_REVIEWED", "KYB_DOCUMENT_CATALOG_REFRESHED", "KYB_DOCUMENTS_PURCHASED", "KYB_CASE_MANIFEST_REVISED", "KYB_CASE_RUN_COMPLETED", "KYB_CASE_RUN_FAILED", "KYB_CASE_RUN_REAPED", "KYB_CASE_RUN_REQUEUED", "KYB_CASE_EFFECTS_ABANDONED", "KYB_CASE_RETRY_FORCED", "KYB_CASE_DECISION_REPORT_HELD", "KYB_CASE_WAIVER_DECIDED", "KYB_CASE_DECIDED", "KYB_CASE_EXCEPTION_RECORDED", "KYB_CASE_EXCEPTION_WITHDRAWN", "KYB_CASE_DECISION_PROPOSAL_WITHDRAWN", "KYB_SCREENING_HIT_RESOLVED", "KYB_SCREENING_HIT_PROPOSED", "KYB_CASE_CHECK_CONFIRMED", "KYB_CASE_REOPENED", "KYB_CASE_QUALITY_REVIEW_RECORDED", "KYB_OWNERSHIP_CONFIRMATION_SUBMITTED", "KYB_SUBJECT_ASSIGNED", "KYB_SUBJECT_RELEASED", "KYB_COMPANY_RATING_OVERRIDDEN", "KYB_COMPANY_RATING_OVERRIDE_ENDED", "COMPLIANCE_POLICY_UPDATED", "COMPLIANCE_POLICY_DRAFT_SAVED", "COMPLIANCE_POLICY_PUBLISHED", "COMPLIANCE_POLICY_PUT_IN_FORCE", "COMPLIANCE_POLICY_SOP_UPLOADED", "COMPLIANCE_POLICY_SOP_REVIEWED", "KYB_CASE_AML_DISPOSITIONED", "KYB_CASE_STEP_PROPOSAL_DECIDED", "KYB_CASE_CLARIFICATION_PROPOSAL_DECIDED", "KYB_CASE_FACT_RECORDED", "KYB_CASE_INVITATION_SENT", "KYB_CASE_INVITATION_FAILED", "KYC_GRANT_CREATED", "CONSENT_GRANTED", "BLOCKLIST_ENTRY_CREATED", "BLOCKLIST_ENTRY_DELETED", "RISK_WEIGHT_UPDATED", "RISK_FACTOR_UPDATED", "DOCUMENT_DOWNLOADED", "FLOW_RESULT_EXPORTED", "FLOW_RISK_SCORE_CHANGED", "FLOW_RISK_STATUS_CHANGED", "RISK_TAG_ADDED", "RISK_TAG_RETRACTED", "TM_RULE_TRIGGERED", "TM_ALERT_RAISED", "TM_AGENT_REVIEWED", "TM_AGENT_REVIEW_STARTED", "TM_AGENT_RESOLVED", "TM_ALERT_DISPOSITIONED", "TM_ALERT_ESCALATED", "TM_RULE_DISABLED", "UNKNOWN" ] }, "AuditLogEntry": { "type": "object", "description": "A single entry in the audit log, returned by the query API.", "required": [ "id", "action", "resourceType", "details", "createdAt" ], "properties": { "action": { "$ref": "#/components/schemas/AuditAction" }, "actorId": { "type": [ "string", "null" ], "format": "uuid" }, "actorIp": { "type": [ "string", "null" ] }, "actorRole": { "type": [ "string", "null" ] }, "actorZid": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "details": {}, "id": { "type": "string", "format": "uuid" }, "isSandbox": { "type": [ "boolean", "null" ], "description": "Whether this entry originated from a sandbox operation.\n`null` = cross-cutting event (auth, org management) that spans both environments." }, "organizationId": { "type": [ "string", "null" ], "format": "uuid" }, "outcomeStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuditOutcome", "description": "Outcome of the operation. `null` for older entries recorded before outcomes were tracked." } ] }, "resourceId": { "type": [ "string", "null" ], "format": "uuid" }, "resourceType": { "$ref": "#/components/schemas/AuditResourceType" }, "sessionId": { "type": [ "string", "null" ], "description": "Login-session identifier (`fid`). Stable across token refreshes within one browser session." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuditSource", "description": "What triggered the event: an API request (`HTTP`, with method and path), a background\nprocess (`WORKER`), or a scheduled task (`SCHEDULED`)." } ] } } }, "AuditOutcome": { "oneOf": [ { "type": "object", "description": "Successful HTTP response (2xx).", "required": [ "status", "type" ], "properties": { "status": { "type": "integer", "format": "int32", "description": "Numeric HTTP status code (e.g. 200, 201, 204).", "minimum": 0 }, "type": { "type": "string", "enum": [ "httpSuccess" ] } } }, { "type": "object", "description": "Error HTTP response (4xx / 5xx).", "required": [ "status", "type" ], "properties": { "code": { "type": [ "integer", "null" ], "format": "int32", "description": "Application-level error code from the error response body (e.g. 200 for validation,\n201 for deserialization). `null` when the error did not carry one.", "minimum": 0 }, "status": { "type": "integer", "format": "int32", "description": "Numeric HTTP status code (e.g. 400, 404, 500).", "minimum": 0 }, "tag": { "type": [ "string", "null" ], "description": "Semantic error tag string (e.g. `\"BAD_REQUEST\"`, `\"NOT_FOUND\"`, `\"UNAUTHORIZED\"`)." }, "type": { "type": "string", "enum": [ "httpError" ] } } }, { "type": "object", "description": "A background process completed without error.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "workerOk" ] } } }, { "type": "object", "description": "A background process failed.", "required": [ "variant", "type" ], "properties": { "type": { "type": "string", "enum": [ "workerError" ] }, "variant": { "type": "string", "description": "Name of the error that caused the failure (e.g. `\"VaultLocked\"`, `\"UpsertDvResult\"`)." } } } ], "description": "The outcome of the operation that produced an audit entry, identified by `type`:\n- `httpSuccess` — the API request succeeded (2xx); `status` is the HTTP status code.\n- `httpError` — the API request failed (non-2xx); `status` is the HTTP status code, and\n `code` and `tag` identify the error returned in the response body, when available.\n- `workerOk` — a background process completed successfully.\n- `workerError` — a background process failed; `variant` names the error.", "discriminator": { "propertyName": "type" } }, "AuditResourceType": { "type": "string", "description": "The type of resource an audit log entry refers to. `Unknown` when the resource type could\nnot be determined (e.g. for some system operations).", "enum": [ "Search", "Identity", "Organization", "OrganizationSettings", "OrganizationTheme", "OrganizationInvite", "OrganizationBilling", "SubscriptionPlan", "KybJurisdictionPricing", "TopupPack", "ApiKey", "Bot", "Flow", "FlowStep", "FlowResult", "FlowPartnerInvite", "VerificationRequest", "DvResult", "AmlResult", "TinCheck", "PoaResult", "KybResult", "KybCase", "KybCaseRule", "KybCompanyRating", "KybSubjectAssignment", "FormResult", "Form", "RiskWeight", "ContextualFactor", "ScoreDefinition", "ScoreTag", "ScoreRule", "AuditLog", "ChatMessage", "DocumentSelection", "GeolocationResult", "PhoneVerification", "SpidResult", "WalletVerification", "Vault", "KybUboData", "DocumentDefinition", "ConfigOverride", "AgentReviewPolicy", "ShortUrl", "Cache", "Transaction", "TmRule", "TmList", "TmSettings", "TmAlert", "TmRuleTemplate", "DisposableEmailDomain", "RegistrationOffer", "RegistrationOfferLink", "WebhookEndpoint", "WebhookOrganizationSecret", "Unknown" ] }, "AuditSource": { "oneOf": [ { "type": "object", "description": "HTTP request trigger.", "required": [ "method", "path", "type" ], "properties": { "method": { "type": "string", "description": "HTTP method (e.g. \"GET\", \"POST\", \"PUT\", \"DELETE\")." }, "path": { "type": "string", "description": "Request path (e.g. \"/organizations/{id}/flows\")." }, "type": { "type": "string", "enum": [ "HTTP" ] } } }, { "type": "object", "description": "The event was emitted by a background process rather than directly by an API request.", "required": [ "workerType", "scenario", "type" ], "properties": { "scenario": { "$ref": "#/components/schemas/WorkerScenario", "description": "What started the background process." }, "type": { "type": "string", "enum": [ "WORKER" ] }, "workerType": { "$ref": "#/components/schemas/WorkerType", "description": "The kind of background process that emitted this event." } } }, { "type": "object", "description": "Scheduled/cron task trigger.", "required": [ "taskName", "type" ], "properties": { "taskName": { "type": "string", "description": "Name of the scheduled task (e.g. \"AML_REFRESH\", \"CLEANUP\")." }, "type": { "type": "string", "enum": [ "SCHEDULED" ] } } } ], "description": "What triggered an audit event, identified by `type`:\n- `HTTP` — an API request (`method` and `path`).\n- `WORKER` — a background process (`workerType` and `scenario`).\n- `SCHEDULED` — a scheduled task (`taskName`).", "discriminator": { "propertyName": "type" } }, "AutoOneClickKycConfig": { "type": "object", "required": [ "partnerConfigs" ], "properties": { "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"en_title\": \"Verify with Partners\" }" }, "partnerConfigs": { "type": "array", "items": { "$ref": "#/components/schemas/AutoOneClickPartnerConfig" }, "description": "Partner flow configurations with step type hints" }, "partnerFlows": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Flow" }, "description": "Full partner flow objects (populated by rehydrate_flow_step)" } } }, "AutoOneClickKycData": { "type": "object", "description": "Data for tracking auto one-click KYC flow.", "required": [ "flowId", "flowStepId" ], "properties": { "flowId": { "type": "string", "format": "uuid" }, "flowStepId": { "type": "string", "format": "uuid" } } }, "AutoOneClickKycStepOutput": { "type": "object", "description": "Auto One-Click KYC step output for workflow decisions.", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "AutoOneClickPartnerConfig": { "type": "object", "description": "Configuration for a single partner flow in auto one-click", "required": [ "flowId" ], "properties": { "flowId": { "type": "string", "format": "uuid", "description": "The partner flow ID" }, "targetStepTypes": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStepType" }, "description": "Which step types to attempt one-click for in this partner flow\nIf empty, defaults to [Dv]" } } }, "BaxeError": { "type": "object", "required": [ "code", "errorTag" ], "properties": { "code": { "type": "integer", "format": "int32", "minimum": 0 }, "errorTag": { "$ref": "#/components/schemas/ErrorTags" }, "message": { "type": [ "string", "null" ] } } }, "BotTokenScope": { "type": "string", "description": "Describes the visibility scope of a bot token.\n\n- `Organization` — the bot is connected to one specific organisation and is\n only visible in that organisation's bot list.\n- `Platform` — the bot is a platform-root identity (no\n `default_organization_id`) and is visible in every organisation's bot\n list.\n\nStored inside the `credentialData` JSONB of the `BOT_TOKEN` credential row.\n`Organization` is the default to ensure backward-compatible deserialization\nof rows written before this field existed.", "enum": [ "ORGANIZATION", "PLATFORM" ] }, "BranchCondition": { "type": "object", "description": "A condition branch for switch operators.", "required": [ "condition", "label" ], "properties": { "condition": { "$ref": "#/components/schemas/Condition", "description": "The condition to evaluate." }, "label": { "type": "string", "description": "The label of the edge to follow if this condition matches." } } }, "BusinessInfoDisagreementSource": { "type": "string", "description": "Source that can participate in a business information field disagreement.", "enum": [ "submitted", "document", "catalog" ] }, "BusinessInfoFieldVerification": { "type": "object", "description": "Per-field verification result comparing submitted business info against document-extracted values.", "required": [ "matchType" ], "properties": { "agentReasoning": { "type": [ "string", "null" ], "description": "The AI agent's one-sentence explanation of why this match classification was chosen.\nPresent only when the agent was invoked (i.e. an LLM cross-check was performed)." }, "catalogValue": { "type": [ "string", "null" ], "description": "The value extracted from the company catalog API." }, "disagreementSources": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessInfoDisagreementSource" }, "description": "Sources that disagree with one another for this field." }, "documentSources": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentFieldSource" }, "description": "Every persisted observation used for this field, including conflicting documents." }, "documentValue": { "type": [ "string", "null" ], "description": "The value extracted from the uploaded document(s)." }, "matchType": { "$ref": "#/components/schemas/BusinessInfoMatchType", "description": "Whether the submitted value matches the document value." }, "submittedValue": { "type": [ "string", "null" ], "description": "The user-submitted value for this field." }, "suggestedValue": { "type": [ "string", "null" ], "description": "The canonical corrected value recommended by the AI agent.\nWhen a suggested value is safely applied, `run_business_info_cross_check` stores the field\nas `AutoCorrect`. `Mismatch` and `NotFound` suggestions are surfaced for manual review\nwithout mutating the stored record." } } }, "BusinessInfoMatchType": { "type": "string", "description": "Match type for a single business information field against document-extracted values.", "enum": [ "match", "autoCorrect", "fuzzy", "mismatch", "notFound" ] }, "BusinessInformation": { "type": "object", "required": [ "contactEmail", "companyName", "registrationNumber", "companyType", "country", "address", "city", "postZipCode", "businessActivity", "incorporationDate" ], "properties": { "address": { "type": "string" }, "businessActivity": { "type": "string" }, "city": { "type": "string" }, "companyName": { "type": "string" }, "companyType": { "type": "string" }, "contactEmail": { "type": "string" }, "country": { "type": "string" }, "incorporationDate": { "type": "string" }, "postZipCode": { "type": "string" }, "registrationNumber": { "type": "string" }, "subdivision": { "type": [ "string", "null" ], "description": "The state or region the company is registered in, as the subdivision part of its ISO\n3166-2 code without the country prefix (for example `\"DE\"` for Delaware or `\"NY\"` for New\nYork), read together with `country`. Required only where company registers are regional\nrather than national (currently the US); absent for every other country." } } }, "BusinessInformationClarificationResponse": { "type": "object", "description": "Parsed representation of the client's clarification response stored inside\n`reviewReason` JSON. Present only on document requests of that type after\nthe client has submitted.", "required": [ "decision", "reason" ], "properties": { "decision": { "type": "string", "description": "Client's decision: `\"confirm\"` (values are correct as-is) or `\"deny\"` (proposes new values)." }, "fields": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BusinessInformationClarificationResponseField" }, "description": "Field updates proposed by the client. Absent or empty when `decision` is `\"confirm\"`.\nStored metadata uses key `\"updates\"`; API and legacy use `\"fields\"`." }, "reason": { "type": "string", "description": "Free-text explanation from the client." } } }, "BusinessInformationClarificationResponseField": { "type": "object", "description": "A single field update proposed by the client in a business-information clarification response.", "required": [ "fieldKey", "value" ], "properties": { "fieldKey": { "type": "string", "description": "The business-information field key (e.g. `\"companyName\"`)." }, "value": { "type": "string", "description": "The new value proposed by the client." } } }, "CaseCoverageSummary": { "type": "object", "description": "How far a case has been checked, as a list row can afford to answer it.\n\nThe case's own coverage read (`GET …/coverage`) answers per requirement AND per subject: it fans\nout over the screening population and the officer groups, and it reports the requirements that\nnothing was configured to answer at all. That reading costs a manifest, an officer population\nand a policy per case, which a page of fifty cannot afford — so a row carries the cheaper one:\nthe case's own steps, counted by how each settled.\n\nIt is a sorting aid — \"this file still has three checks out\" — and deliberately not the\napproval gate. The two readings can differ: this one knows nothing about a requirement that\nleft no step behind, nor about one subject of a screening that covered the others, so\n`complete` here means the steps are done and never that the case may be approved.", "required": [ "covered", "uncovered", "pending", "complete" ], "properties": { "complete": { "type": "boolean", "description": "Every step settled covered, and there was at least one. A case nothing has been planned for\nyet reads `false`: there is nothing that could have covered it." }, "covered": { "type": "integer", "format": "int32", "description": "Steps that answered their requirement: completed, adopted, waived, or failed and confirmed\nby a person with evidence.", "minimum": 0 }, "pending": { "type": "integer", "format": "int32", "description": "Steps that have not settled yet, and the requirements nothing has been planned for.", "minimum": 0 }, "uncovered": { "type": "integer", "format": "int32", "description": "Steps that settled without answering it — failed, or skipped with nothing to re-answer it.", "minimum": 0 } } }, "CaseDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/CaseSummaryResponse" }, { "type": "object", "properties": { "episodes": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEpisode" }, "description": "Oldest first; a case always has at least one. Derived from the case's transitions and\ndecisions at read time and stored nowhere." } } } ], "description": "One case as its own read answers.\n\nThe list row, flattened so every key a client already binds against stays exactly where it was,\nplus the one thing a single case can afford that a page cannot: its **episodes**, each attempt\nat the case from an opening or a reopening to the decision that closed it. A case reopens under\nits own id, so without them a file decided, resubmitted and decided again reads as one flat\ntimeline in which nothing says which attempt an act belonged to." }, "CaseEpisode": { "type": "object", "description": "One attempt at the case, from an opening or a reopening to its decision.\n\nDerived from the case's transitions and decisions; nothing stores it.", "required": [ "number", "openedAt", "cause" ], "properties": { "cause": { "$ref": "#/components/schemas/EpisodeCause" }, "decision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EpisodeDecision", "description": "`None` while the episode is still open." } ] }, "number": { "type": "integer", "format": "int32", "description": "1 for the first, counting up. A case always has at least one.", "minimum": 0 }, "openedAt": { "type": "string", "format": "date-time" }, "openedBy": { "type": [ "string", "null" ], "format": "uuid", "description": "Who reopened it, where a person did. The first episode opens with the case and names\nnobody." } } }, "CaseRatingSummary": { "type": "object", "description": "A company's rating as a case list shows it: the level in force and whether a person set it.\nThe parts it was computed from and its override history are the rating's own read.", "required": [ "ratingId", "level", "overridden" ], "properties": { "level": { "$ref": "#/components/schemas/KybRatingLevel", "description": "The level in force: the override's while one is in force, the computed one otherwise." }, "overridden": { "type": "boolean", "description": "Whether an override is in force over the computed level." }, "ratingId": { "type": "string", "format": "uuid" } } }, "CaseSummaryResponse": { "type": "object", "description": "A case as a reviewer's list reads it.\n\n`assignment` and `rating` are not the case's own: both are kept per company, so a list reads\nthem off `companyKey`. They are here so a worklist is one read — who holds each case and how\nrisky its company is are what a reviewer sorts their day by.", "required": [ "id", "origin", "status", "country", "dueDiligenceLevel", "coverage", "createdAt", "updatedAt" ], "properties": { "assignment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubjectAssignmentResponse", "description": "Who holds the case's company now, if anyone." } ] }, "companyKey": { "type": [ "string", "null" ], "description": "The key the company's assignment and rating are kept under. Absent for a company with no\nregistration number: it cannot be told from another in its country, so nothing is kept\nabout it and it can be neither assigned nor rated." }, "country": { "type": "string" }, "coverage": { "$ref": "#/components/schemas/CaseCoverageSummary", "description": "How far the case has been checked, counted over its own steps. Present on every row: a case\nwith nothing planned yet reads three zeros and `complete: false`, which is an answer." }, "createdAt": { "type": "string", "format": "date-time" }, "dueDiligenceLevel": { "$ref": "#/components/schemas/KybCaseDueDiligenceLevel" }, "episode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EpisodeRef", "description": "Which attempt at the case this row is on: its number and what opened it — `CREATED` for the\nfirst, `RESUBMITTED` for a case the applicant answered and reopened.\n\nA case reopens under its own id, so a list that says nothing about episodes shows a file\ndecided, resubmitted and decided again as one row with no sign that it has been round twice.\nDerived from the case's opening transitions at read time, never stored; absent for a case\nwhose history says nothing." } ] }, "flowResultId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "legalName": { "type": [ "string", "null" ] }, "nextAction": { "type": [ "string", "null" ], "description": "`CLIENT` | `RM` | `COMPLIANCE` | `SUPPORT` | `FUNDED` | `DENIED`, where set." }, "origin": { "$ref": "#/components/schemas/KybCaseOrigin", "description": "Who opened the case: `END_USER` (the business applicant, through a flow), `OPERATOR` (a member of your\norganization) or `MIGRATION` (created from a KYB result that predates KYB cases)." }, "rating": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CaseRatingSummary", "description": "The company's rating, once it has one." } ] }, "registrationNumber": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/KybCaseStatus" }, "updatedAt": { "type": "string", "format": "date-time" }, "waitingOn": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OwedBy", "description": "Which party the case is waiting on: `APPLICANT` | `REVIEWER` | `AGENT` | `PROVIDER` |\n`PLATFORM`.\n\nThe same question `GET …/next-actions` answers in full, summarised to its first line so a\nreviewer can sort a list by it. Derived, never stored, and absent where nobody owes the case\nanything — a decided case is the ordinary way to get that." } ] } } }, "CheckStatus": { "type": "string", "description": "Provider-agnostic check status.\n\nThis enum represents the canonical outcome of any verification check,\nabstracting away provider-specific status codes.\n\n# Deserialization\n\nSupports both string format (\"passed\", \"failed\", etc.) and legacy integer codes:\n- 0 = Passed\n- 1 = Failed\n- 2 = NotPerformed", "enum": [ "passed", "failed", "not_performed", "unknown" ] }, "CheckoutSessionResponse": { "type": "object", "description": "Response from creating a checkout session", "required": [ "checkoutUrl" ], "properties": { "checkoutUrl": { "type": "string" } } }, "CloudflareTracePayload": { "type": "object", "properties": { "colo": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "loc": { "type": [ "string", "null" ] }, "ts": { "type": [ "string", "null" ] }, "visitScheme": { "type": [ "string", "null" ] } } }, "CompanySearchCandidate": { "type": "object", "description": "A single company search hit. Provider-neutral: it never carries which registry\nor provider produced the match.", "required": [ "id", "legalName", "countryCode" ], "properties": { "address": { "type": [ "string", "null" ], "description": "Street line, when the register publishes one.\n\nAbsent more often than you would expect: it is built from `addressLine1`, or `street` +\nnumber, and plenty of registers return an address block carrying neither — only `city` and\na postcode. `city` is therefore the field a picker can actually rely on." }, "city": { "type": [ "string", "null" ], "description": "Town or city of the registered address.\n\nCarried separately from `address` rather than folded into it because it is the part that\nsurvives: a chooser showing several same-named companies needs *something* placing them\napart, and the city is present on hits whose street line is not." }, "countryCode": { "type": "string" }, "id": { "type": "string", "description": "Registration number / provider id — pass back as `candidateId` to prefill." }, "legalName": { "type": "string" }, "matchKind": { "type": [ "string", "null" ], "description": "Opaque hint about why this matched (e.g. `\"name\"`), when the provider reports it.\n\n`\"mock\"` marks the selectable mock company every sandbox search offers: it is not a register\nhit, and selecting it serves canned data for the rest of the journey." } } }, "CompanySearchResponse": { "type": "object", "description": "Response for `GET .../kyb/company-search`. `available: false` (with an empty\ncandidate list) signals the widget to hide the search box — the kill switch is\noff or no provider serves the country. It is never an error.", "required": [ "candidates", "available" ], "properties": { "available": { "type": "boolean" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchCandidate" } }, "subdivisions": { "type": "array", "items": { "$ref": "#/components/schemas/SubdivisionOption" }, "description": "The subdivisions this country's company registers are addressed by, when it has no national\none — the US registers every company with a state, so `US` alone names no register.\n\nServed rather than left to each client to hardcode: the list belongs to the one module that\ncan keep it honest, and a client's private copy rots silently the moment coverage changes.\nEmpty for every country that needs no subdivision, which is nearly all of them.\n\nPresent on two shapes of answer: alongside results (so a picker can be shown pre-emptively),\nand alongside an **empty** candidate list with `available: true`, which is how a search that\nnamed no subdivision is answered — \"pick a state\", not \"unavailable\" and not an error." } } }, "CompanyStatus": { "type": "string", "description": "The registry's lifecycle state for a company, normalized across providers so no caller has to\nknow which register produced it.\n\nVariants are declared least-to-most severe and `Ord` follows that order, so a company sitting\nin several states at once (bankruptcy proceedings that ended in a strike-off) reports the worst\none and a single value is enough to gate approval.", "enum": [ "ACTIVE", "RESTRUCTURING", "LIQUIDATION", "BANKRUPTCY", "DISSOLVED" ] }, "Condition": { "type": "object", "title": "Condition", "description": "A workflow condition expression (internal workflow-engine structure)." }, "ConditionOperator": { "type": "string", "description": "Condition operator type representing all valid condition operators.", "enum": [ "EQ", "NE", "GT", "LT", "GTE", "LTE", "AND", "OR", "NOT", "IN", "ANY", "ALL", "IS_NULL", "IS_NOT_NULL", "CONTAINS", "LITERAL" ] }, "CountriesFilter": { "type": "object", "required": [ "accepted", "blocked" ], "properties": { "accepted": { "type": "array", "items": { "type": "string" } }, "blocked": { "type": "array", "items": { "type": "string" } } } }, "CreateDvSessionPayload": { "type": "object", "description": "Request body for creating a hosted document-verification session. Both fields are optional,\nand they only take effect when hosted capture sessions are enabled for your deployment.", "properties": { "language": { "type": [ "string", "null" ], "description": "Preferred language for the hosted capture flow, as a language code (e.g. `\"en\"`). An\nunsupported code is ignored rather than rejected, and the default language is used." }, "sandboxScenario": { "type": [ "string", "null" ], "description": "Sandbox-only outcome control (e.g. `\"approve\"`, `\"decline_document_expired\"`). Ignored\noutside sandbox." } } }, "CreateDvSessionResponse": { "type": "object", "description": "A newly created hosted document-verification session. Embed `url` in an iframe; once the user\nhas finished, send `sessionToken` and `sessionId` (as `interviewId`) to `process-dv-document`\nto retrieve the results.", "required": [ "sessionId", "sessionToken", "url", "capture" ], "properties": { "capture": { "$ref": "#/components/schemas/DvCapture", "description": "What this session can do: its capture mode, whether capture traffic goes through Zyphe's\nproxy, and whether the session itself covers the liveness and document-authenticity checks." }, "sessionId": { "type": "string" }, "sessionToken": { "type": "string" }, "url": { "type": "string" } } }, "CreateTopupCheckoutRequest": { "type": "object", "description": "Request to create a checkout session for a one-time credit top-up purchase.", "required": [ "priceId" ], "properties": { "priceId": { "type": "string", "description": "The price ID of the top-up pack to purchase, as returned in `priceId` by\n`GET .../billing/topup-packs`." }, "redirectUri": { "type": [ "string", "null" ], "description": "Optional redirect URI after checkout. If not provided, redirects to the webapp root." } } }, "CreateVerificationRequestPayload": { "allOf": [ { "$ref": "#/components/schemas/VerificationIdentifier" }, { "type": "object", "required": [ "termsAndConditionsAccepted", "privacyPolicyAccepted", "cookiesPolicyAccepted" ], "properties": { "continueUrl": { "type": [ "string", "null" ] }, "cookiesPolicyAccepted": { "type": "boolean" }, "customData": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "privacyPolicyAccepted": { "type": "boolean" }, "termsAndConditionsAccepted": { "type": "boolean" } } } ] }, "CreateVerificationRequestResponse": { "type": "object", "required": [ "verificationRequest" ], "properties": { "verificationRequest": { "$ref": "#/components/schemas/VerificationRequest" } } }, "CreationSource": { "type": "string", "description": "How an organization was created. Lets the frontend tell self-serve signups\napart from admin- or partner-provisioned orgs (e.g. to force self-serve orgs\nto pick a real plan instead of the custom plan).\n\n- `SelfServe` — public signup with no invite.\n- `Admin` — created by platform staff; also the default for pre-existing orgs.\n- `Partner` — created through a validated partner invite.", "enum": [ "SELF_SERVE", "ADMIN", "PARTNER" ] }, "CredentialType": { "type": "string", "enum": [ "PASSWORD", "MAGIC_LINK", "PASSKEY", "BOT_TOKEN", "WALLET", "EXTERNAL_ID" ] }, "CreditExpiryPolicy": { "oneOf": [ { "type": "object", "description": "Credits expire at the end of each billing period (legacy `carry_over = false`).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "periodEnd" ] } } }, { "type": "object", "description": "Credits never expire and accumulate (legacy `carry_over = true`).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "never" ] } } }, { "type": "object", "description": "Rolling validity: each grant expires `months` after it was granted,\nsnapped forward to a billing-period boundary.", "required": [ "months", "type" ], "properties": { "months": { "type": "integer", "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "monthsFromGrant" ] } } }, { "type": "object", "description": "Absolute cutoff: grants expire `months` after the subscription started,\nsnapped to a boundary and clamped to at least the current period end.", "required": [ "months", "type" ], "properties": { "months": { "type": "integer", "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "monthsFromSubscription" ] } } } ], "description": "When the credits granted by a subscription plan at each renewal expire.", "discriminator": { "propertyName": "type" } }, "Currency": { "type": "string", "example": "usd" }, "DecideCasePayload": { "type": "object", "description": "A reviewer's decision on a case: the one immutable decision it gets.", "required": [ "outcome" ], "properties": { "confirmingProposalId": { "type": [ "string", "null" ], "format": "uuid", "description": "The standing proposed decision this act is the **second signature** on.\n\nWhere the organization's approval matrix asks for two signatures, the first act answers\n`202` with `decisionProposal`; sending its id back here is what closes the case. The\nconfirmer must be a different **person** holding a decider role, and the proposal lapses\nrather than being honoured if the state it pinned has moved." }, "dueDiligenceLevel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DueDiligenceLevel", "description": "The due-diligence tier the approver records with an approval. Ignored on a rejection." } ] }, "outcome": { "$ref": "#/components/schemas/KybCaseDecisionOutcome", "description": "`APPROVED` | `REJECTED`. An approval needs `READY_FOR_REVIEW`; a rejection is also accepted\nfrom `ACTION_REQUIRED`, and then needs a reason." }, "reason": { "type": [ "string", "null" ], "description": "Mandatory on every rejection, and on an approval resting on a recorded exception or on a\nheld match; optional on a clean approval. A blank string is no reason." }, "reasonCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCaseDecisionReasonCode", "description": "The closed vocabulary beside the free text: the reason explains, the code is what a\nregulator, a metric and a quality review can count. A decision that owes a reason and sends\nno code is recorded as `OTHER`." } ] } } }, "DecidedCaseResponse": { "type": "object", "description": "What the decision route did: closed the case (`200`), or recorded the first of two signatures\n(`202`) — the same body, with only the half that happened filled in.\n\nOne type for both because one act produced both: the matrix, not the caller, decides which. On\na `200` the body is exactly what it has always been; on a `202` the decision half is absent and\n`decisionProposal` says who is awaited.", "required": [ "outcome" ], "properties": { "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decisionId": { "type": [ "string", "null" ], "format": "uuid", "description": "Absent on a `202`: nothing was decided, so there is no decision." }, "decisionProposal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecisionProposalSummary", "description": "Set on a `202`: the organization's approval matrix asks for a second signature, and this\nact recorded a proposal instead of a decision." } ] }, "outcome": { "$ref": "#/components/schemas/KybCaseDecisionOutcome", "description": "The outcome decided, or — on a `202` — the outcome proposed." }, "reportVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The report version the decision sealed, package and all. Absent on a `202`." }, "statusAfter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCaseStatus" } ] }, "statusBefore": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCaseStatus" } ] } } }, "DecisionProposalRecorded": { "type": "object", "description": "The decision the organization's approval matrix turned into a *proposal*.\n\nThe first signature is recorded and the case is NOT decided: someone holding one of\n`awaitingRoles`, and not the proposer, confirms it through the case route's decision-proposal\nendpoints. A legacy door that gets one answers `202` rather than `200`, so an integrator that\nreads only the status code still learns that nothing is final.", "required": [ "id", "awaitingRoles" ], "properties": { "awaitingRoles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "Who may give the second signature. Empty only if the matrix named nobody, which cannot\nhappen: a proposal exists because a row asked for two signatures." }, "id": { "type": "string", "format": "uuid", "description": "The `KybCaseDecisionProposal` row, and the id the confirmation names." } } }, "DecisionProposalSummary": { "type": "object", "description": "The proposal a `202` recorded, and who it waits for.", "required": [ "id", "awaitingRoles" ], "properties": { "awaitingRoles": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "The roles the matrix named, any one of which may confirm — a different person from the\nproposer, and never a bot or an API key." }, "id": { "type": "string", "format": "uuid", "description": "Send it back as `confirmingProposalId` to close the case." } } }, "DirectorCandidate": { "type": "object", "description": "A director/legal-representative suggestion prefilled from the provider's data.\nThe applicant confirms/edits before it becomes a declared director.", "required": [ "fullName" ], "properties": { "birthDate": { "type": [ "string", "null" ], "description": "`\"YYYY-MM-DD\"`, when the provider reported a birth date. Registers list officers with a\nbirth date far more consistently than they identify graph owners, so this is usually\npopulated — and passing it on is what keeps a director's AML screening from degrading to\nname-only for want of data we were handed." }, "firstName": { "type": [ "string", "null" ], "description": "The register's own split of the name. Present far more often than not for legal\nrepresentatives, and always preferred over splitting `full_name` on whitespace — the\nheuristic mangles multi-word surnames (\"ALVES DE CASTRO\") that the register got right." }, "fullName": { "type": "string" }, "lastName": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] } } }, "DirectorDefinition": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Nationality of the director. Absent when the company register reported none." }, "dateOfBirth": { "type": [ "string", "null" ], "description": "Date of birth of the director. Often absent for a director taken from a company register,\nsince registers list officers without identity details; such a director is screened on name\nalone." }, "emailAddress": { "type": [ "string", "null" ], "description": "Email of the director. `None` for a name-only director added without an email." }, "firstName": { "type": "string" }, "gender": { "type": [ "string", "null" ], "description": "Gender of the director. Absent for any director taken from a company register (registers do\nnot publish gender); collected only when the director is entered by hand." }, "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable identifier for this director within the KYB result, used to address the director\n(for example to remove or screen them). Absent only on directors recorded before identifiers\nwere introduced." }, "lastName": { "type": "string" } } }, "DiscoverKybUbosResponse": { "type": "object", "description": "Response for `POST .../kyb/discover-ubos`. The graph runs asynchronously: the widget\npolls `GET .../kyb/discovery` for the terminal result. `status` is the created (or\nexisting, on an idempotent re-call) GRAPH row's status.", "required": [ "discoveryId", "status" ], "properties": { "discoveryId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/KybDiscoveryRequestStatus" } } }, "DocauthCheck": { "type": "string", "description": "A document-authenticity check that can be enabled on a document-verification step. Each check\nis enabled independently; see each value for what it detects and how a failure affects the\nresult.", "enum": [ "SCREEN_REPLAY", "PORTRAIT_GENDER", "PORTRAIT_AGE" ] }, "DocscanExtractionProvenance": { "type": "object", "description": "How the document data was extracted when an AI model read the document: which prompt version\nand model were used, the model's confidence and any warnings, which document sides had\nreadable text, and how long the extraction took. The document images and raw text are not\nincluded.", "required": [ "promptVersion", "promptScope", "model", "confidence", "ocrSides", "usage", "processingTimeMs" ], "properties": { "confidence": { "type": "number", "format": "double", "description": "The model's confidence in the extraction, after the platform's own checks capped it." }, "model": { "type": "string", "description": "Identifier of the AI model the extraction ran against." }, "ocrSides": { "$ref": "#/components/schemas/OcrSides", "description": "Which sides of the document text was read from. A side without text is missing\ncorroboration, not a contradiction." }, "processingTimeMs": { "type": "integer", "format": "int64", "description": "Wall-clock duration of the extraction, including OCR and any schema retry.", "minimum": 0 }, "promptScope": { "$ref": "#/components/schemas/ExtractionPromptScope", "description": "Whether the extraction instructions came from the organization's own override or the\nplatform default." }, "promptVersion": { "type": "string", "description": "Version of the extraction instructions that produced this result." }, "usage": { "$ref": "#/components/schemas/ExtractionUsage", "description": "AI model usage for the successful attempt." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Why the confidence landed where it did. Without this, a score below the configured\nthreshold is unexplainable from the UI: the reason otherwise exists only inside\n`providerMetadata.responseJson`, which is reachable only by downloading the response log." } } }, "DocscanLlmModel": { "type": "string", "description": "AI vision model used to extract data from scanned documents on a document-verification step.\nSelectable by Zyphe administrators.", "enum": [ "KIMI_K2_5", "QWEN3_VL", "UNKNOWN" ] }, "Document": { "type": "object", "required": [ "id", "metadata", "path", "type", "typeName", "createdAt", "updatedAt", "vaultId" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "path": { "type": "string" }, "type": { "type": "integer", "format": "int32" }, "typeName": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "vaultId": { "type": "string", "format": "uuid" } } }, "DocumentCatalogEntry": { "type": "object", "description": "One official register document that can be purchased for the company, as listed in the\ndocument catalog. `quotedCredits` is its price in Zyphe credits. `owned`, `purchasedAt` and\n`reissuable` describe your organization's own copy of the document.", "required": [ "documentId", "category", "quotedCredits", "owned", "reissuable" ], "properties": { "category": { "type": "string", "description": "The provider's category key (`financialStatements`, `certifiedTradeRegisterExtract`, …)." }, "description": { "type": [ "string", "null" ] }, "documentDate": { "type": [ "string", "null" ], "description": "The filing date as the register states it, verbatim — a label, not a timestamp." }, "documentId": { "type": "string", "description": "The provider's opaque document id. Regenerated per catalogue fetch and explicitly not\nstable long-term, so it is only ever safe to buy from a catalogue just refreshed." }, "estimatedDeliverySeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long the register is expected to take, per the provider." }, "format": { "type": [ "string", "null" ], "description": "The register's own word for the container (`pdf`, `zip`). Advisory: a filing listed `zip`\nis regularly delivered as PDF." }, "name": { "type": [ "string", "null" ] }, "owned": { "type": "boolean", "description": "This organization already holds a copy." }, "purchaseId": { "type": [ "string", "null" ], "format": "uuid", "description": "The receipt holding it, for the download route." }, "purchasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this organization bought that copy." }, "quotedCredits": { "type": "integer", "format": "int32", "description": "The price, in **Zyphe credits**. The provider's unit never crosses this boundary." }, "reissuable": { "type": "boolean", "description": "A fresh copy can be bought. `false` while this organization's own copy is still current —\ninside the freshness window a re-purchase returns what it already holds." }, "subType": { "type": [ "string", "null" ], "description": "The provider's stable per-country classifier, when it reports one. Safer to key on than\n`name`, which is in the register's own language." } } }, "DocumentCatalogResponse": { "type": "object", "description": "Response for `GET .../kyb-cases/{case_id}/document-catalog`.", "required": [ "status", "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentCatalogEntry" } }, "fetchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`PENDING` while registers are still answering, `COMPLETED` once they have, `FAILED` if the\nfetch failed, `NONE` when no catalogue was ever requested for this KYB result.\n\nRegisters answer independently, so `PENDING` does not mean empty: entries already listed\nare real and buyable while more are still arriving." }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid", "description": "The KYB's anchor verification request — the websocket room a `discovery-update` push lands\nin. Reported here, off the catalogue row itself, rather than only in a dispatch response,\nso a dashboard that was reloaded while a fetch or a purchase was still running can still\njoin the room and see it settle. `None` before any catalogue was requested, when there is\nnothing outstanding to wait for either." } } }, "DocumentClusterName": { "type": "string", "description": "Named categories of identity documents.\n\nServed in the OpenAPI schema even though no response field carries one: the cluster is\nderived at flow-evaluation time from a result's numeric `documentType` and exposed to JDM\nconditions as `.documentClass`. Clients that let an operator author those conditions\nneed the exact value set, and generating it beats transcribing it.", "enum": [ "ID_CARDS", "PASSPORTS", "DRIVER_LICENSES", "VISAS", "UNKNOWN" ] }, "DocumentData": { "type": "object", "required": [ "documentNumber", "issuingState", "issuingAuthority" ], "properties": { "documentCan": { "type": "string" }, "documentClassCode": { "type": "string" }, "documentNumber": { "type": "string" }, "expiryDate": { "type": [ "string", "null" ], "format": "date" }, "issuingAuthority": { "type": "string" }, "issuingDate": { "type": [ "string", "null" ], "format": "date" }, "issuingState": { "type": "string" }, "mrzStrings": { "type": "string" } } }, "DocumentDownloadResponse": { "type": "object", "description": "Response for `GET .../kyb-cases/{case_id}/documents/{purchase_id}/download`.\n\nThe signed URL is *returned*, not redirected to. The dashboard authenticates with a bearer\ntoken that a plain browser navigation cannot carry, so a redirect would have to be followed by\nan unauthenticated request — and the caller would get a `401` instead of a document. Handing\nback the URL lets the client fetch it through the authenticated API and then open it.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Short-lived and single-purpose. Not cacheable, and not worth persisting: re-reading this\nendpoint signs a fresh one for free." } } }, "DocumentFieldSource": { "type": "object", "description": "A document observation used by a cross-check. Legacy observations have no extraction ID.", "required": [ "value" ], "properties": { "extractionId": { "type": [ "string", "null" ], "format": "uuid" }, "value": { "type": "string" } } }, "DocumentFormatFilter": { "type": "object", "required": [ "formats" ], "properties": { "formats": { "type": "array", "items": { "type": "string" } } } }, "DocumentImage": { "type": "object", "required": [ "type", "path" ], "properties": { "path": { "type": "string" }, "type": { "type": "string" } } }, "DocumentPurchaseDecision": { "type": "object", "description": "The outcome for one document in a purchase request. Each document is accepted or rejected on\nits own, so a request mixing good and bad documents reports per document instead of failing\nas a whole.", "required": [ "documentId", "accepted" ], "properties": { "accepted": { "type": "boolean" }, "documentId": { "type": "string" }, "purchaseId": { "type": [ "string", "null" ], "format": "uuid", "description": "The receipt row, when the purchase was accepted." }, "quotedCredits": { "type": [ "integer", "null" ], "format": "int32", "description": "What this document was quoted at, in Zyphe credits." }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentRejectReason" } ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDiscoveryRequestStatus", "description": "`PENDING` | `COMPLETED` | `FAILED`. Registers quote minutes, so `PENDING` is the norm." } ] } } }, "DocumentRejectReason": { "type": "string", "description": "Why a document cannot be bought — a closed enum, so the catalogue and the dispatch report can\nnever disagree on the wording of a refusal.\n\nNo variant names an internal pricing cause: a customer learns that a purchase was refused and\nwhat to do about it, never how we arrive at a price.", "enum": [ "unknownDocumentId", "alreadyOwned", "purchaseInFlight", "catalogUnavailable", "providerError", "priceChanged", "insufficientCredits" ] }, "DocumentScanStatus": { "type": "object", "description": "Status of various document scan checks.\n\n# Deserialization\n\nSupports both new abstract format and legacy format:\n\n**New format:**\n```json\n{ \"overall\": \"passed\", \"documentType\": \"passed\", \"expiry\": \"passed\", \"mrz\": \"passed\" }\n```\n\n**Legacy format:**\n```json\n{\n \"overallStatus\": 0,\n \"detailsOptical\": { \"docType\": 1, \"expiry\": 0, \"mrz\": 2, ... },\n \"optical\": 0, \"portrait\": 1, \"rfid\": 2, ...\n}\n```", "required": [ "overall", "documentType", "expiry", "mrz" ], "properties": { "documentType": { "$ref": "#/components/schemas/CheckStatus", "description": "Document type detection result" }, "expiry": { "$ref": "#/components/schemas/CheckStatus", "description": "Expiry date validation result" }, "mrz": { "$ref": "#/components/schemas/CheckStatus", "description": "MRZ validation result" }, "overall": { "$ref": "#/components/schemas/CheckStatus", "description": "Overall verification result" } } }, "DocumentSelectionConfig": { "type": "object", "required": [ "countriesFilter", "documentTypesFilter", "enabledGovernmentProviders" ], "properties": { "allowedDocumentsPerCountry": { "type": [ "object", "null" ], "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "countriesFilter": { "$ref": "#/components/schemas/CountriesFilter" }, "documentTypesFilter": { "$ref": "#/components/schemas/DocumentTypeFilter" }, "documentTypesFilterPerCountry": { "type": [ "object", "null" ], "description": "Optional per-country overrides for the document-type filter.\n\nKeys are ISO 3166-1 alpha-2 country codes. When a country is present here, its\n`DocumentTypeFilter` fully overrides `document_types_filter` for that country\n(no union/intersection). An explicit empty entry rejects the country entirely\n(the country gate fails, not just the document-type gate).\n\nThe custom deserializer validates each key via `CountryInfo::from_any_country_code`\nand normalises the stored key to its `iso_alpha_2` upper-case form.", "additionalProperties": { "$ref": "#/components/schemas/DocumentTypeFilter" }, "propertyNames": { "type": "string" } }, "enabledGovernmentProviders": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/SpidDocumentType" } }, "propertyNames": { "type": "string" } }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"en_button_label\": \"Next step\" }" } } }, "DocumentSelectionStepOutput": { "type": "object", "description": "Document selection step output for workflow decisions.", "properties": { "country": { "type": [ "string", "null" ] }, "documentType": { "type": [ "integer", "null" ], "format": "int64" } } }, "DocumentTypeFilter": { "type": "object", "required": [ "types" ], "properties": { "types": { "type": "array", "items": { "type": "string" } } } }, "DocumentUpload": { "type": "object", "required": [ "filename" ], "properties": { "documentType": { "type": [ "string", "null" ] }, "filename": { "type": "string" }, "presignedUrl": { "type": [ "string", "null" ] }, "s3Key": { "type": [ "string", "null" ] } } }, "DueDiligenceLevel": { "type": "string", "description": "How intensively a business must be investigated before it can be onboarded: the risk-based\ndue-diligence tier AML/CFT regulations expect. Independent of the screening strategy, which\ndecides *who* is screened; this decides *how deeply* the business is investigated. The level\nis currently recorded only and does not yet change which checks the platform runs.", "enum": [ "simplified", "standard", "enhanced" ] }, "DvCapture": { "type": "object", "description": "What a document-capture session can do. `capture` is the capture mode; `usesProxy` is `true`\nwhen the capture surface talks to the identity-verification provider through Zyphe's proxy;\n`providesLiveness` and `providesAuthenticity` are `true` when the session itself performs the\nliveness check and the document-authenticity check. When `false`, the session does not: a check\nruns only if the flow has one of its own, a liveness step or the step's `docauthChecks`, which\nare empty by default.", "required": [ "capture", "usesProxy", "providesLiveness", "providesAuthenticity" ], "properties": { "capture": { "$ref": "#/components/schemas/DvCaptureMode" }, "providesAuthenticity": { "type": "boolean" }, "providesLiveness": { "type": "boolean" }, "usesProxy": { "type": "boolean" } } }, "DvCaptureMode": { "type": "string", "description": "How a provider is driven for one attempt.", "enum": [ "DIRECT", "SESSION" ] }, "DvConfig": { "type": "object", "required": [ "minimumAge" ], "properties": { "amlAgenticMode": { "oneOf": [ { "$ref": "#/components/schemas/KybAgenticMode", "description": "Agentic AML-review mode for the person AML screening this DV step triggers\n(`DISABLED` | `SUGGEST` | `AUTO_PILOT`). Per-flow, mirroring `KybConfig.agentic_mode`:\nthe AML review dispatcher resolves the mode from the screening's originating step, so\neach flow controls its own AML autonomy rather than a deployment-wide switch." } ], "default": "DISABLED" }, "capture": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DvCapture", "description": "This attempt's resolved capability descriptor — capture mode, proxy, liveness, authenticity\n— so the frontend knows which capture path to render without ever seeing which provider\nproduced it.\n\nA per-attempt value, not a per-flow one: it is derived from the verification request's\nresolved ladder rung, so it is injected only into the VR-scoped `next-step` response, never\npersisted on this config, and never present on the cached full-flow response — a per-attempt\nvalue cannot live in a per-flow cache." } ] }, "docauthChecks": { "type": "array", "items": { "$ref": "#/components/schemas/DocauthCheck" }, "description": "Additional document-authenticity checks to run on this step's scans. Empty by default\n(no additional checks). `SCREEN_REPLAY` fails the scan on a replay verdict; the portrait\nchecks only lower the document score. Configured by Zyphe administrators; ignored when the\nidentity-verification provider in use supplies its own authenticity checks or none." }, "documentSelectionStepId": { "type": "string", "format": "uuid" }, "incodeConfigurationId": { "type": [ "string", "null" ], "description": "Provider configuration ID the frontend must use when creating the document-capture session\nwith the identity-verification provider. Set by the server when the step is served; absent\nwhen the provider in use does not need one. Do not set it yourself." }, "kycValiditySeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long (in seconds) a successful DV result remains valid before\nre-KYC is required. `None` = never expires (existing behaviour)." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"en_button_label\": \"Next step\" }" }, "llmModel": { "$ref": "#/components/schemas/DocscanLlmModel", "description": "AI vision model used to extract data from scanned documents. Uses the default model when\nomitted." }, "maxAttempts": { "type": [ "integer", "null" ], "format": "int32", "example": "5", "minimum": 0 }, "minimumAge": { "type": "integer", "format": "int32", "minimum": 0 }, "poaFromGovcheck": { "type": "boolean", "description": "When true, the scanned driver's license is validated against government records and, after\nthe document scan, a proof-of-address result is produced from the validated address.\nDefaults to `false`. Only supported by some identity-verification providers; ignored\notherwise." }, "processImagesOverrides": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProcessImagesOverrides" } ] }, "requiredDocumentFields": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredDocumentField" } }, "reverificationLeadSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long (in seconds) *before* a result's expiry to begin re-verification: the flow is\nreopened and a reminder email is sent, so the holder can renew while their current result is\nstill valid. Defaults to one week (604800) when omitted. Ignored when\n`kycValiditySeconds` is not set; capped at the validity period." }, "thresholds": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "format": "float" }, "propertyNames": { "type": "string", "enum": [ "documentScorePercent" ] } } } }, "DvConfigThreshold": { "type": "string", "enum": [ "documentScorePercent" ] }, "DvReason": { "type": "string", "enum": [ "UNKNOWN", "WRONG_DOCUMENT_TYPE", "COUNTRY_FILTER", "FACE_MATCH_CHECK", "FACE_MATCH_CHECK_ONE_CLICK", "OVERALL_STATUS", "DOCUMENT_COUNTRY_MISMATCH", "DOCUMENT_COUNTRY_MISSING", "DATE_OF_EXPIRY_NOT_VALID", "DATE_OF_EXPIRY_NOT_READABLE", "DATE_OF_EXPIRY_FIELD_MISSING", "DOCUMENT_ALREADY_USED_BY_ANOTHER_USER", "DOCUMENT_FINGERPRINT_COMPUTATION", "SECURITY_CHECK_FAILED", "CROSS_CHECK_FAILED", "DOCUMENT_ALTERATION_DETECTED", "DOCUMENT_TAMPERING_DETECTED", "FAKE_DOCUMENT_DETECTED", "SCREEN_REPLAY_ATTACK_DETECTED", "PAPER_COPY_DETECTED", "DOCUMENT_SCORE_BELOW_THRESHOLD", "DOCUMENT_TYPE_NOT_DEFINED", "DOCUMENT_NOT_FOUND", "DATE_OF_BIRTH_BELOW_MINIMUM_AGE", "DOCUMENT_TYPE_CHECK", "ELECTRONIC_DEVICE", "SECURITY_TEXT", "IMAGE_PATTERNS", "PHOTO_EMBEDDINGS", "BLACK_AND_WHITE_COPY", "UNIQUENESS_CHECK", "REQUIRED_FIELDS_MISMATCH", "LIVENESS_CHECK_FAILED", "LIVENESS_ANTISPOOF_FAILED", "LIVENESS_BRIGHTNESS_FAILED", "LIVENESS_EYES_CLOSED_FAILED", "LIVENESS_WEARING_SUNGLASSES_FAILED", "LIVENESS_FACE_OCCLUDED_FAILED", "LIVENESS_SHARPNESS_FAILED", "LIVENESS_FACE_CONSISTENCY_FAILED", "MISSING_FRONT_IMAGE", "DUPLICATE_IMAGE_SIDE", "INVALID_IMAGE_DATA", "IMAGE_TOO_LARGE", "UNSUPPORTED_IMAGE_FORMAT", "DOCUMENT_INCOMPLETE" ] }, "DvResult": { "type": "object", "required": [ "id", "status", "reasons", "data", "processAdditionalData", "authenticityChecks" ], "properties": { "adminComment": { "type": [ "string", "null" ] }, "authenticityChecks": { "type": "array", "items": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "browser": { "type": [ "string", "null" ] }, "class": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "data": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "documentId": { "type": [ "string", "null" ], "format": "uuid" }, "documentScorePercent": { "type": [ "integer", "null" ], "format": "int32" }, "documentType": { "type": [ "integer", "null" ], "format": "int32" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "manualReviewAt": { "type": [ "string", "null" ], "format": "date-time" }, "manualReviewNote": { "type": [ "string", "null" ] }, "manualReviewerId": { "type": [ "string", "null" ], "format": "uuid" }, "manualReviewerZid": { "type": [ "string", "null" ] }, "originalVrHistoryId": { "type": [ "string", "null" ], "format": "uuid" }, "platform": { "type": [ "string", "null" ] }, "portraitMatchPercent": { "type": [ "integer", "null" ], "format": "int32" }, "processAdditionalData": { "$ref": "#/components/schemas/ProcessAdditionalData" }, "provinceCode": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/DvReason" } }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "validUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "When this KYC result expires and re-verification is required (re-KYC validity).\n`null` means it never expires (no `kyc_validity_seconds` configured, or a legacy result)." }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "DvStepOutput": { "type": "object", "required": [ "status", "numberOfAttempts" ], "properties": { "amlAdverseMedia": { "type": [ "boolean", "null" ], "description": "Whether the subject's screening found adverse media — a routing signal beside `amlPep` and\n`amlSanctions`, so a flow can branch on it as it can on the other two. `None` until a\nscreening lands, and on outputs written before the signal existed." }, "amlPep": { "type": [ "boolean", "null" ] }, "amlRiskScorePercent": { "type": [ "integer", "null" ], "format": "int32" }, "amlSanctions": { "type": [ "boolean", "null" ] }, "dateOfExpiry": { "type": [ "string", "null" ], "format": "date-time" }, "documentType": { "type": [ "integer", "null" ], "format": "int32" }, "issuingCountry": { "type": [ "string", "null" ] }, "livenessStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResultStatus" } ] }, "numberOfAttempts": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/components/schemas/ResultStatus" } }, "additionalProperties": { "type": "boolean", "description": "Pre-compiled results of conditions that reference vault-derived personal data\n(name, surname, date of birth, age, etc.).\n\nEach entry maps a stable `condition_hash` (16-char hex, see\n`matcher::precompile::condition_hash`) to the boolean result of evaluating\nthat condition against the live in-memory `VaultDocument` at the moment the\nDV background job ran.\n\nFlattened into the serialized output so each hash becomes a top-level sibling\nof `status`, `issuingCountry`, etc. — referenceable as `\"dv_step.\"`.\n\nAt JDM evaluation time, `vault_condition::resolve_precompiled_graph` replaces\nany condition whose hash is present here with `Condition::Literal { value }`,\nso no vault PII ever needs to be stored in or read from the database." } }, "EpisodeCause": { "type": "string", "description": "Why an episode of a case opened.\n\nEach reopening cause here is the reading of one transition cause: a `REOPENED` transition opens\na `RESUBMITTED` episode, a `QA_REOPENED` one a `QA_REOPENED` episode and a `PERIODIC_REVIEW` one a\n`PERIODIC_REVIEW` episode — the case's own history says which way it came back.", "enum": [ "CREATED", "RESUBMITTED", "QA_REOPENED", "PERIODIC_REVIEW" ] }, "EpisodeDecision": { "type": "object", "description": "How an episode ended, where it did.", "required": [ "id", "outcome", "standing" ], "properties": { "id": { "type": "string", "format": "uuid" }, "outcome": { "$ref": "#/components/schemas/KybCaseDecisionOutcome" }, "packageVersionId": { "type": [ "string", "null" ], "format": "uuid", "description": "The progress report version the decision sealed its package into." }, "standing": { "type": "boolean", "description": "Whether this decision is the one that still stands: a superseded decision keeps its episode\nand says it was overtaken." } } }, "EpisodeRef": { "type": "object", "description": "An episode named from somewhere else — a story entry, an account entry, a list row, a sealed\npackage. The number and the cause are what a reader needs; the rest is on the case.", "required": [ "number", "cause" ], "properties": { "cause": { "$ref": "#/components/schemas/EpisodeCause" }, "number": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ErrorTags": { "type": "string", "enum": [ "unexpected", "bad_request", "permission_denied", "request_deserialization", "database", "invalid_email_or_password", "user_not_confirmed", "verify_password", "send_email", "open_session", "read_session", "close_session", "user_disabled", "missing_authorization_header", "invalid_authorization_header", "token_generation", "user_not_found", "email_already_taken", "invalid_invite", "wrong_invite_user", "invite_not_found", "email_already_verified", "flow_not_found", "flow_step_not_found", "organization_not_found", "storage", "verification_request_not_found", "document_reader", "sse", "organization_settings_not_found", "theme_not_found", "start_job", "result_not_found", "kyc_grant_not_found", "document_not_found", "service_invocation", "trigger_webhook", "too_many_invites", "invite_already_used", "invite_already_accepted", "invite_already_revoked", "invite_revoked", "invite_expired", "invite_already_exists", "share_already_revoked", "form_not_found", "form_in_use", "flow_step_configuration_not_found", "identity_not_found", "step_order_violation", "serialization", "mock_data", "api_key_not_found", "not_implemented", "access_grant", "rate_limit_exceeded", "missing_api_key", "invalid_api_key", "origin_not_allowed", "step_already_completed", "send_sms", "send_notification", "parse_error", "inviter_organization_not_found", "forbidden", "passkey_authentication", "internal", "invalid_email", "disposable_email", "graph_validation", "external_api", "share_already_has_write_access", "share_does_not_have_write_access", "write_access_already_revoked", "invite_required", "billing", "billing_email_required", "product_not_active", "registration_offer_not_found", "registration_offer_unavailable", "registration_offer_invalid_terms", "topup_pack_unlocks_unpriced", "score_rule_not_found", "score_rule_field_outside_scores", "score_rule_unknown_score", "score_rule_score_disabled", "score_rule_score_not_yet_computed", "score_rule_set_score_out_of_range", "score_rule_effect_kind_mismatch", "kyb_case_not_decidable", "kyb_case_not_ready", "kyb_case_exception_required", "kyb_case_rejecting_hit", "kyb_case_reason_required", "kyb_case_decision_not_authorized", "kyb_case_second_signature_required", "compliance_policy_open_questions", "tin_check_invalid_tin", "tin_check_unavailable", "tin_check_ein_required", "tin_check_mismatch", "tin_check_attempts_exhausted" ] }, "EstimateBasis": { "type": "string", "description": "What an estimated cost represents. `fixedPrice` is a real quoted price; `variableCap` is only\nthe maximum that may be charged, because the actual cost varies; `unknown` means pricing could\nnot be determined and a conservative maximum is shown. Do not present a `variableCap` or\n`unknown` estimate to users as a price.", "enum": [ "fixedPrice", "variableCap", "unknown" ] }, "ExecutedAction": { "type": "object", "description": "Represents an executed action with its ID and type.", "required": [ "actionId", "actionConfig" ], "properties": { "actionConfig": { "$ref": "#/components/schemas/ActionConfig", "description": "The type of action that was executed." }, "actionId": { "type": "string", "format": "uuid", "description": "The unique identifier of the action node." } } }, "ExpansionCandidate": { "type": "object", "description": "Whether one node of the ownership graph can be expanded, and at what estimated cost, as shown\nin the expansion preview. `countryCode` and pricing are always those of this node's own\ncompany, not the company under review: a Cayman parent of an Italian company is priced as\nCayman.", "required": [ "nodeId", "legalName", "countryCode", "nodeStatus", "expandable", "alreadyExpanded", "estimateBasis" ], "properties": { "alreadyExpanded": { "type": "boolean", "description": "Report-only, never a rejection: the provider's 24h dedup makes re-expanding an already\n`found` node near-free, and a reviewer may legitimately re-pull it." }, "countryCode": { "type": "string" }, "estimateBasis": { "$ref": "#/components/schemas/EstimateBasis" }, "estimatedCredits": { "type": [ "integer", "null" ], "format": "int32", "description": "**Zyphe** credits (provider credit cents × EUR→credit FX rate × Zyphe margin) — never the\nprovider's own credits. `None` when `expandable` is `false`: a rejected node has no\ndefensible price to show." }, "expandable": { "type": "boolean" }, "expectedLatency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExpansionLatency", "description": "`None` when `expandable` is `false` — nothing is being agreed to." } ] }, "legalName": { "type": "string" }, "nodeId": { "type": "string" }, "nodeStatus": { "type": "string", "description": "The provider's node-status flag (`found`, `budget_truncated`, `placeholder`, …) as stored\non the graph — free-form, see `OwnershipFlags::status`." }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExpansionRejectReason" } ] } } }, "ExpansionDecision": { "type": "object", "description": "Whether one requested node was accepted for expansion. `discoveryId` and `status` are absent\nfor a node rejected up front; a node that was sent but failed (`providerError` or\n`budgetExceeded`) has `accepted: false` and carries both, with `status` `FAILED`.", "required": [ "nodeId", "accepted" ], "properties": { "accepted": { "type": "boolean" }, "chargedCredits": { "type": [ "integer", "null" ], "format": "int32", "description": "Present when the row finalized inline; otherwise it arrives via the websocket push or the\n`GET .../kyb/discovery` read." }, "discoveryId": { "type": [ "string", "null" ], "format": "uuid" }, "estimateBasis": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EstimateBasis" } ] }, "estimatedCredits": { "type": [ "integer", "null" ], "format": "int32", "description": "Estimated cost of expanding this node, in Zyphe credits, as in the expansion preview." }, "nodeId": { "type": "string" }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExpansionRejectReason" } ] }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDiscoveryRequestStatus", "description": "Present once a row exists, including a node whose dispatch itself failed\n(`providerError`/`budgetExceeded`) — that row is `FAILED`." } ] } } }, "ExpansionLatency": { "type": "string", "description": "How long an accepted expansion is expected to take to resolve. Not cosmetic: it changes what\nthe operator is agreeing to when they click. `None` when the node was not accepted — there is\nnothing to wait for.", "enum": [ "fast", "slow", "manual" ] }, "ExpansionPreviewResponse": { "type": "object", "description": "Preview of which ownership-graph nodes can be expanded and what each would cost, plus the\nexpansions already running. Requesting a preview is free; prices come from a price list that\nis refreshed at least daily.", "required": [ "candidates", "inFlight", "concurrencySlotsFree" ], "properties": { "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ExpansionCandidate" } }, "concurrencySlotsFree": { "type": "integer", "format": "int32", "minimum": 0 }, "inFlight": { "type": "array", "items": { "$ref": "#/components/schemas/InFlightExpansion" } }, "pricingFetchedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The oldest `fetchedAt` among the pricing rows consulted for this preview, or `None` when no\ncandidate country had a cached row. A staleness hint, not a guarantee — an individual\ncountry's own row may be fresher or staler than this floor." } } }, "ExpansionRecord": { "type": "object", "description": "One past expansion of a single ownership-graph node: its status, when it ran, why it stopped\n(if it stopped early) and what it actually cost, in `chargedCredits`.", "required": [ "discoveryId", "rootNodeId", "status", "chargedCredits", "createdAt" ], "properties": { "chargedCredits": { "type": "integer", "format": "int32" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "discoveryId": { "type": "string", "format": "uuid" }, "rootNodeId": { "type": "string" }, "status": { "$ref": "#/components/schemas/KybDiscoveryRequestStatus" }, "stoppedReason": { "type": [ "string", "null" ] } } }, "ExpansionRejectReason": { "type": "string", "description": "Why a node cannot be expanded. `providerError`, `budgetExceeded` and `insufficientCredits`\nonly occur when the expansion is actually requested, never in the expansion preview. A\n`budgetExceeded` rejection costs nothing and, when available, reports the actual price in the\ndecision's `estimatedCredits`, so you can retry with a higher `maxCreditsPerNode`.", "enum": [ "notACompanyNode", "countryUnsupported", "graphDatapointUnavailable", "expansionInFlight", "baseRunInFlight", "autoTraversalInFlight", "concurrencyCap", "unknownNodeId", "providerError", "budgetExceeded", "insufficientCredits" ] }, "ExtendKybDiscoveryPayload": { "type": "object", "description": "Request to continue a completed ownership discovery that stopped early, digging deeper from\nthe selected company nodes of the ownership graph. Each node is priced, billed and accepted or\nrejected on its own.", "required": [ "nodeIds" ], "properties": { "maxCreditsPerNode": { "type": [ "integer", "null" ], "format": "int32", "description": "The most, in Zyphe credits, that expanding each node may cost your organization. It can\nonly lower the limit: for a fixed-price country, a cap below the quoted price makes the node\ncome back rejected with its actual cost instead of being charged. Omit it to use the\nplatform's default ceiling.", "minimum": 0 }, "nodeIds": { "type": "array", "items": { "type": "string" }, "description": "`nodeId`s of company nodes in the current `ownershipStructure` to expand (max 25)." } } }, "ExtendKybDiscoveryResponse": { "type": "object", "description": "Result of a request to extend an ownership discovery, with one decision per requested node.\nNodes are accepted or rejected individually: the request fails with `400` only when every node\nis rejected, and otherwise returns `202` with this report.", "required": [ "verificationRequestId", "estimatedCreditsTotal", "expansions" ], "properties": { "estimatedCreditsTotal": { "type": "integer", "format": "int32", "description": "Sum of `estimatedCredits` over accepted nodes only." }, "expansions": { "type": "array", "items": { "$ref": "#/components/schemas/ExpansionDecision" } }, "verificationRequestId": { "type": "string", "format": "uuid", "description": "The KYB's anchor verification request — the websocket room for `discovery-update`." } } }, "ExtractionPromptScope": { "type": "string", "enum": [ "PLATFORM", "ORGANIZATION" ] }, "ExtractionUsage": { "type": "object", "required": [ "promptTokens", "completionTokens", "totalTokens" ], "properties": { "completionTokens": { "type": "integer", "format": "int32", "minimum": 0 }, "promptTokens": { "type": "integer", "format": "int32", "minimum": 0 }, "totalTokens": { "type": "integer", "format": "int32", "minimum": 0 } } }, "FactorKey": { "oneOf": [ { "type": "object", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "fixed" ] }, "value": { "type": "string" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "answerValue" ] } } } ], "description": "A FORM factor key: a fixed string, or the submitted answer value itself (so each distinct\nanswer maps to its own FORM factor — e.g. a country select).\n\n`AnswerValue` on a `Select` field authors one `ScoreFactor` row per enumerated\n`SelectOptions.values` entry at form-sync time (`form_risk_sync::DesiredRisk::from_sections`),\nsharing the factor's multiplier, so any of those answers resolves to a real multiplier at\nscore time.\n\n**Remaining gap (D-13):** a field has no enumerable option set to author against when it is\nnot a `Select` (e.g. free-text `Text`), or when it is a `Select` with `isOtherAllowed: true`\nand the submitted answer is the free-text \"Other\" value. In those cases the emitted\n`AnswerValue` key in `FormResult.riskFactorKeys` has no matching `ScoreFactor` row, the score-time\nlookup returns `None`, and the factor's multiplier is silently skipped (undercounting the\ncontextual multiplier). Form-sync logs a warning when this applies to a saved field.", "discriminator": { "propertyName": "type" } }, "FieldControlOperation": { "type": "object", "required": [ "timestamp", "identityId", "zid", "operation" ], "properties": { "identityId": { "type": "string", "format": "uuid" }, "operation": { "$ref": "#/components/schemas/FieldControlOperationType" }, "timestamp": { "type": "string", "format": "date-time" }, "zid": { "type": "string" } } }, "FieldControlOperationType": { "oneOf": [ { "type": "object", "required": [ "markAsFalsePositive" ], "properties": { "markAsFalsePositive": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string" } } } } }, { "type": "object", "required": [ "unmarkAsFalsePositive" ], "properties": { "unmarkAsFalsePositive": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string" } } } } }, { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string" } } } } } ] }, "FieldReviewStatus": { "type": "string", "description": "Per-field review status within a clarification document request.", "enum": [ "PENDING", "APPROVED", "REJECTED" ] }, "FieldRiskConfig": { "type": "object", "description": "Risk authoring attached to a single form field (compiled to Forms-source score rows on save).", "properties": { "factors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldRiskFactor" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FieldRiskTag" } } } }, "FieldRiskFactor": { "type": "object", "required": [ "key", "multiplier" ], "properties": { "definitionKey": { "type": [ "string", "null" ], "description": "Target ScoreDefinition key. None = \"forms\" (100% backward compatible)." }, "key": { "$ref": "#/components/schemas/FactorKey" }, "multiplier": { "type": "number", "format": "double" }, "when": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, "FieldRiskTag": { "type": "object", "required": [ "tag", "weight" ], "properties": { "definitionKey": { "type": [ "string", "null" ], "description": "Target ScoreDefinition key. None = \"forms\" (100% backward compatible)." }, "tag": { "type": "string" }, "weight": { "type": "number", "format": "double" }, "when": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition", "description": "Gate on this field's answer; `None` = emit whenever the field is answered." } ] } } }, "FieldWithControl": { "type": "object", "required": [ "value", "controls" ], "properties": { "controls": { "type": "array", "items": { "$ref": "#/components/schemas/FieldControlOperation" } }, "value": { "type": "array", "items": { "type": "string" } } } }, "FileOptions": { "type": "object", "required": [ "accept", "expectedDocumentType" ], "properties": { "accept": { "type": "array", "items": { "type": "string" } }, "expectedDocumentType": { "type": "string" }, "maxCountUploads": { "type": "integer", "format": "int32", "minimum": 0 } } }, "FilterOperator": { "type": "string", "enum": [ "unfiltered", "in", "equals", "not-in", "not-equals", "contains", "gte", "lte" ] }, "Flow": { "type": "object", "required": [ "id", "name", "slug", "successUrl", "steps", "jdm" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "jdm": { "$ref": "#/components/schemas/WorkflowGraph" }, "name": { "type": "string" }, "slug": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FlowStep" } }, "successUrl": { "type": "string" }, "themeId": { "type": [ "string", "null" ], "format": "uuid", "description": "The theme this flow renders with; `None` means use the org default theme." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FlowResult": { "type": "object", "required": [ "id", "organizationId", "flowSlug", "status", "dvResults", "poaResults", "amlResults", "formResults", "kybResults", "spidResults", "phoneResults", "walletResults", "jdmData", "customData" ], "properties": { "amlResults": { "type": "array", "items": { "$ref": "#/components/schemas/AmlResult" } }, "assignedRiskTags": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedRiskTag" }, "description": "Custom risk tags conditionally assigned by the flow builder's AssignRiskTags action." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "customData": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "dvResults": { "type": "array", "items": { "$ref": "#/components/schemas/DvResult" } }, "flow": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Flow" } ] }, "flowSlug": { "type": "string" }, "formResults": { "type": "array", "items": { "$ref": "#/components/schemas/FormResult" } }, "geolocationResults": { "type": "array", "items": { "$ref": "#/components/schemas/GeolocationResult" } }, "id": { "type": "string", "format": "uuid" }, "identity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Identity" } ] }, "jdmData": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FlowStepOutput" } }, "kybResults": { "type": "array", "items": { "$ref": "#/components/schemas/KybResult" } }, "organization": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Organization" } ] }, "organizationId": { "type": "string", "format": "uuid" }, "phoneResults": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneResult" } }, "poaResults": { "type": "array", "items": { "$ref": "#/components/schemas/PoaResult" } }, "reviewSuggestion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReviewSuggestion" } ] }, "riskScorePercent": { "type": [ "integer", "null" ], "format": "int32", "description": "Composed global risk score for the flow (0–100). `None` if not yet scored." }, "spidResults": { "type": "array", "items": { "$ref": "#/components/schemas/SpidResult" } }, "status": { "$ref": "#/components/schemas/VerificationRequestStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "walletResults": { "type": "array", "items": { "$ref": "#/components/schemas/WalletResult" } } } }, "FlowStep": { "oneOf": [ { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/DvConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "DV" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/FormConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "FORM" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/PoaConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "POA" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/KybConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "KYB" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/SpidConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "SPID" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/PhoneConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "PHONE" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/WalletConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "WALLET" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/LivenessConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "LIVENESS" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/AutoOneClickKycConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "AUTO_ONE_CLICK_KYC" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/DocumentSelectionConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "DOCUMENT_SELECTION" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/GeolocationConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "GEOLOCATION" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/KybDocumentsConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "KYB_DOCUMENTS" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/KybUbosConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "KYB_UBOS" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "object", "required": [ "id", "name", "slug", "config", "flowId", "order", "type" ], "properties": { "config": { "$ref": "#/components/schemas/KybDirectorsConfig" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureUrl": { "type": [ "string", "null" ] }, "flowId": { "type": "string", "format": "uuid" }, "gotoStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "slug": { "type": "string" }, "successUrl": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "KYB_DIRECTORS" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } } ], "discriminator": { "propertyName": "type" } }, "FlowStepConfig": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/AutoOneClickKycConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "AUTO_ONE_CLICK_KYC" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/DvConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "DV" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/FormConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "FORM" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/PoaConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "POA" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/KybConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "KYB" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/WalletConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "WALLET" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/LivenessConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "LIVENESS" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/DocumentSelectionConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "DOCUMENT_SELECTION" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GeolocationConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "GEOLOCATION" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/SpidConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "SPID" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/PhoneConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "PHONE" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/KybDocumentsConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "KYB_DOCUMENTS" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/KybUbosConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "KYB_UBOS" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/KybDirectorsConfig" }, { "type": "object", "required": [ "stepType" ], "properties": { "stepType": { "type": "string", "enum": [ "KYB_DIRECTORS" ] } } } ] } ], "discriminator": { "propertyName": "stepType" } }, "FlowStepInfo": { "type": "object", "required": [ "ID", "NAME", "SLUG", "ORDER", "CONFIG", "FLOW_ID", "STEP_TYPE" ], "properties": { "CONFIG": { "$ref": "#/components/schemas/FlowStepConfig" }, "CREATED_AT": { "type": [ "string", "null" ], "format": "date-time" }, "FAILURE_URL": { "type": [ "string", "null" ] }, "FLOW_ID": { "type": "string", "format": "uuid" }, "GOTO_STEP_ID": { "type": [ "string", "null" ], "format": "uuid" }, "ID": { "type": "string", "format": "uuid" }, "NAME": { "type": "string" }, "ORDER": { "type": "integer", "format": "int32" }, "SLUG": { "type": "string" }, "STEP_TYPE": { "$ref": "#/components/schemas/FlowStepType" }, "SUCCESS_URL": { "type": [ "string", "null" ] }, "UPDATED_AT": { "type": [ "string", "null" ], "format": "date-time" } } }, "FlowStepOutput": { "oneOf": [ { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/DvStepOutput" }, "type": { "type": "string", "enum": [ "DV" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/PoaStepOutput" }, "type": { "type": "string", "enum": [ "POA" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/SpidStepOutput" }, "type": { "type": "string", "enum": [ "SPID" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/WalletStepOutput" }, "type": { "type": "string", "enum": [ "WALLET" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/PhoneStepOutput" }, "type": { "type": "string", "enum": [ "PHONE" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/FormStepOutput" }, "type": { "type": "string", "enum": [ "FORM" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/KybStepOutput" }, "type": { "type": "string", "enum": [ "KYB" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/LivenessStepOutput" }, "type": { "type": "string", "enum": [ "LIVENESS" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/AutoOneClickKycStepOutput" }, "type": { "type": "string", "enum": [ "AUTO_ONE_CLICK_KYC" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/ActionStepOutput" }, "type": { "type": "string", "enum": [ "ACTION" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/DocumentSelectionStepOutput" }, "type": { "type": "string", "enum": [ "DOCUMENT_SELECTION" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/GeolocationStepOutput" }, "type": { "type": "string", "enum": [ "GEOLOCATION" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/KybDocumentsStepOutput" }, "type": { "type": "string", "enum": [ "KYB_DOCUMENTS" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/KybUbosStepOutput" }, "type": { "type": "string", "enum": [ "KYB_UBOS" ] } } }, { "type": "object", "required": [ "data", "type" ], "properties": { "data": { "$ref": "#/components/schemas/KybDirectorsStepOutput" }, "type": { "type": "string", "enum": [ "KYB_DIRECTORS" ] } } } ], "discriminator": { "propertyName": "type" } }, "FlowStepType": { "type": "string", "enum": [ "DV", "FORM", "POA", "KYB", "SPID", "PHONE", "WALLET", "LIVENESS", "AUTO_ONE_CLICK_KYC", "DOCUMENT_SELECTION", "GEOLOCATION", "KYB_DOCUMENTS", "KYB_UBOS", "KYB_DIRECTORS" ] }, "Form": { "type": "object", "required": [ "id", "organizationId", "name", "sections" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organizationId": { "type": "string", "format": "uuid" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/FormSection" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FormAnswerSection": { "type": "object", "required": [ "name", "answers" ], "properties": { "answers": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "name": { "type": "string" } } }, "FormConfig": { "type": "object", "required": [ "formId" ], "properties": { "form": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Form" } ] }, "formId": { "type": "string", "format": "uuid" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "oneClickMaxAgeSeconds": { "type": [ "integer", "null" ], "format": "int64" } } }, "FormItem": { "oneOf": [ { "type": "object", "required": [ "content", "type" ], "properties": { "content": { "$ref": "#/components/schemas/InputField" }, "type": { "type": "string", "enum": [ "InputField" ] } } }, { "type": "object", "required": [ "content", "type" ], "properties": { "content": { "$ref": "#/components/schemas/Plaintext" }, "type": { "type": "string", "enum": [ "Plaintext" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "Separator" ] } } } ], "discriminator": { "propertyName": "type" } }, "FormReason": { "type": "string", "enum": [ "UNKNOWN" ] }, "FormResult": { "type": "object", "required": [ "id", "flowResultId", "status", "sections" ], "properties": { "assignedRiskTags": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AssignedRiskTag" }, "description": "Risk tags assigned during form scoring. `None` if not scored." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "flowResultId": { "type": "string", "format": "uuid" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "form": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Form" } ] }, "formId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FormReason" } ] }, "riskFactorKeys": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Risk factor keys matched during form scoring. `None` if not scored." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/FormSection" } }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "FormSection": { "type": "object", "required": [ "name", "label", "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FormItem" } }, "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" } } }, "FormStepOutput": { "type": "object", "description": "Form step output for workflow decisions.\n\n# Field Name Restrictions\n\nThe `fields` HashMap is flattened during serialization. Form field names must not conflict\nwith the reserved field names \"status\" and \"riskScorePercent\", as this would create duplicate\nkeys in the serialized JSON output, resulting in invalid JSON.", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus", "description": "Form submission status." } }, "additionalProperties": { "description": "Dynamic form fields flattened into the output.\nNote: Field names must not conflict with \"status\" or \"riskScorePercent\" to avoid duplicate\nkeys during serialization." } }, "GeolocationConfig": { "type": "object", "properties": { "ipValidation": { "type": "boolean", "example": "true" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "locationCrossCheck": { "type": "boolean", "example": "true" }, "vpnDetection": { "type": "boolean", "example": "true" } } }, "GeolocationCoordinates": { "type": "object", "required": [ "latitude", "longitude", "accuracy" ], "properties": { "accuracy": { "type": "number", "format": "double" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } }, "GeolocationResult": { "type": "object", "required": [ "id", "status", "vpn", "blacklistedIp", "flowResultId" ], "properties": { "blacklistedIp": { "type": "boolean" }, "country": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "deviceFingerprint": { "type": [ "string", "null" ] }, "flowResultId": { "type": "string", "format": "uuid" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "ipAddress": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" }, "vpn": { "type": "boolean" } } }, "GeolocationStepOutput": { "type": "object", "description": "Geolocation step output for workflow decisions.", "properties": { "blacklistedIp": { "type": "boolean" }, "country": { "type": [ "string", "null" ] }, "deviceFingerprint": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "vpn": { "type": "boolean" } } }, "GetApiKeyResponse": { "type": "object", "required": [ "apiKey" ], "properties": { "apiKey": { "$ref": "#/components/schemas/ZypheApiKey" } } }, "GetFlowResponse": { "type": "object", "required": [ "flow" ], "properties": { "flow": { "$ref": "#/components/schemas/Flow" } } }, "GetFormResponse": { "type": "object", "required": [ "form" ], "properties": { "form": { "$ref": "#/components/schemas/Form" } } }, "GetFullFlowResponse": { "type": "object", "required": [ "flow", "organizationId", "organizationName", "settings" ], "properties": { "flow": { "$ref": "#/components/schemas/Flow" }, "flowPartnerOrganizationsNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "organizationId": { "type": "string", "format": "uuid" }, "organizationName": { "type": "string" }, "settings": { "$ref": "#/components/schemas/Settings" }, "theme": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Theme", "description": "The theme the flow renders with: its selected theme, or the org's default. Theme is the single\nsource of truth for branding; orgs are seeded a default theme on creation, so `None` only\noccurs for legacy orgs without one (the frontend then applies its built-in defaults)." } ] } } }, "GetKybDirectorCandidatesResponse": { "type": "object", "description": "Response for `GET .../kyb/director-candidates`.\n\nRe-serves what `company-prefill` returned once, read back from the persisted provider snapshot,\nso the directors step can populate itself without the client having to carry the candidates\nacross a step transition.\n\nEmpty in the common case: officers live in a paid company block that prefill no longer buys, so\nonly historical snapshots carry them. Clients must treat an empty list as normal and collect\ndirectors from the applicant.", "required": [ "directorCandidates" ], "properties": { "directorCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/DirectorCandidate" } } } }, "GetKybDiscoveryResponse": { "type": "object", "description": "Response for `GET .../kyb/discovery`. Read-only view of the latest ownership-discovery\nGRAPH run and the ownership structure it produced.", "required": [ "status", "uboSuggestions", "available" ], "properties": { "available": { "type": "boolean", "description": "`true` when the kill switch is on and the provider is enabled." }, "errorMessage": { "type": [ "string", "null" ], "description": "Terminal-row error detail (e.g. \"graph failed validation: …\") — present when the run\ncompleted but its result could not be applied." }, "expansions": { "type": "array", "items": { "$ref": "#/components/schemas/ExpansionRecord" }, "description": "History of manual per-node expansions of the ownership graph; empty when the graph has\nnever been extended. Automatic discovery steps are listed in `waves` instead. Returned to\nyour organization only, never to the applicant." }, "ownershipStructure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OwnershipStructure", "description": "The discovered ownership graph, when a run has completed and produced a valid one." } ] }, "status": { "type": "string", "description": "`NONE` (no run) | `PENDING` | `COMPLETED` | `FAILED` — the **base** GRAPH run's status.\nPer-node expansion state is reported in `expansions` (and the `discovery-update` websocket\npush), never here: a reviewer expanding one node must not flip a finished discovery back to\n`PENDING`." }, "stoppedReason": { "type": [ "string", "null" ], "description": "Why graph traversal stopped early, when it did (e.g. `max_depth_reached`)." }, "traversal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TraversalSummary", "description": "The automatic ownership discovery's threshold, budget and spend. Absent until a discovery\nhas started. Returned to your organization only, never to the applicant." } ] }, "uboSuggestions": { "type": "array", "items": { "$ref": "#/components/schemas/UboSuggestion" }, "description": "UBO suggestions derived from the ownership graph's `isUbo` individual nodes." }, "waves": { "type": "array", "items": { "$ref": "#/components/schemas/TraversalWave" }, "description": "Steps of the automatic ownership discovery beyond its first run, oldest first; empty when\nnone were needed. Returned to your organization only, never to the applicant." } } }, "GetLivenessChallengeResponse": { "oneOf": [ { "type": "object", "description": "Active head-movement challenge liveness.", "required": [ "id", "movements", "movementDurationMs", "rotationThresholds", "rotationThresholdsDiagonal", "cardinalDominanceRatio", "video", "calibrationImage", "movementImages", "mode" ], "properties": { "calibrationImage": { "$ref": "#/components/schemas/LivenessUploadUrl" }, "cardinalDominanceRatio": { "type": "number", "format": "float" }, "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "ACTIVE" ] }, "movementDurationMs": { "type": "integer", "format": "int64" }, "movementImages": { "type": "array", "items": { "$ref": "#/components/schemas/LivenessUploadUrl" } }, "movements": { "type": "array", "items": { "$ref": "#/components/schemas/HeadMovement" } }, "rotationThresholds": { "$ref": "#/components/schemas/RotationThresholds" }, "rotationThresholdsDiagonal": { "$ref": "#/components/schemas/RotationThresholds" }, "video": { "$ref": "#/components/schemas/LivenessUploadUrl" } } }, { "type": "object", "description": "Passive selfie-only liveness. No head movements required.", "required": [ "id", "calibrationImage", "mode" ], "properties": { "calibrationImage": { "$ref": "#/components/schemas/LivenessUploadUrl" }, "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "PASSIVE" ] } } } ], "description": "Response to the `liveness-challenge` endpoint.\n\nThe `mode` discriminant tells the client which capture flow to perform:\n- `\"ACTIVE\"` — head-movement challenge; the client captures movements and\n uploads movement images + video + calibration image.\n- `\"PASSIVE\"` — selfie-only; the client uploads only a calibration image.\n No movements are required.", "discriminator": { "propertyName": "mode" } }, "GetNextStepPayload": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "description": "Wallet address. Required when `credentialType` is `WALLET`." }, "chain": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SiwxChain", "description": "Wallet chain. Required when `credentialType` is `WALLET`." } ] }, "credentialType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CredentialType", "description": "Credential type for wallet or external-ID based resolution (`WALLET` or `EXTERNAL_ID`)." } ] }, "email": { "type": [ "string", "null" ], "description": "Email address of the user whose verification progress should be queried." }, "externalId": { "type": [ "string", "null" ], "description": "External identifier. Required when `credentialType` is `EXTERNAL_ID`." } } }, "GetNextStepResponse": { "type": "object", "required": [ "isCompleted" ], "properties": { "customData": { "type": [ "object", "null" ], "description": "Custom data associated with the flow result, if one exists.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "executedActions": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutedAction" }, "description": "Actions that were automatically executed as part of flow evaluation (e.g. status transitions)." }, "flowResultId": { "type": [ "string", "null" ], "format": "uuid", "description": "The ID of the flow result record, if one exists for this user." }, "isCompleted": { "type": "boolean", "description": "Whether the user has completed all required steps in the flow." }, "nextStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep", "description": "The next incomplete step in the flow for this user, or `null` if the flow is complete." } ] } } }, "GetVerificationRequestResponse": { "type": "object", "required": [ "verificationRequest", "identity" ], "properties": { "externalId": { "type": [ "string", "null" ], "description": "External ID credential configured for this identity, if any." }, "identity": { "$ref": "#/components/schemas/Identity" }, "passkey": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VaultUnlockPasskeyData", "description": "Passkey data for vault unlock (only if passkey is configured)" } ] }, "verificationRequest": { "$ref": "#/components/schemas/VerificationRequest" }, "wallet": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WalletIdentifierPayload", "description": "Wallet credential configured for this identity, if any." } ] } } }, "HeadMovement": { "type": "string", "description": "Represents the different head movements that can be requested in a liveness challenge", "enum": [ "up", "up-right", "right", "down-right", "down", "down-left", "left", "up-left" ] }, "Identity": { "type": "object", "required": [ "id", "zid", "role", "emailVerified", "isActive", "settings" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "defaultOrganizationId": { "type": [ "string", "null" ], "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "role": { "$ref": "#/components/schemas/Role" }, "settings": { "$ref": "#/components/schemas/IdentitySettings" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "zid": { "type": "string" } } }, "IdentitySettings": { "type": "object", "required": [ "locale" ], "properties": { "lastEnvironmentIsSandbox": { "type": "boolean" }, "locale": { "$ref": "#/components/schemas/Locale" }, "synthetic": { "type": "boolean", "description": "`true` when this identity is demo/synthetic data (for example generated sample data in a\nsandbox) rather than a real end user. Never set for a real verified identity." } } }, "ImageQualityCheckResult": { "type": "object", "description": "Result of an image quality check.\n\n# Deserialization\n\nSupports both new abstract format and legacy format:\n\n**New format:**\n```json\n{ \"checkType\": \"focus\", \"result\": \"passed\", \"probability\": 97 }\n```\n\n**Legacy format (single item from 'list'):**\n```json\n{ \"type\": 1, \"result\": 0, \"probability\": 97, \"featureType\": 0, \"mean\": 0.0, \"stdDev\": 0.0 }\n```", "required": [ "checkType", "result" ], "properties": { "advisory": { "type": "boolean", "description": "Reported to the holder, excluded from the document score. Set when the check means\n\"this capture could not be read\" rather than \"this document is poor\"." }, "checkType": { "$ref": "#/components/schemas/ImageQualityCheckType" }, "details": { "description": "Why the check landed where it did — the gate that tripped, the value measured and the\nbar it missed. A failed image-quality check is what turns a holder away and asks them\nto shoot again, so it is the one result that always has to be explainable." }, "probability": { "type": [ "integer", "null" ], "format": "int32" }, "result": { "$ref": "#/components/schemas/CheckStatus" } } }, "ImageQualityCheckType": { "type": "string", "description": "Types of image quality checks.\n\n# Deserialization\n\nSupports both string format and legacy integer type codes:\n- 0 = Glare (ImageGlares)\n- 1 = Focus (ImageFocus)\n- 2 = Resolution (ImageResolution)\n- 3 = Colorness (ImageColorness)\n- 4 = Perspective (ImagePerspective)\n- 5 = Bounds (ImageBounds)\n- 6 = ScreenCapture (ImageScreenCapture)\n- 7 = Portrait (ImagePortrait)", "enum": [ "glare", "focus", "resolution", "colorness", "perspective", "bounds", "screen_capture", "portrait", "image_quality", "unknown" ] }, "InFlightExpansion": { "type": "object", "description": "One live expansion already running against this KYB result, surfaced by the preview so the\noperator can see what is in flight before choosing more nodes.", "required": [ "nodeId", "discoveryId", "startedAt" ], "properties": { "discoveryId": { "type": "string", "format": "uuid" }, "nodeId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" } } }, "InputField": { "oneOf": [ { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition", "description": "Condition that determines whether this field is required.\nWhen absent, the field is not required.\nMust be a valid Condition JSON object (see workflow engine Condition schema)." } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "date" ] }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition", "description": "Condition that determines whether this field is visible.\nWhen absent, the field is always visible." } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "text" ] }, "validationRegex": { "type": [ "string", "null" ], "description": "Optional regex pattern validated against the submitted value.\nWritten by the platform admin at form-build time; both frontend and\nbackend validate against it on submission." }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "number" ] }, "validationRegex": { "type": [ "string", "null" ], "description": "Optional regex pattern validated against the stringified submitted number." }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "textarea" ] }, "validationRegex": { "type": [ "string", "null" ], "description": "Optional regex pattern validated against the submitted value." }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "checkbox" ] }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": { "$ref": "#/components/schemas/FileOptions" }, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "file" ] }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "optionLabels", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "optionLabels": { "type": "object", "description": "Option labels for select fields: maps option value/UUID to localized labels", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "propertyNames": { "type": "string" } }, "options": { "$ref": "#/components/schemas/SelectOptions" }, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "select" ] }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, { "type": "object", "required": [ "label", "name", "options", "type" ], "properties": { "label": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "options": {}, "requiredWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] }, "risk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldRiskConfig" } ] }, "type": { "type": "string", "enum": [ "place" ] }, "value": {}, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } } ], "discriminator": { "propertyName": "type" } }, "InputFieldOptions": { "oneOf": [ { "$ref": "#/components/schemas/FileOptions" }, { "$ref": "#/components/schemas/SelectOptions" }, {} ] }, "InputFieldType": { "type": "string", "enum": [ "date", "text", "number", "textarea", "checkbox", "file", "select", "place" ] }, "InputImage": { "type": "object", "description": "Input image for document scanning.", "required": [ "value", "pageIndex", "source" ], "properties": { "pageIndex": { "$ref": "#/components/schemas/InputImagePageIndex", "description": "Page index" }, "source": { "type": "string", "description": "Image source identifier" }, "value": { "type": "string", "description": "Base64-encoded image data" } } }, "InputImagePageIndex": { "type": "string", "description": "Page index for input images.\n\nSerialized as camelCase strings for frontend compatibility:\n\"front\" and \"back\".", "enum": [ "front", "back" ] }, "KybAgenticMode": { "type": "string", "description": "How much the automated compliance review agent may do on its own (used for KYB and AML reviews).\n`DISABLED` (default): the agent does not run. `SUGGEST`: the agent reviews and records its\nrecommended approve/clear action as a suggestion for a human to act on. `AUTO_PILOT`: the agent\nmay take that action itself, subject to the platform's safety checks.", "enum": [ "DISABLED", "SUGGEST", "AUTO_PILOT" ] }, "KybCaseDecisionOutcome": { "type": "string", "description": "The outcome of a case decision: `APPROVED` or `REJECTED`. A decision is never edited once\nmade; if the case is reopened, a later decision supersedes it.", "enum": [ "APPROVED", "REJECTED" ] }, "KybCaseDecisionReasonCode": { "type": "string", "description": "Why a case was decided the way it was, as a fixed set of codes. The code classifies the\ndecision; the decision's free-text reason explains it. Defaults to `OTHER` when no code is\ngiven.", "enum": [ "CDD_INCOMPLETE", "SANCTIONS_CONFIRMED", "PEP_CONFIRMED", "ADVERSE_MEDIA", "OUTSIDE_RISK_APPETITE", "SUSPECTED_FRAUD", "APPLICANT_UNRESPONSIVE", "OTHER" ] }, "KybCaseDecisionReasonCodeField": { "$ref": "#/components/schemas/KybCaseDecisionReasonCode", "description": "What kind of reason a platform admin's moderation rests on, as a multipart text field.\n\nA newtype because the payload is multipart rather than JSON: the code's own `FromStr` reads\nexactly the `SCREAMING_SNAKE_CASE` names the wire carries everywhere else, so a value spelled\none way in JSON cannot mean something else here." }, "KybCaseDueDiligenceLevel": { "type": "string", "description": "The case engine's due-diligence level, as the manifest and the case row carry it. Mirrors the\n`kyb_case_due_diligence_level_check` DB CHECK vocabulary; the profile document uses lowercase\nlevels, which the builder maps to these values.", "enum": [ "SIMPLIFIED", "STANDARD", "ENHANCED" ] }, "KybCaseOfficersResponse": { "type": "object", "description": "A KYB case's officers: the ultimate beneficial owners and the directors the case screens and\ninvites into KYC. What the case's officer routes answer — the roster as it stands after the act.", "required": [ "caseId", "ubos", "directors" ], "properties": { "caseId": { "type": "string", "format": "uuid" }, "directors": { "type": "array", "items": { "$ref": "#/components/schemas/DirectorDefinition" } }, "ubos": { "type": "array", "items": { "$ref": "#/components/schemas/UboDefinition" } } } }, "KybCaseOrchestratorKind": { "type": "string", "description": "Which planner a manifest pins (OrchestrationSpec.kind). Mirrors the `kyb_case_orchestration_decision_kind_check` DB CHECK vocabulary.", "enum": [ "LINEAR", "JDM", "LLM" ] }, "KybCaseOrigin": { "type": "string", "description": "Who opened a KYB case.", "enum": [ "END_USER", "OPERATOR", "MIGRATION" ] }, "KybCasePlannerMode": { "type": "string", "description": "How a planner runs.\n\nFor the AI planner, which never orders runs, the mode says what becomes of what it proposes:\nnothing (`DISABLED`, it is not asked), a reviewer's decision (`SUGGEST`), or acceptance by the\nengine itself (`AUTO_PILOT`). Autopilot applies only changes that make the case stricter — the\nsame \"stricter only\" check a reviewer's acceptance goes through — and never orders, waives,\nlowers or decides anything. The linear and rules planners do not read the mode.", "enum": [ "DISABLED", "SUGGEST", "AUTO_PILOT" ] }, "KybCaseStatus": { "type": "string", "description": "The lifecycle status of a KYB case. `APPROVED`, `REJECTED` and `CANCELLED` close the case; a\nclosed case can later be reopened (for example when the applicant resubmits or a periodic\nreview is due), which moves it back to `OPEN` or `PROCESSING`.", "enum": [ "OPEN", "PROCESSING", "WAITING_INPUT", "ACTION_REQUIRED", "READY_FOR_REVIEW", "APPROVED", "REJECTED", "CANCELLED" ] }, "KybCommunication": { "type": "object", "required": [ "id", "kybResultId", "senderIdentityId", "recipientEmail", "subject", "body" ], "properties": { "body": { "type": "string" }, "documentRequestId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "kybResultId": { "type": "string", "format": "uuid" }, "recipientEmail": { "type": "string" }, "senderIdentityId": { "type": "string", "format": "uuid" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "type": "string" } } }, "KybConfig": { "type": "object", "description": "The KYB anchor step's configuration.\n\n**Deprecated document inputs.** `certificateOfIncorporation`, `articlesOfAssociation`,\n`organizationalStructureChart`, `proofOfAttorney` and `customDocuments` are still accepted on\ninput and folded into `customCountryDocuments[\"**\"]` (see\n`KybDocumentCatalog::fold_legacy_documents`); they are never serialized.", "properties": { "agentResearch": { "$ref": "#/components/schemas/AgentResearchTerms", "description": "What the KYB reviewer may look up by itself on this flow's cases, and what that may cost.\n\n**Off unless you turn it on.** With `enabled: true` the reviewer, after reading the case,\ntries to close the gaps it could not close from the case alone: the company's **registry\nrecord** and its **ownership graph**, **adverse media** on the company and its officers,\nand a **hosted web search**. Nothing is decided from it — what it finds is recorded on the\nrun and shown beside the recommendation.\n\n**What it costs.** Answers your organization already holds and that are still valid are\nadopted for free. Anything bought is bought through the same services the rest of the\nplatform buys through and is **metered at your usual prices**, inside `spendLimit`\n(in credits, per run) — a purchase that would exceed it is not made. The hosted search is\nabsorbed by the platform and bounded by `maxSearches`. Both sit under a platform ceiling;\nterms above it are refused when the flow is saved.\n\n**What leaves the platform.** The hosted search receives the company's four public\nidentifiers and nothing else: its legal name, its registration number, its country and its\nwebsite. No person's name, no document, no case text. The other tools are the ones your\ncases already use." }, "agenticMode": { "oneOf": [ { "$ref": "#/components/schemas/KybAgenticMode" } ], "default": "DISABLED" }, "allowIndividualSubject": { "type": "boolean", "description": "Offer the applicant an individual-vs-business choice at the start of the step.\n\n**Frontend marker only** — the backend persists and serves it but takes no behaviour from it,\nso nothing downstream branches on this flag. When `false` (the default) the widget skips the\nchoice and treats the subject as a **business**, which is the pre-existing behaviour for every\nflow assembled before this field existed. Default-off is what makes adding it a no-op for\nlive flows.", "default": "false", "example": "true" }, "amlAgenticMode": { "oneOf": [ { "$ref": "#/components/schemas/KybAgenticMode", "description": "Agentic AML-review mode for the company + UBO AML screenings this KYB step triggers\n(`DISABLED` | `SUGGEST` | `AUTO_PILOT`), independent of `agentic_mode` (which governs the\nKYB document review). The AML review dispatcher resolves it from the screening's step." } ], "default": "DISABLED" }, "autoSendUboKycEmail": { "type": "boolean", "description": "When `false`, the KYC invitation email is NOT automatically sent to UBOs on KYB\nsubmission; a reviewer instead triggers it on demand via the UBO reminder endpoint\n(which sends the initial invitation for un-onboarded UBOs). Defaults to `true`\n(auto-send), preserving existing behavior.", "default": "true", "example": "true" }, "collectDirectors": { "type": "boolean", "default": "false", "example": "false" }, "customCountryDocuments": { "type": "object", "description": "Your organization's KYB document configuration: overrides of platform catalog documents\nand documents of your own. Keyed by ISO 3166-1 alpha-2 country code (other ISO formats are\naccepted and normalized), or by `\"**\"` for every country without a list of its own. A\ncountry's list replaces the `\"**\"` list for that country; neither replaces the platform\ncatalog.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/KybCountryDocument" } }, "propertyNames": { "type": "string" } }, "discoveryBudgetCredits": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-verification cap (in credits) on ownership-discovery spend. `None` = platform default.\nOnly consulted when `discovery_enabled` is set. See `discovery_enabled` above for why this\nmoved here from `KybUbosConfig::discovery_budget_credits`.", "example": "3000", "minimum": 0 }, "discoveryEnabled": { "type": "boolean", "description": "Whether submitting the business information automatically starts ownership discovery:\nlooking up the company's ownership structure in company registers. Discovery spends your\norganization's credits. Defaults to `false`.", "default": "false", "example": "true" }, "documentsPerCountry": { "type": [ "object", "null" ], "description": "Read-only. The documents the applicant must upload up front, per country, as served to\nclients. One entry per country with a configured list, plus a `\"**\"` entry that is always\npresent: look up `documentsPerCountry[country] ?? documentsPerCountry[\"**\"]`. On-demand and\ndisabled documents are left out, and `validationSchema` is empty.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/KybCountryDocument" } }, "propertyNames": { "type": "string" } }, "kycFlowId": { "type": "string", "format": "uuid", "description": "Deprecated: set `kycFlowId` on the UBOs and directors steps instead, which lets each use its\nown KYC flow. May be omitted; will be removed in a future version." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "maxDirectors": { "type": "integer", "format": "int32", "default": "10", "example": "3", "minimum": 0 }, "maxFileUploads": { "type": "integer", "format": "int32", "default": "10", "example": "5", "minimum": 0 }, "maxUbos": { "type": "integer", "format": "int32", "default": "10", "example": "3", "minimum": 0 }, "orchestrator": { "oneOf": [ { "$ref": "#/components/schemas/KybCaseOrchestratorKind", "description": "Which planner the cases this flow opens are planned by: `LINEAR` (the default) presents the\nsteps in a fixed order, `JDM` applies the organization's orchestration rules\n(`/kyb-case-rules`) on top of it, and `LLM` has a model read each case against the\norganization's compliance policy and propose changes that make it stricter.\n\nPinned on each case when it opens, so changing it moves the cases opened afterwards and none\nalready open. A `JDM` flow whose organization has no enabled rule plans exactly as `LINEAR`\ndoes, with `NO_RULES` on the plan row. An `LLM` case runs in the fixed order, and what the\nmodel proposes — the owners' or directors' identity verification, a step made required, a\nhigher due-diligence level, a wider screening — waits on the case's proposals until a\nreviewer accepts or declines it." } ], "default": "LINEAR" }, "plannerMode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCasePlannerMode", "description": "What becomes of the AI planner's proposals, read only when `orchestrator` is `LLM`:\n`DISABLED` (the planner is not asked), `SUGGEST` (each waits for a reviewer — the default) or\n`AUTO_PILOT` (the engine accepts each itself, while it still makes the case stricter; a KYC\nstep for a role this flow names no KYC flow for still waits for a reviewer)." } ] }, "tinCheckEnabled": { "type": "boolean", "description": "Ask a US business for its EIN and match it, with the company name, against IRS records\nwhen the business information is submitted (a TIN check).\n\nOnly US businesses are asked: an EIN is a US identifier, and the check is a US one. A\nsubmission whose EIN and name do not match is refused, so the applicant can correct it.\nEach check that returns a verdict is billed to the organization as a TIN check\n(`creditCosts.tinCheck`), and needs the `TIN_CHECK` product. Defaults to `false`.", "default": "false", "example": "true" } } }, "KybCountryDocument": { "type": "object", "description": "One KYB document, either as a platform catalog row, as an organisation override in\n`customCountryDocuments`, or as an entry of a resolved (effective) list.\n\nIn an organisation's `customCountryDocuments` an entry whose `key` matches a platform row is a\nper-key **override** of that row: the organisation owns `required`, `onDemand`, `enabled` and a\nnon-blank `label`, while `validationSchema`, `groupKey` and `source` always come from the\nplatform row. An entry with any other key is an organisation-only document.", "required": [ "key" ], "properties": { "enabled": { "type": "boolean", "description": "`false` removes the document: it is not offered, not required and not requestable. This is\nhow an organisation drops a platform document, for one country or for every country at\nonce. Resolved lists never contain a disabled entry. Defaults to `true`." }, "groupKey": { "type": [ "string", "null" ], "description": "Groups this document with the others carrying the same value into a set of\nmutually-satisfying **alternatives**: the group counts as one requirement, and a single\nupload of any member satisfies it. Models the KYB spec's \"submit one of: Certificate of\nIncumbency | Company Register Extract | Certified Registers\". `None` (the common case)\nmeans the document stands alone and must be uploaded on its own. Platform-owned." }, "key": { "type": "string", "description": "Machine-readable key used as the document type identifier (e.g.\n`\"visura_camerale\"`, `\"certificate_of_incorporation\"`).\nUnique within (scope, country)." }, "label": { "type": "string", "description": "Human-readable label shown to the user during the KYB flow. On an organisation override a\nblank label keeps the platform's own label, which is why a bare `{ key, enabled: false }`\nentry is a valid override." }, "onDemand": { "type": "boolean", "description": "When `true`, the document is NOT demanded upfront (excluded from the required-document\ngate) and is instead requested on demand by a reviewer during review. Defaults to\n`false`." }, "required": { "type": "boolean", "description": "Whether upload of this document is mandatory for KYB approval.\nDefaults to `true`." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDocumentSource", "description": "Whether the document comes from the platform catalog (`platform`) or was added by your\norganization (`organization`). Set by the server on resolved document lists; ignored on\ninput." } ] }, "validationSchema": { "description": "JSON Schema of extracted facts. `properties` defines fields, `x-schemaVersion` versions\nthe contract, and `x-validationRules` carries acceptance criteria outside the output data.\nPlatform-owned, and emptied (`{}`) in every map served to a client." } } }, "KybDecisionResponse": { "allOf": [ { "$ref": "#/components/schemas/KybResult" }, { "type": "object", "properties": { "decisionProposal": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DecisionProposalRecorded" } ] } } } ], "description": "What the legacy KYB decision routes answer — the console's approve and the two SDK routes.\n\nThe `KybResult` is flattened, so a decision that closed the case serializes **byte for byte**\nwhat these routes have always returned (legacy paths and payloads unchanged) and\n`decisionProposal` is absent. A decision the matrix turned into a proposal answers `202` with\nthe UNCHANGED result plus the block: the caller sees that its act was recorded, that the file\ndid not move, and who is being waited on." }, "KybDirectorsConfig": { "type": "object", "description": "Configuration for the `KYB_DIRECTORS` satellite step.\n\nCarries the director declaration settings previously bundled into the monolithic\n`KybConfig` (gated there by `collect_directors: bool`). The existence of this step\nreplaces that boolean. `kyb_step_id` points at the anchor `KYB` step.\n\n`kyc_flow_id` is a copy independent from `KybUbosConfig.kyc_flow_id` — this enables\na *different* KYC flow for directors than for UBOs, a new capability.", "required": [ "kybStepId" ], "properties": { "kybStepId": { "type": "string", "format": "uuid", "description": "The anchor KYB step this directors satellite belongs to." }, "kycFlowId": { "type": "string", "format": "uuid", "description": "The KYC flow directors are invited into to verify their identity. Only used when\n`requireKyc` is `true`; may be omitted otherwise." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "maxDirectors": { "type": "integer", "format": "int32", "default": "10", "example": "3", "minimum": 0 }, "requireKyc": { "type": "boolean", "description": "Whether each declared director must complete a KYC flow (`true`, the default) or is only\nscreened by name. When `true`, an email address is required for each director and they are\ninvited into `kycFlowId`. Independent of the UBOs setting: a flow may verify its UBOs while\nscreening its directors by name only, or the reverse.", "default": "true", "example": "false" } } }, "KybDirectorsStepOutput": { "type": "object", "description": "KYB directors satellite step output for workflow decisions.", "required": [ "directorCount", "allDirectorsVerified" ], "properties": { "allDirectorsVerified": { "type": "boolean" }, "directorCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "KybDiscoveryRequestStatus": { "type": "string", "description": "Where a KYB discovery request (a company-registry lookup) stands: `PENDING`, `COMPLETED` or `FAILED`.", "enum": [ "PENDING", "COMPLETED", "FAILED" ] }, "KybDocumentCheckOverride": { "type": "object", "description": "A reviewer's correction of one document check verdict.", "required": [ "overriddenBy", "overriddenAt" ], "properties": { "modelStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDocumentCheckStatus", "description": "What the latest comparison's model verdict is; `None` when it gave none (a failed\nextraction's document type)." } ] }, "overriddenAt": { "type": "string", "format": "date-time" }, "overriddenBy": { "type": "string", "format": "uuid" } } }, "KybDocumentCheckStatus": { "type": "string", "description": "Verdict of one supplementary document check (a non-business extracted field, or the\ndocument's `acceptanceRules`). Reasons are never exposed; they stay in the S3 history payload.", "enum": [ "match", "mismatch", "notFound", "notCheckable" ] }, "KybDocumentCheckSummary": { "type": "object", "description": "Reviewer-facing summary of one uploaded document in the latest cross-check: what it was\nclassified as, whether extraction succeeded, and the status of every document check.", "required": [ "extractionId", "sourceS3Key", "status", "checks" ], "properties": { "checks": { "type": "object", "description": "Check name (`acceptanceRules`, `directors`, …) → verdict. Empty for a failed extraction.", "additionalProperties": { "$ref": "#/components/schemas/KybDocumentCheckStatus" }, "propertyNames": { "type": "string" } }, "definitionKey": { "type": [ "string", "null" ], "description": "The catalog key the upload was classified as; `None` for an unclassified upload." }, "definitionLabel": { "type": [ "string", "null" ] }, "documentType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDocumentCheckStatus", "description": "Whether the document is the kind of document it was submitted as: `match`, `mismatch`\n(clearly another kind of document) or `notCheckable`. `None` when nothing judged it — an\nunclassified upload, a failed extraction, or one extracted before this verdict existed." } ] }, "errorCode": { "type": [ "string", "null" ], "description": "Stable failure code (`UNSUPPORTED_MEDIA`, `INVALID_EXTRACTION`, …) when `status` is `FAILED`." }, "extractionId": { "type": "string", "format": "uuid" }, "overrides": { "type": "object", "description": "The checks a reviewer corrected, by name (`@documentType` for the document-type verdict).\n`documentType` and `checks` already carry the corrected status; this says what the model\nsaid and who changed it.", "additionalProperties": { "$ref": "#/components/schemas/KybDocumentCheckOverride" }, "propertyNames": { "type": "string" } }, "sourceS3Key": { "type": "string" }, "status": { "$ref": "#/components/schemas/KybDocumentExtractionStatus" } } }, "KybDocumentExtractionStatus": { "type": "string", "description": "Outcome of one per-document extraction (`KybDocumentExtraction.status`).", "enum": [ "COMPLETED", "FAILED" ] }, "KybDocumentRequest": { "type": "object", "required": [ "id", "kybResultId", "requestedByIdentityId", "documentName", "requestType", "status" ], "properties": { "clarificationFields": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Clarification field keys requested for review (for clarification requests only)." }, "clarificationResponse": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BusinessInformationClarificationResponse", "description": "Parsed clarification response submitted by the client. Populated only on\nbusiness-information clarification document requests after the client has responded." } ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "documentName": { "type": "string" }, "fieldStatuses": { "type": [ "object", "null" ], "description": "Per-field review statuses for clarification requests.\nKeys are field names (e.g. \"companyName\"), values are the review status for that field.", "additionalProperties": { "$ref": "#/components/schemas/FieldReviewStatus" }, "propertyNames": { "type": "string" } }, "fulfilledAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kybResultId": { "type": "string", "format": "uuid" }, "presignedUrl": { "type": [ "string", "null" ] }, "previousValues": { "type": [ "object", "null" ], "description": "Snapshot of old business information field values before the client submitted updated values.\nKeys are field names, values are the previous string values.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "requestType": { "$ref": "#/components/schemas/KybDocumentRequestType", "description": "The type of this document request." }, "requestedByIdentityId": { "type": "string", "format": "uuid" }, "reviewReason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybDocumentReviewReason", "description": "Moderator review note or structured clarification response payload." } ] }, "status": { "$ref": "#/components/schemas/KybDocumentRequestStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "uploadedFilename": { "type": [ "string", "null" ] }, "uploadedS3Key": { "type": [ "string", "null" ] } } }, "KybDocumentRequestStatus": { "type": "string", "enum": [ "PENDING", "UPLOADED", "APPROVED", "REJECTED" ] }, "KybDocumentRequestType": { "type": "string", "description": "The type of a KYB document request.\n\n- `Standard` — operator requests a named document (e.g. certificate of incorporation). The client uploads a file.\n- `Clarification` — operator requests the client to re-confirm or update specific business information fields.\n Supports per-field review via `field_statuses`.\n- `UboDeclaration` — reopens the `KYB_UBOS` satellite for a fresh applicant declaration. Used to\n regress a discovery-backed flow's UBOs part back to awaiting-client when the graph produced\n nothing usable.\n- `DirectorDeclaration` — same as `UboDeclaration`, for the `KYB_DIRECTORS` satellite.\n- `OwnershipConfirmation` — opened by a reopening (a quality review's disagreement or the\n periodic review), never by hand: the company is asked to confirm, through the existing request\n link, that the owners and officers on file are still the ones there are. The answer lands as\n the applicant's own assertions; while it is open the case waits on the applicant, and\n deciding without it takes an exception like any other open request.", "enum": [ "STANDARD", "CLARIFICATION", "UBO_DECLARATION", "DIRECTOR_DECLARATION", "OWNERSHIP_CONFIRMATION" ] }, "KybDocumentReviewReason": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/BusinessInformationClarificationResponse" } ] }, "KybDocumentSource": { "type": "string", "description": "Where an effective KYB document entry comes from.\n\nSet by resolution (`KybDocumentCatalog::resolve_for_country`), never trusted from a stored\nconfig: an entry whose `key` matches a platform `DocumentDefinitions` row is `platform`, however\nthe organisation overrode it, and every other entry is `organization`.", "enum": [ "platform", "organization" ] }, "KybDocumentsConfig": { "type": "object", "description": "Configuration for the `KYB_DOCUMENTS` satellite step.\n\nCarries the document requirements previously bundled into the monolithic `KybConfig`.\n`kyb_step_id` points at the anchor `KYB` step (same pattern as `LivenessConfig.document_step_id`).\n\n**Deprecated document inputs.** `certificateOfIncorporation`, `articlesOfAssociation`,\n`organizationalStructureChart`, `proofOfAttorney` and `customDocuments` are still accepted on\ninput and folded into `customCountryDocuments[\"**\"]` (see\n`KybDocumentCatalog::fold_legacy_documents`); they are never serialized.", "required": [ "kybStepId" ], "properties": { "customCountryDocuments": { "type": "object", "description": "The organisation's document configuration. See `KybConfig::custom_country_documents`, whose\nsemantics this mirrors.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/KybCountryDocument" } }, "propertyNames": { "type": "string" } }, "documentsPerCountry": { "type": [ "object", "null" ], "description": "The effective upfront documents per country, populated at rehydration time (see\n`KybConfig::documents_per_country`, whose semantics this mirrors).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/KybCountryDocument" } }, "propertyNames": { "type": "string" } }, "kybStepId": { "type": "string", "format": "uuid", "description": "The anchor KYB step this documents satellite belongs to." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "maxFileUploads": { "type": "integer", "format": "int32", "default": "10", "example": "5", "minimum": 0 } } }, "KybDocumentsStepOutput": { "type": "object", "description": "KYB documents satellite step output for workflow decisions.\n\nThin output for the `KYB_DOCUMENTS` step (see `FlowStepOutput::Kyb` for the KYB\naggregate carried on the anchor step).", "required": [ "uploadedCount", "requiredSatisfied" ], "properties": { "requiredSatisfied": { "type": "boolean" }, "uploadedCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "KybMetadata": { "type": "object", "description": "The KYB result metadata bag. Empty by default.", "properties": { "dueDiligenceLevel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DueDiligenceLevel", "description": "How intensively this business must be investigated before approval: `simplified`,\n`standard` or `enhanced`. When absent, no choice has been made and `standard` applies." } ] }, "ownershipStructure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OwnershipStructure", "description": "The ownership graph, when an admin has recorded one." } ] }, "registryStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompanyStatus", "description": "The registry's lifecycle state for the subject company, recorded by the business-information\ncross-check from whichever register it consulted. `None` when no lookup produced one —\neither nothing matched, or the provider serving that country does not report it. The\napproval guard reads this, so absence stays indistinguishable from \"not checked\" and is\nnever treated as a clean bill of health." } ] }, "screeningStrategy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ScreeningStrategy", "description": "Which people must be identified and screened before this business can be approved: `ubo`,\n`directors` or `uboAndDirectors`. When absent, no choice has been made and `ubo` applies." } ] } }, "additionalProperties": { "description": "Any other top-level key. Opaque to the backend, passed through verbatim." } }, "KybPurchasedDocumentStatus": { "type": "string", "description": "Where a document bought from a company register stands: `PENDING`, `COMPLETED` or `FAILED`.", "enum": [ "PENDING", "COMPLETED", "FAILED" ] }, "KybRatingLevel": { "type": "string", "description": "A company's risk level, from lowest to highest severity: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`.", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "KybResult": { "type": "object", "description": "The legacy KYB result: a KYB case in the format used before KYB cases existed.\n\n**Deprecated.** Still returned by the flow-result, verification-request and KYB endpoints and\nby `LEGACY_V1` webhooks, unchanged. Its `id` is the id of its KYB case: to migrate, read the case\nat `/sdk/organizations/{organizationId}/kyb-cases/{id}`, or use the `kybCase` field of a `V2`\nwebhook.", "required": [ "id", "status", "pepAndSanctionsStatus" ], "properties": { "assignedAt": { "type": [ "string", "null" ], "format": "date-time" }, "assignedToIdentityId": { "type": [ "string", "null" ], "format": "uuid" }, "businessInformation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BusinessInformation" } ] }, "businessInformationVerification": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/BusinessInfoFieldVerification" }, "propertyNames": { "type": "string" } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "directorDefinitions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DirectorDefinition" } }, "documentChecks": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/KybDocumentCheckSummary" }, "description": "One entry per uploaded document of the latest cross-check, with the status of every\ndocument check (acceptance rules first among them). Populated on the same reviewer-facing\nreads as `effective_required_documents`; `None` elsewhere and before any cross-check ran." }, "documentUploads": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DocumentUpload" } }, "effectiveRequiredDocuments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/KybCountryDocument" }, "description": "The effective list of required KYB documents for this result's country.\n\nResolved by `KybDocumentCatalog::resolve_for_country` using the full\npriority chain: platform DB definitions → org-admin `custom_country_documents`\n→ global legacy fields. `None` until explicitly set by a caller with DB access\n(e.g. the MCP `get_kyb_result` tool). Not computed in the `From` conversion." }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "fundedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object", "description": "Admin-curated metadata. Organizations read it; only admins write it.\nEmpty (`{}`) when nothing has been recorded." }, "nextAction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NextAction" } ] }, "pepAndSanctionsStatus": { "$ref": "#/components/schemas/PepAndSanctionsStatus" }, "reason": { "type": [ "string", "null" ] }, "report": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ModerationResultStatus" }, "uboDefinitions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UboDefinition" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } }, "deprecated": true }, "KybStepOutput": { "type": "object", "description": "KYB (Know Your Business) step output for workflow decisions.", "required": [ "status" ], "properties": { "amlAdverseMedia": { "type": [ "boolean", "null" ], "description": "Whether the company's screening found adverse media." }, "amlPep": { "type": [ "boolean", "null" ] }, "amlRiskScorePercent": { "type": [ "integer", "null" ], "format": "int32" }, "amlSanctions": { "type": [ "boolean", "null" ] }, "businessName": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "moderationStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ModerationResultStatus" } ] }, "pepAndSanctionsStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PepAndSanctionsStatus" } ] }, "registrationNumber": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "KybSubjectRef": { "oneOf": [ { "type": "object", "required": [ "personId", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "PERSON" ] }, "personId": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "companyKey", "kind" ], "properties": { "companyKey": { "type": "string" }, "kind": { "type": "string", "enum": [ "COMPANY" ] } } } ], "description": "A subject the analyst layer keeps a row about: an organization-wide person, or a company by its\nnormalized key — the same two subjects an attestation is about.\n\nOn the wire it is tagged, `{ \"kind\": \"PERSON\", \"personId\": … }` or\n`{ \"kind\": \"COMPANY\", \"companyKey\": … }`, so a client cannot send a person id and a company key\nat once, which the tables' subject CHECK would refuse anyway.", "discriminator": { "propertyName": "kind" } }, "KybUbosConfig": { "type": "object", "description": "Configuration for the `KYB_UBOS` satellite step.\n\nCarries the UBO declaration + child-KYC invitation settings previously bundled\ninto the monolithic `KybConfig`. `kyb_step_id` points at the anchor `KYB` step.", "required": [ "kybStepId" ], "properties": { "autoSendUboKycEmail": { "type": "boolean", "description": "When `false`, the KYC invitation email is NOT automatically sent to UBOs on\nsubmission; a reviewer instead triggers it on demand via the UBO reminder\nendpoint (which sends the initial invitation for un-onboarded UBOs). Defaults to\n`true` (auto-send), preserving existing behavior.", "default": "true", "example": "true" }, "kybStepId": { "type": "string", "format": "uuid", "description": "The anchor KYB step this UBOs satellite belongs to." }, "kycFlowId": { "type": "string", "format": "uuid", "description": "The KYC flow UBOs are invited into to verify their identity. Only used when `requireKyc`\nis `true`; may be omitted otherwise." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "maxUbos": { "type": "integer", "format": "int32", "default": "10", "example": "3", "minimum": 0 }, "requireKyc": { "type": "boolean", "description": "Whether a declared UBO must go through child KYC, or is collected for AML name screening\nonly.\n\n`true` (the default, and the behaviour of every flow built before this field existed): the\nwidget demands an email address for each UBO — an email is what a KYC invitation is\naddressed to — and the backend resolves `kyc_flow_id` to send and schedule those\ninvitations.\n\n`false`: the widget collects a UBO by name alone and asks for no email; `kyc_flow_id` is\nthen meaningless and may be omitted. The backend must NOT resolve a KYC entry point in that\ncase — `resolve_kyc_flow_entry_point` is a hard error when the flow does not exist, so an\nunguarded resolution would fail the entire UBO submission of a flow that legitimately has\nno KYC flow at all.\n\nNothing downstream of submission needs to branch on this: the readiness gate\n(`KybService::are_all_ubos_verified`, `check_kyb_result_approval_readiness`) already keys\noff each UBO's *own* email presence — email-bearing UBOs need a completed child KYC,\nname-only UBOs need a clean name-AML screening — so an entirely email-less declaration set\nresolves through the name-only branch without consulting any config.", "default": "true", "example": "false" } } }, "KybUbosStepOutput": { "type": "object", "description": "KYB UBOs satellite step output for workflow decisions.", "required": [ "uboCount", "allUbosVerified" ], "properties": { "allUbosVerified": { "type": "boolean" }, "uboCount": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ListOrganizationFlowResultsResponse": { "type": "object", "required": [ "page", "totalCount" ], "properties": { "page": { "type": "array", "items": { "$ref": "#/components/schemas/FlowResult" } }, "totalCount": { "type": "integer", "format": "int64", "minimum": 0 } } }, "LivenessConfig": { "type": "object", "required": [ "documentStepId" ], "properties": { "biometricCheckEnabled": { "type": [ "boolean", "null" ], "description": "When `true` the liveness step also performs a biometric match against the stored portrait.\nSet to `false` to keep the liveness UX but skip biometric verification." }, "documentStepId": { "type": "string", "format": "uuid" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"en_button_label\": \"Next step\" }" }, "maxAttempts": { "type": [ "integer", "null" ], "format": "int32", "example": "5", "minimum": 0 }, "passiveLiveness": { "type": "boolean", "description": "When `true`, passive liveness (selfie-only, no head movements) is used instead\nof active challenge-based liveness. Configured by admin only. Defaults to `false`." }, "performAntispoof": { "type": [ "boolean", "null" ] }, "skipIfPreviousLivenessPassed": { "type": [ "boolean", "null" ], "description": "When enabled (the default when unset), the liveness step is skipped during a\none-click KYC reuse if the reused document verification result already carries a\nsuccessful liveness outcome (`processAdditionalData.rawLivenessData`).\n\nThe reused liveness must originate from a flow of the same organization, unless\nthe one-click was authenticated via passkey — in which case cross-organization\nreuse is allowed. Set to `false` to always require a fresh liveness." }, "thresholds": { "type": [ "object", "null" ], "additionalProperties": { "type": "number", "format": "float" }, "propertyNames": { "type": "string", "enum": [ "portraitMatchPercent", "biometricMatchPercent" ] } } } }, "LivenessConfigThreshold": { "type": "string", "enum": [ "portraitMatchPercent", "biometricMatchPercent" ] }, "LivenessStepOutput": { "type": "object", "description": "Liveness check step output for workflow decisions.", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "LivenessUploadUrl": { "type": "object", "required": [ "presignedUrl", "s3Key" ], "properties": { "presignedUrl": { "type": "string" }, "s3Key": { "type": "string" } } }, "LlmDocumentType": { "type": "string", "enum": [ "PASSPORT", "PASSPORT_DIPLOMATIC", "PASSPORT_OFFICIAL", "PASSPORT_ORDINARY", "NATIONAL_ID", "RESIDENCE_PERMIT", "ALIEN_ID", "VISA", "DRIVERS_LICENSE", "OTHER", "UNKNOWN" ] }, "Locale": { "type": "string", "description": "Locale identifier", "enum": [ "en", "it", "de", "es", "fr", "hi", "id", "pt" ] }, "LogicalOperator": { "type": "string", "description": "Logical operators for workflow branching.", "enum": [ "BRANCH", "SWITCH", "MERGE", "PARALLEL_SPLIT", "PARALLEL_JOIN" ] }, "ManualReviewResultStatus": { "type": "string", "enum": [ "approved", "rejected", "failed" ] }, "ModerationResultStatus": { "type": "string", "enum": [ "ACQUIRING", "ENRICHING", "PENDING_MODERATION", "REVIEW_REQUIRED", "SUCCESS", "FAILED" ] }, "ModerationResultStatusField": { "$ref": "#/components/schemas/ModerationResultStatus" }, "NextAction": { "type": "string", "enum": [ "CLIENT", "RM", "COMPLIANCE", "SUPPORT", "FUNDED", "DENIED" ] }, "NodePosition": { "type": "object", "description": "Position of a node in the visual editor.", "required": [ "x", "y" ], "properties": { "x": { "type": "number", "format": "double", "description": "X coordinate" }, "y": { "type": "number", "format": "double", "description": "Y coordinate" } } }, "NormalizedEmail": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "user@example.com" } } }, "OcrSides": { "type": "object", "required": [ "front", "back" ], "properties": { "back": { "type": "boolean" }, "front": { "type": "boolean" } } }, "Organization": { "type": "object", "required": [ "id", "slug", "name", "registrationNumber", "country", "address", "website", "email", "phone", "creationSource" ], "properties": { "address": { "type": "string" }, "country": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "creationSource": { "$ref": "#/components/schemas/CreationSource" }, "email": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "industry": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "phone": { "type": "string" }, "postcode": { "type": [ "string", "null" ] }, "registrationNumber": { "type": "string" }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Settings" } ] }, "slug": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "website": { "type": "string" } } }, "OrganizationInvite": { "type": "object", "required": [ "id", "email", "organizationId", "used", "validBefore", "role" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "email": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "inviter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrganizationInviterInfo" } ] }, "organizationId": { "type": "string", "format": "uuid" }, "revoked": { "type": [ "boolean", "null" ] }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "role": { "$ref": "#/components/schemas/Role" }, "used": { "type": "boolean" }, "validBefore": { "type": "string", "format": "date-time" } } }, "OrganizationInviterInfo": { "type": "object", "required": [ "role" ], "properties": { "email": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/Role" } } }, "OwedBy": { "oneOf": [ { "type": "object", "description": "The company being verified: a document, an answer, a confirmation.", "required": [ "party" ], "properties": { "party": { "type": "string", "enum": [ "APPLICANT" ] } } }, { "type": "object", "description": "Somebody at the organization.", "required": [ "party" ], "properties": { "identityId": { "type": [ "string", "null" ], "format": "uuid" }, "party": { "type": "string", "enum": [ "REVIEWER" ] }, "role": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Role" } ] } } }, { "type": "object", "description": "The reviewing agent, where the flow's agentic mode has one working the case.", "required": [ "party" ], "properties": { "party": { "type": "string", "enum": [ "AGENT" ] } } }, { "type": "object", "description": "An outside provider: a register, a screening source, a document check.", "required": [ "party" ], "properties": { "party": { "type": "string", "enum": [ "PROVIDER" ] } } }, { "type": "object", "description": "Zyphe itself — an owed closing effect, a run the platform has to finish.", "required": [ "party" ], "properties": { "party": { "type": "string", "enum": [ "PLATFORM" ] } } } ], "description": "Who owes the next act.\n\n`Reviewer` carries the role the matrix named and the identity the subject is assigned to where\nthere is one; both are optional because \"a reviewer\" is a complete answer when the case names\nnobody in particular. The kind of principal is NOT read here: that is kept to the confirmation\nrule and the quality review.", "discriminator": { "propertyName": "party" } }, "OwnershipBirthDate": { "type": "object", "required": [ "day", "month", "year" ], "properties": { "day": { "type": "integer", "format": "int32", "minimum": 0 }, "month": { "type": "integer", "format": "int32", "minimum": 0 }, "year": { "type": "integer", "format": "int32" } } }, "OwnershipCompany": { "type": "object", "required": [ "id", "legalName", "countryCode" ], "properties": { "countryCode": { "type": "string" }, "id": { "type": "string" }, "legalName": { "type": "string" } } }, "OwnershipContinuation": { "type": "object", "description": "Why an ownership node was left unexplored, and what continuing discovery from it would take.", "properties": { "accumulatedOwnership": { "type": [ "number", "null" ], "format": "double", "description": "This node's stake in the **root**, as a fraction in `0.0..=1.0` (so `0.144` is 14.4%).\nUndefined — and therefore absent — whenever any upstream hop lacked a percentage, which is\nexactly the case an automatic traversal must fail *open* on rather than prune." }, "depth": { "type": [ "integer", "null" ], "format": "int32", "description": "How many hops from the root this node sits at.", "minimum": 0 }, "estimatedCost": { "type": [ "integer", "null" ], "format": "int64", "description": "What one continuation from this node is expected to cost, in provider credit cents. The\nwire key is `estimatedCost`; renamed on our side so the field says its unit, matching\nevery other cents-denominated field in the platform." }, "reason": { "type": "string", "description": "Why the traversal stopped here — `\"budget\"` in every case observed so far.\n\nDefaulted because it is the only required field on this struct, and the cost of it being\nabsent is wildly out of proportion to its value: `get_discovery_status` parses the stored\n`KybMetadata` with `.ok()`, so one continuation hint missing a `reason` would discard the\n**entire** ownership structure — a graph the organization paid for, hidden by the absence of\na label we only ever use for display." } } }, "OwnershipEdge": { "type": "object", "required": [ "id", "fromId", "toId", "percentage" ], "properties": { "fromId": { "type": "string" }, "id": { "type": "string" }, "percentage": { "type": "number", "format": "double" }, "source": { "type": [ "string", "null" ] }, "toId": { "type": "string" } } }, "OwnershipEntity": { "oneOf": [ { "type": "object", "required": [ "company", "type" ], "properties": { "company": { "$ref": "#/components/schemas/OwnershipCompany" }, "type": { "type": "string", "enum": [ "company" ] } } }, { "type": "object", "required": [ "individual", "type" ], "properties": { "individual": { "$ref": "#/components/schemas/OwnershipIndividual" }, "type": { "type": "string", "enum": [ "individual" ] } } } ], "description": "The provider's wire shape `{ \"type\": \"company\", \"company\": { ... } }`, expressed as an\ninternally tagged enum: the `type` tag selects the variant, so a tag that disagrees with\nits payload — or an unknown tag — is unrepresentable and rejected at deserialization.", "discriminator": { "propertyName": "type" } }, "OwnershipFlags": { "type": "object", "description": "Per-node flags. `status` is free-form for the same reason as `stopped_reason`; the\nreference provider already emits `found`, `budget_truncated`, `placeholder`, and\n`coverage_unavailable`, and a fifth value must not fail a write.\n\n`status` is the load-bearing truncation signal: an unexplored node must render\ndifferently from a resolved one, so \"no UBO found\" is never read as \"no UBO exists\".", "required": [ "status" ], "properties": { "isRoot": { "type": "boolean" }, "isUbo": { "type": "boolean" }, "isUboProxy": { "type": "boolean" }, "status": { "type": "string" } } }, "OwnershipIndividual": { "type": "object", "required": [ "name" ], "properties": { "birthDate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OwnershipBirthDate" } ] }, "name": { "$ref": "#/components/schemas/OwnershipIndividualName" }, "nationality": { "type": [ "string", "null" ] } } }, "OwnershipIndividualName": { "type": "object", "required": [ "fullName" ], "properties": { "fullName": { "type": "string" } } }, "OwnershipNode": { "allOf": [ { "$ref": "#/components/schemas/OwnershipEntity" }, { "type": "object", "required": [ "nodeId", "flags" ], "properties": { "continuation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OwnershipContinuation", "description": "For a node that was not explored because the discovery budget ran out: why it stopped,\nand what exploring further from it would cost. Present only on nodes whose status is\n`budget_truncated`." } ] }, "flags": { "$ref": "#/components/schemas/OwnershipFlags" }, "nodeId": { "type": "string" }, "source": { "description": "Where this node's data came from, as reported by the company-registry data provider: which\nregister, or `ai_analysis` of named filings (a weaker level of assurance). Absent for older\nownership structures and for nodes the provider did not attribute." }, "totalOwnershipPercentage": { "type": [ "number", "null" ], "format": "double" } } } ], "description": "A graph node. `entity` is flattened and tagged on `type`, so a `company`-typed node\ncannot exist without company data." }, "OwnershipStructure": { "type": "object", "description": "An ownership graph: who owns the subject company, transitively.", "required": [ "nodes", "edges" ], "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/OwnershipEdge" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/OwnershipNode" } }, "stoppedReason": { "type": [ "string", "null" ], "description": "Why graph traversal stopped, when it stopped early (e.g. `max_depth_reached`).\nFree-form: provider-defined and admin-entered, so a closed enum would reject\nan unrecognised value at write time." } } }, "Pagination": { "type": "object", "properties": { "filter": { "type": "string", "example": "createdAt:in:2025-01-01,2025-01-02;updatedAt:gt:2025-01-02" }, "skip": { "type": "integer", "format": "int32", "example": "0", "minimum": 0 }, "sort": { "type": "string", "example": "createdAt:desc" }, "take": { "type": "integer", "format": "int32", "example": "100", "minimum": 0 } } }, "PepAndSanctionsStatus": { "type": "string", "enum": [ "REVIEW", "PENDING", "SUCCESS", "FAILED", "IN_PROGRESS" ] }, "PepAndSanctionsStatusField": { "$ref": "#/components/schemas/PepAndSanctionsStatus" }, "PersonalData": { "type": "object", "required": [ "givenName", "surname", "dateOfBirth", "nationality", "gender" ], "properties": { "dateOfBirth": { "type": "string" }, "gender": { "type": "string" }, "givenName": { "type": "string" }, "nationality": { "type": "string" }, "personalNumber": { "type": "string" }, "placeOfBirth": { "type": "string" }, "surname": { "type": "string" } } }, "PhoneConfig": { "type": "object", "properties": { "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" } } }, "PhoneResult": { "type": "object", "required": [ "id", "status", "phoneNumberLast4", "flowResultId" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "documentId": { "type": [ "string", "null" ], "format": "uuid" }, "flowResultId": { "type": "string", "format": "uuid" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "phoneNumberE164": { "type": [ "string", "null" ] }, "phoneNumberLast4": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "PhoneStepOutput": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "Plaintext": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "visibleWhen": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition" } ] } } }, "PoaConfig": { "type": "object", "required": [ "documentFilter" ], "properties": { "documentFilter": { "type": "array", "items": { "$ref": "#/components/schemas/PoaDocumentType" } }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" }, "maxAgeDays": { "type": "integer", "format": "int32", "example": "90", "minimum": 0 } } }, "PoaDocumentType": { "type": "string", "enum": [ "PAY_SLIP", "UTILITY_BILL", "FINANCIAL_DOCUMENT", "RECEIPT", "INVOICE", "BANK_DOCUMENT", "TAX_CLEARANCE_CERTIFICATE", "HOUSEHOLD_REGISTER", "CERTIFICATE_OF_RESIDENCE", "DLDV", "OTHER" ] }, "PoaReason": { "type": "string", "enum": [ "UNKNOWN", "DOCUMENT_TYPE_NOT_ALLOWED", "NAME_MISMATCH", "DATE_TOO_OLD", "INVALID_DOCUMENT", "UNRECOGNIZED_ADDRESS" ] }, "PoaResult": { "type": "object", "required": [ "id", "status", "createdAt", "updatedAt" ], "properties": { "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "documentId": { "type": [ "string", "null" ], "format": "uuid" }, "documentType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PoaDocumentType" } ] }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PoaReason" } ] }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": "string", "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "PoaStepOutput": { "type": "object", "required": [ "status" ], "properties": { "documentAgeDays": { "type": [ "integer", "null" ], "format": "int64" }, "documentType": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "PortraitAgeRange": { "type": "object", "description": "An estimated age bracket, in whole years.", "required": [ "low", "high" ], "properties": { "high": { "type": "integer", "format": "int32", "minimum": 0 }, "low": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PortraitEstimate": { "type": "object", "description": "What face analysis estimated from the portrait printed on the identity document: whether it\nis a face, the apparent age range and the perceived gender. Recorded for every scan that\nfound a portrait, and used as the evidence behind the portrait-attribute security checks.", "required": [ "faceConfidence" ], "properties": { "ageRange": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PortraitAgeRange", "description": "Estimated age bracket in whole years, inclusive at both ends. An estimate of how old the\nperson *looks* in the photo — which is how old they were when it was taken, not today." } ] }, "faceConfidence": { "type": "number", "format": "float", "description": "The service's confidence (0-100) that the selected crop is a face at all." }, "gender": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PortraitGenderEstimate", "description": "Perceived gender, as the service predicts it from appearance." } ] } } }, "PortraitGenderEstimate": { "type": "object", "description": "A perceived-gender prediction with the service's confidence in it.", "required": [ "value", "confidence" ], "properties": { "confidence": { "type": "number", "format": "float", "description": "0-100." }, "value": { "type": "string", "description": "`M` or `F` — the two values the service can predict, in the same notation as the\ndocument's printed sex so the two read side by side." } } }, "PrefillKybCompanyPayload": { "type": "object", "description": "Payload for `POST .../kyb/company-prefill`.", "required": [ "country", "candidateId" ], "properties": { "candidateId": { "type": "string", "description": "The `id` of a `CompanySearchCandidate` chosen by the applicant." }, "country": { "type": "string", "description": "ISO country (any alpha-2/alpha-3/numeric/name form)." }, "subdivision": { "type": [ "string", "null" ], "description": "ISO 3166-2 subdivision, required when `country` is the US. See `CompanySearchQuery`." } } }, "PrefillKybCompanyResponse": { "type": "object", "description": "Response for `POST .../kyb/company-prefill`. Prefill values the applicant\nconfirms/edits before submitting through `submit-business-info`.\n\nFilled from FREE provider data only. Outside the national-registry countries that serve a full\nrecord at no charge, that means a company search hit: legal name, registration number and legal\naddress. `companyType` and `incorporationDate` come back empty for the applicant to supply, and\nare reconciled against the register after submission by the business-info cross-check.", "required": [ "businessInformation", "directorCandidates", "authoritative", "pending" ], "properties": { "authoritative": { "type": "boolean", "description": "`false` when the values came from a non-authoritative source (a company search hit) — an\nauthoritative verification-mode fetch is scheduled on submit, and the cross-check compares\nthe applicant's submission against it." }, "businessInformation": { "$ref": "#/components/schemas/BusinessInformation" }, "directorCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/DirectorCandidate" }, "description": "Directors and officers found for the company, for the applicant to pick from. Empty unless\nthe company's country has a national registry that lists officers." }, "pending": { "type": "boolean", "description": "`true` when some company data is still being retrieved from the company-registry data\nprovider and will be completed later; `false` when the prefill is already complete." } } }, "ProcessAdditionalData": { "type": "object", "description": "Typed representation of process_additional_data stored in DV results.\n\nThis struct captures all the additional data associated with document\nverification processing, including document scan status, image quality\nchecks, security checks, and liveness data.\n\n# Deserialization\n\nSupports both new abstract format and legacy format. The main difference\nis in the `imageQuality` field:\n\n**New format:**\n```json\n{\n \"imageQuality\": [\n { \"checkType\": \"focus\", \"result\": \"passed\", \"probability\": 97 }\n ]\n}\n```\n\n**Legacy format:**\n```json\n{\n \"imageQuality\": [\n {\n \"count\": 6,\n \"list\": [\n { \"type\": 1, \"result\": 0, \"probability\": 97, ... }\n ],\n \"result\": 0\n }\n ]\n}\n```", "properties": { "authenticityVerified": { "type": [ "boolean", "null" ], "description": "Whether a document-authenticity assessment actually ran for this result.\n\n`Some(false)` means no tampering/forgery/replay check was performed — it is not a\nstatement that the document is genuine. Read this before treating an empty\n`security_checks` map as a pass. `None` on results written before the flag existed." }, "autoOneClickKycData": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AutoOneClickKycData", "description": "Auto one-click KYC flow tracking data" } ] }, "biometricCheckData": { "description": "Biometric check data (for face matching results)" }, "documentExpiredWebhookSentAt": { "type": [ "string", "null" ], "format": "date", "description": "Date on which the `DocumentExpired` webhook was sent for this document-verification result.\nAbsent until the document has expired and the webhook has gone out; the webhook is sent\nonly once per result." }, "extraction": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocscanExtractionProvenance", "description": "How this result's extraction was produced. `None` for provider paths that do not\nextract with a model, and on results written before this field existed." } ] }, "imageQuality": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ImageQualityCheckResult" }, "description": "Image quality check results" }, "portrait": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PortraitEstimate", "description": "What the face-analysis service read off the document portrait, when one was found.\n`None` when the document carried no detectable portrait, on provider paths that crop\ntheir own portrait, and on results written before this field existed." } ] }, "rawLivenessData": { "description": "Raw liveness data from face verification" }, "replay": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReplayAssessment", "description": "What the replay assessment measured, when one ran. `None` when it is switched off for\nthe step, when the client submitted no raw frames, and on results written before this\nfield existed.\n\n`security_checks` above records only the verdict as three pass/fail statuses, which is\nenough to explain a rejection but not enough to question one." } ] }, "securityChecks": { "type": [ "object", "null" ], "description": "Security check results (mapped by check type)", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentScanStatus", "description": "Document scan status from verification" } ] } } }, "ProcessAddressDocumentRequest": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } }, "ProcessAddressDocumentResponse": { "type": "object", "required": [ "verificationRequestId", "jobId", "attemptsCount" ], "properties": { "attemptsCount": { "type": "integer", "format": "int32", "description": "Number of prior attempts on this verification request.\n`0` = first submission (`Created`); `> 0` = retry (`Updated`)." }, "jobId": { "type": "string" }, "verificationRequestId": { "type": "string", "format": "uuid" } } }, "ProcessDocumentSelectionPayload": { "type": "object", "properties": { "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the document to be verified (e.g. `\"US\"`, `\"GB\"`). Optional — omit to allow any country." }, "documentType": { "type": [ "integer", "null" ], "format": "int64", "description": "Numeric document type identifier. Optional — omit to allow any document type." } } }, "ProcessDocumentSelectionResponse": { "type": "object", "required": [ "verificationRequestId" ], "properties": { "verificationRequestId": { "type": "string", "format": "uuid", "description": "The ID of the verification request that was updated." } } }, "ProcessIdentityDocumentPayload": { "type": "object", "required": [ "countryCode" ], "properties": { "allowedDocumentTypes": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "browser": { "type": [ "string", "null" ] }, "countryCode": { "type": "string" }, "forceDocumentType": { "type": [ "integer", "null" ], "format": "int64" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/InputImage" }, "description": "One front image and an optional back image, base64-encoded." }, "interviewId": { "type": [ "string", "null" ], "description": "Session ID of a hosted document-capture session, as returned when the session was created.\nSend it together with `sessionToken` to have the results fetched from the capture session." }, "platform": { "type": [ "string", "null" ] }, "provinceCode": { "type": [ "string", "null" ] }, "sessionToken": { "type": [ "string", "null" ], "description": "Session token for a hosted document-capture session, as returned when the session was\ncreated. Send it together with `interviewId` (and no `images`) to have the results fetched\nfrom the capture session instead of scanning uploaded images." }, "uncroppedImages": { "type": "array", "items": { "$ref": "#/components/schemas/InputImage" }, "description": "Uncropped originals accompanying `images`, base64-encoded. Optional: omit for clients\nthat only submit cropped images. Stored in S3 next to the doc-scan logs under their own\nretention window and never written to the vault or fed to the extraction provider — see\n`ProcessIdentityDocumentPayload::validate_images`. Each entry's `pageIndex` must have a\nmatching entry in `images` (an uncropped back with no cropped back is a client bug)." } } }, "ProcessIdentityDocumentResponse": { "type": "object", "required": [ "verificationRequestId", "jobId", "attemptsCount" ], "properties": { "attemptsCount": { "type": "integer", "format": "int32" }, "jobId": { "type": "string" }, "verificationRequestId": { "type": "string", "format": "uuid" } } }, "ProcessImagesOverrides": { "type": "object", "properties": { "authParams": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "checkAuth": { "type": [ "boolean", "null" ] }, "scenario": { "type": [ "string", "null" ] } } }, "ProcessLivenessPayload": { "type": "object", "required": [ "challengeId", "movementImagesQuantity" ], "properties": { "challengeId": { "type": "string", "format": "uuid" }, "movementImagesQuantity": { "type": "integer", "format": "int32" } } }, "ProcessLivenessResponse": { "type": "object", "required": [ "verificationRequestId", "jobId" ], "properties": { "jobId": { "type": "string" }, "verificationRequestId": { "type": "string", "format": "uuid" } } }, "ProductType": { "type": "string", "enum": [ "UNKNOWN", "DOCSCAN", "LIVENESS", "POA", "KYB", "KYC_PASSPORT", "SPID", "PHONE", "WALLET", "EXPORT_API", "EXPORT_UI", "BUSINESS_VERIFICATION", "FLOW_BUILDER", "GEOLOCATION", "FORM", "AML", "TRANSACTION_MONITORING", "TIN_CHECK" ] }, "PurchaseDocumentsPayload": { "type": "object", "description": "Payload for `POST .../kyb-cases/{case_id}/documents/purchase`.", "required": [ "documentIds" ], "properties": { "documentIds": { "type": "array", "items": { "type": "string" }, "description": "Document ids from a freshly-refreshed catalogue. Between 1 and 25." } } }, "PurchaseDocumentsResponse": { "type": "object", "description": "Response for `POST .../kyb-cases/{case_id}/documents/purchase`. Partial acceptance: only a\nrequest where *every* document is refused is a `400`.", "required": [ "verificationRequestId", "quotedCreditsTotal", "purchases" ], "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentPurchaseDecision" } }, "quotedCreditsTotal": { "type": "integer", "format": "int32", "description": "Sum of `quotedCredits` over accepted documents only." }, "verificationRequestId": { "type": "string", "format": "uuid", "description": "The KYB's anchor verification request — the websocket room for `discovery-update`." } } }, "PurchasedDocument": { "type": "object", "description": "One purchased document, as reported by `GET .../kyb-cases/{case_id}/documents`.", "required": [ "purchaseId", "documentId", "category", "status", "chargedCredits", "purchasedAt", "downloadable" ], "properties": { "category": { "type": "string" }, "chargedCredits": { "type": "integer", "format": "int32" }, "documentDate": { "type": [ "string", "null" ] }, "documentId": { "type": "string" }, "downloadable": { "type": "boolean", "description": "`true` once there is a stored file. A completed purchase can lack one — storage is\nbest-effort — in which case the download route re-signs from the provider instead." }, "format": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "purchaseId": { "type": "string", "format": "uuid" }, "purchasedAt": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/KybPurchasedDocumentStatus" }, "subType": { "type": [ "string", "null" ] } } }, "RejectKybPayload": { "type": "object", "description": "Request body for `POST /sdk/organizations/{organization_id}/kyb/{kyb_result_id}/reject`.\n\nA rejection is a decision on the company's case and needs a reason; the API key that takes it\nis named beside the reason on the case's decision.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Why the company is rejected. Required, and never blank." }, "reasonCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybCaseDecisionReasonCode", "description": "The closed vocabulary beside the free text. Optional for compatibility — a rejection that\nsends none is recorded as `OTHER`." } ] } } }, "ReplayAssessment": { "type": "object", "description": "Result of the replay-attack check for one document: whether the capture looks like a live\ndocument or a reproduction of one (a photo of a screen or of a print), with the scores behind\nthat verdict for the document as a whole and for each side.", "required": [ "verdict", "attackScore", "screenScore", "printScore", "secondgenScore", "confidence" ], "properties": { "attackScore": { "type": "number", "format": "double", "description": "Stage one: how strongly the capture reads as a reproduction of any medium, in [0, 1].\nThis is the score compared against the rejection threshold." }, "confidence": { "type": "number", "format": "double", "description": "How far past the decision threshold the verdict landed, in [0, 1]. Zero for\n`INCONCLUSIVE`, where no decision was reached." }, "flags": { "type": "array", "items": { "type": "string" } }, "printScore": { "type": "number", "format": "double" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Why the verdict landed where it did, most significant first." }, "screenScore": { "type": "number", "format": "double", "description": "Stage two: how strongly it reads as a display and as a print respectively. A medium is\nonly named when one leads the other by a margin *and* clears an absolute bar." }, "secondgenScore": { "type": "number", "format": "double", "description": "Generation-loss evidence. Scored and reported but never part of the verdict: its\nabsolute distributions overlap too much to reject on, so it exists to raise\n`SECOND_GENERATION` in `flags` for step-up handling." }, "sides": { "type": "array", "items": { "$ref": "#/components/schemas/ReplaySideAssessment" }, "description": "Per side, keyed by `front`/`back`." }, "verdict": { "type": "string", "description": "`LIVE`, `SCREEN`, `PRINT`, `ATTACK` or `INCONCLUSIVE`, taken across both sides at their\nworst case. `INCONCLUSIVE` means the capture was too degraded to read — it asks for\nanother capture and is not an accusation." } } }, "ReplaySideAssessment": { "type": "object", "description": "The replay-attack check's verdict and scores for one side (front or back) of the document.", "required": [ "side", "verdict", "attackScore", "screenScore", "printScore" ], "properties": { "attackScore": { "type": "number", "format": "double" }, "features": { "type": "object", "description": "Every raw feature the detector measured for this side. The calibration input.", "additionalProperties": { "type": "number", "format": "double" }, "propertyNames": { "type": "string" } }, "printScore": { "type": "number", "format": "double" }, "qualityFailures": { "type": "array", "items": { "type": "string" }, "description": "Quality-gate failures, when this side could not be read. Empty on a side that was\njudged." }, "screenScore": { "type": "number", "format": "double" }, "side": { "type": "string", "description": "`front` or `back`." }, "verdict": { "type": "string" } } }, "RequestOnDemandDocumentPayload": { "type": "object", "description": "Request body for `POST.../kyb-cases/{case_id}/document-requests/on-demand`.\n\nAsks the client for a specific on-demand per-country document (identified by its catalog\n`key`). The server validates the key resolves to an on-demand document for the KYB's\ncountry, creates a `Standard` document request from it, and notifies the client.", "required": [ "documentKey" ], "properties": { "body": { "type": [ "string", "null" ], "description": "Optional email body; defaults to a generated body referencing the document." }, "description": { "type": [ "string", "null" ], "description": "Optional description shown to the client; defaults to a generated message." }, "documentKey": { "type": "string", "description": "Catalog `key` of the on-demand document to request (must be on-demand for this country)." }, "recipientEmail": { "type": [ "string", "null" ], "description": "Optional recipient override; defaults to the business contact email." }, "subject": { "type": [ "string", "null" ], "description": "Optional email subject; defaults to a generated subject referencing the document." } } }, "RequiredDocumentField": { "type": "string", "enum": [ "firstName", "middleName", "lastName", "dateOfBirth", "phone", "email", "street", "city", "state", "postcode", "country", "socialSecurityNumber", "expirationDate" ] }, "ResultControlOperation": { "type": "object", "required": [ "timestamp", "identityId", "zid", "operation" ], "properties": { "identityId": { "type": "string", "format": "uuid" }, "operation": { "$ref": "#/components/schemas/ResultControlOperationType" }, "timestamp": { "type": "string", "format": "date-time" }, "zid": { "type": "string" } } }, "ResultControlOperationType": { "oneOf": [ { "type": "object", "required": [ "approve" ], "properties": { "approve": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] } } } } }, { "type": "object", "required": [ "reject" ], "properties": { "reject": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] } } } } }, { "type": "object", "required": [ "escalate" ], "properties": { "escalate": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] } } } } } ] }, "ResultStatus": { "type": "string", "enum": [ "PASSED", "FAILED", "PARTIAL", "REQUIRES_MANUAL_REVIEW", "REQUIRES_ADMIN_REVIEW" ] }, "ReviewSuggestion": { "type": "object", "required": [ "suggestion", "confidence" ], "properties": { "confidence": { "type": "number", "format": "double" }, "suggestion": { "$ref": "#/components/schemas/ManualReviewResultStatus" } } }, "RiskFactorKeys": { "type": "array", "items": { "type": "string" }, "description": "The keys of the form-based risk factors that matched for a form step, as recorded at the time." }, "RiskLevel": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "RiskScore": { "type": "object", "required": [ "riskScorePercent", "riskLevel", "sourcesCount" ], "properties": { "riskLevel": { "$ref": "#/components/schemas/RiskLevel" }, "riskScorePercent": { "type": "integer", "format": "int32" }, "sourcesCount": { "type": "integer", "minimum": 0 } } }, "RiskTagSource": { "oneOf": [ { "type": "object", "description": "Human-asserted; only a human clears it. Never auto-retracted.", "required": [ "kind" ], "properties": { "by": { "type": [ "string", "null" ], "format": "uuid" }, "kind": { "type": "string", "enum": [ "manual" ] } } }, { "type": "object", "description": "Answer-driven form emission; recomputed at form submit.", "required": [ "field", "kind" ], "properties": { "field": { "type": "string" }, "kind": { "type": "string", "enum": [ "formAnswer" ] } } }, { "type": "object", "description": "`AssignRiskTags` action node; recomputed by forward re-derivation.", "required": [ "node_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "action" ] }, "node_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "description": "A tag assigned before its source was recorded. It is not recomputed or removed\nautomatically.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "legacy" ] } } } ], "description": "Provenance for an `AssignedRiskTag` derivation. Determines whether a machine-driven\nrecompute is allowed to retract it (`Manual`/`Legacy` are sticky; only a human clears them).", "discriminator": { "propertyName": "kind" } }, "Role": { "type": "string", "enum": [ "ANONYMOUS", "GUEST", "ORG_ADMIN", "ORG_OPERATOR", "ORG_DEVELOPER", "AML_OFFICER", "PARTNER_USER", "PLATFORM_OPERATOR", "PLATFORM_SALES", "PLATFORM_ADMIN", "SDK", "SYSTEM" ] }, "RotationThresholds": { "type": "object", "description": "Rotation thresholds (in degrees) for head movement verification", "required": [ "up", "down", "left", "right" ], "properties": { "down": { "type": "number", "format": "float" }, "left": { "type": "number", "format": "float" }, "right": { "type": "number", "format": "float" }, "up": { "type": "number", "format": "float" } } }, "RunTinCheckAddress": { "type": "object", "description": "A US mailing address to validate against the USPS database.", "required": [ "street" ], "properties": { "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ], "description": "The two-letter state code, for example `CT`." }, "street": { "type": "string", "description": "The street address, for example `123 Main Street`." }, "unit": { "type": [ "string", "null" ], "description": "A suite, apartment or unit, for example `Suite 310`." }, "zip": { "type": [ "string", "null" ], "description": "Five digits, or nine with the +4 extension." } } }, "RunTinCheckRequest": { "type": "object", "description": "A TIN and the name to match it against, with the optional extras the same check can verify.\n\n`Debug` is written by hand so the TIN never reaches a log line in full.", "required": [ "name", "tin" ], "properties": { "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RunTinCheckAddress", "description": "A mailing address to validate against the USPS database. Confirms the address exists, not\nthat it is the subject's." } ] }, "giin": { "type": [ "string", "null" ], "description": "A FATCA Global Intermediary Identification Number, to look up on the IRS list of registered\nforeign financial institutions." }, "mock": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TinCheckMockOptions", "description": "Sandbox only: state what the check should answer instead of having it looked up. Refused\nin production." } ] }, "name": { "type": "string", "description": "A person's full name or a company's legal name, as it appears on IRS records." }, "tin": { "type": "string", "description": "A US Taxpayer Identification Number: the nine digits of an SSN or EIN. Spaces and hyphens\nare accepted and ignored." } } }, "ScreeningStrategy": { "type": "string", "description": "Which natural persons a KYB file must identify and screen before it can be approved.\n\nThis selects *which* population is required, never *whether* one is: every variant demands at\nleast one screened person. A business whose required population is empty is an incomplete\nfile, however cleanly its registry data cross-checks.", "enum": [ "ubo", "directors", "uboAndDirectors" ] }, "SdkAmlScreenQuery": { "type": "object", "description": "Search criteria for an AML screening. Every field is an optional string; provide at least one.\nThe more fields you fill in, the more precise the matching. Result-only data (sanctions,\ntopics, positions held) cannot be used as search input.", "properties": { "address": { "type": [ "string", "null" ] }, "alias": { "type": [ "string", "null" ] }, "birthCountry": { "type": [ "string", "null" ] }, "birthDate": { "type": [ "string", "null" ] }, "birthPlace": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "middleName": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "nationality": { "type": [ "string", "null" ] }, "passportNumber": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ] }, "registrationNumber": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } }, "SdkAmlScreenRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "$ref": "#/components/schemas/SdkAmlScreenQuery" }, "subjectType": { "$ref": "#/components/schemas/AmlSubjectType" } } }, "SdkAmlScreenResponse": { "type": "object", "required": [ "format", "provider", "entities" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/AmlEntityResponse" } }, "format": { "type": "string", "description": "Entity format of the returned matches, currently always `\"ftm/1\"`." }, "provider": { "type": "string", "description": "Identifier of the screening provider that produced these results. How many entity fields\nare populated depends on the provider — see the SDK docs for coverage differences." } } }, "SdkCreateVerificationRequestPayload": { "allOf": [ { "$ref": "#/components/schemas/VerificationIdentifier" }, { "type": "object", "properties": { "customData": { "type": [ "object", "null" ], "description": "Arbitrary key-value metadata to attach to this verification request.", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "webhook": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SdkSessionWebhookPayload", "description": "An extra callback for this verification run, delivered *in addition to* every configured\norganization endpoint.\n\nRequires a **Secret** SDK key. A Publishable key may be embedded in a browser, so allowing\none to install an arbitrary callback URL would turn this route into a server-side request\nforgery primitive.\n\nSupplying it again while resuming the same run replaces the previous callback; omitting it\nwhile resuming leaves the existing one untouched." } ] } } } ], "description": "Request body for creating or resuming a verification request on behalf of a user. Provide an\n`email`, a wallet credential, or both. When both are given, the wallet identifies the user and\nthe email is kept as a contact address." }, "SdkCreateVerificationRequestResponse": { "type": "object", "required": [ "verificationRequest", "zypheAccessSig", "zypheToken", "zid", "isSandbox", "flowSlug", "flowStepSlug" ], "properties": { "email": { "type": [ "string", "null" ], "description": "The email address associated with the verified user's identity, if available." }, "flowSlug": { "type": "string", "description": "Slug of the flow this verification request belongs to." }, "flowStepSlug": { "type": "string", "description": "Slug of the current flow step (the first incomplete step)." }, "isSandbox": { "type": "boolean", "description": "Whether this verification request was created in sandbox mode." }, "sessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "Identifier of the logical verification run. Stable across the calls that resume it." }, "sessionWebhook": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SdkSessionWebhookResponse", "description": "Present when this call installed or replaced a session callback." } ] }, "verificationRequest": { "$ref": "#/components/schemas/VerificationRequest", "description": "The created or resumed verification request." }, "zid": { "type": "string", "description": "Zyphe user identifier (ZID) for the verified user." }, "zypheAccessSig": { "type": "string", "description": "Short-lived signed access token used to authenticate subsequent SDK calls on behalf of this user." }, "zypheToken": { "type": "string", "description": "JWT for the verified user's session. Pass this as a bearer token for user-scoped SDK calls." } } }, "SdkSessionWebhookPayload": { "type": "object", "description": "A callback attached to one logical verification run, supplied when an authenticated server\ninitiates or resumes it through the SDK.\n\n**Additive, never a replacement.** Every configured organization endpoint that matches still\nfires; this is delivered alongside them. If a configured endpoint happens to share this URL the\ncustomer receives two signed calls, which is the intended reading of \"along with the already\nconfigured notifications\" — deduplicating by URL would silently discard a subscription that was\nexplicitly requested.", "required": [ "url", "secret" ], "properties": { "eventTypes": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Canonical event filters. Omitted means every verification and flow event this session\nproduces. Transaction Monitoring and other sessions' KYC Passport events can never be\nsubscribed to here, whether listed or not." }, "payloadVersion": { "$ref": "#/components/schemas/WebhookPayloadVersion" }, "secret": { "type": "string", "description": "Caller-generated HMAC signing secret.\n\nRequired, and required to be the *caller's*, on purpose: this endpoint may be resuming an\nexisting run rather than creating one, and a server-minted secret would then have to be\neither re-returned (leaking it on every resume) or silently kept (leaving the caller unable\nto verify). A caller-supplied secret makes an idempotent retry predictable instead." }, "url": { "type": "string", "description": "HTTPS callback URL. Validated on write and re-resolved against the public-address rules\nagain immediately before every delivery." } }, "additionalProperties": false }, "SdkSessionWebhookResponse": { "type": "object", "description": "What the caller is told about the callback it just installed. Never the secret it supplied.", "required": [ "id", "secretHint", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "secretHint": { "type": "string", "description": "Last characters of the supplied secret, so the caller can confirm which one is in force." } } }, "SecurityCheckType": { "type": "string", "description": "Canonical security/authenticity check types.", "enum": [ "uv_luminescence", "ir_b900", "image_pattern", "axial_protection", "uv_fibers", "ir_visibility", "ocr_security_text", "ipi", "photo_embedding", "photo_area", "portrait_comparison", "holograms", "kinegram", "letter_screen", "barcode", "mrz", "extended_mrz", "extended_ocr", "liveness", "electronic_device", "screen_replay", "black_and_white_copy", "document_alteration", "document_tampering", "fake_document", "paper_copy", "cross_check", "portrait_gender", "portrait_age", "unknown" ] }, "SelectOptions": { "type": "object", "required": [ "values", "isOtherAllowed" ], "properties": { "isOtherAllowed": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "string" } } } }, "ServiceCredentialEnvironment": { "type": "string", "description": "The environment a service credential works in, fixed by its token prefix: `sk_live_` for\nproduction, `sk_test_` for sandbox.\n\nA service credential is a bot token an integrator's server uses on the organization API\n(`Authorization: Bearer sk_…`). The prefix is part of the hashed token, so it can't be changed\nwithout invalidating the token.", "enum": [ "LIVE", "TEST" ] }, "Settings": { "type": "object", "properties": { "askPasskeyCreation": { "type": [ "boolean", "null" ], "description": "When true (default), prompt users to create a passkey during the verification flow.\nWhen false, skip the passkey creation step.\nOptional so that patch requests only write this field when explicitly provided." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "delayFlowResults": { "type": [ "boolean", "null" ] }, "emailNotifications": { "type": [ "array", "null" ], "items": { "type": "string" } }, "extendedWebhook": { "type": [ "boolean", "null" ] }, "oneClickAlwaysRequestUnlockVault": { "type": [ "boolean", "null" ], "description": "When true (default), always require vault unlock for one-click KYC even if a grant already exists.\nWhen false, skip vault unlock if an active KYC grant already exists for the organization.\nOptional so that patch requests only write this field when explicitly provided." }, "published": { "type": "boolean" }, "skipSignedAccess": { "type": "boolean" }, "slackNotifications": { "type": [ "array", "null" ], "items": { "type": "string" } }, "telegramNotifications": { "type": [ "array", "null" ], "items": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "webhookSecret": { "type": [ "string", "null" ] }, "webhookWithLegacy": { "type": [ "boolean", "null" ] } } }, "SiwxChain": { "type": "string", "enum": [ "ETHEREUM", "ETHEREUM_TESTNET", "SOLANA", "SOLANA_TESTNET" ] }, "SpidConfig": { "type": "object", "properties": { "documentSelectionStepId": { "type": "string", "format": "uuid", "description": "The ID of the document-selection step that precedes this SPID step in the flow." }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" } } }, "SpidDocumentType": { "type": "string", "enum": [ "ITALIAN_SPID", "AADHAAR" ] }, "SpidResult": { "type": "object", "required": [ "id", "status", "path" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" } } }, "SpidResultDetails": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "companyVatNumber": { "type": [ "string", "null" ] }, "countryOfBirth": { "type": [ "string", "null" ] }, "dateOfBirth": { "type": [ "string", "null" ] }, "digitalAddress": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "fiscalNumber": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "gender": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "mobilePhone": { "type": [ "string", "null" ] }, "placeOfBirth": { "type": [ "string", "null" ] }, "registeredOffice": { "type": [ "string", "null" ] }, "spidCode": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "SpidStepOutput": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "StartGeolocationVerificationRequest": { "type": "object" }, "StartGeolocationVerificationResponse": { "type": "object", "required": [ "verificationRequestId", "nonce" ], "properties": { "nonce": { "type": "string" }, "verificationRequestId": { "type": "string", "format": "uuid" } } }, "StartPhoneVerificationRequest": { "type": "object", "required": [ "phoneNumberE164" ], "properties": { "phoneNumberE164": { "type": "string" } } }, "StartPhoneVerificationResponse": { "type": "object", "required": [ "verificationRequestId" ], "properties": { "verificationRequestId": { "type": "string", "format": "uuid" } } }, "StartWalletVerificationRequest": { "type": "object", "required": [ "address", "chain" ], "properties": { "address": { "type": "string" }, "chain": { "$ref": "#/components/schemas/SiwxChain" } } }, "StartWalletVerificationResponse": { "type": "object", "required": [ "verificationRequestId", "message" ], "properties": { "message": { "type": "string" }, "verificationRequestId": { "type": "string", "format": "uuid" } } }, "SubdivisionOption": { "type": "object", "description": "One selectable subdivision: the ISO 3166-2 code the API expects back, and its English name.", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "description": "The bare code (`DE`), which is what `subdivision` accepts. The qualified form (`US-DE`) and\nthe English name are accepted too, but this is the canonical one to send back." }, "name": { "type": "string", "description": "English name, for display (`Delaware`)." } } }, "SubjectAssignmentResponse": { "type": "object", "description": "One hand-off of a subject's work.", "required": [ "id", "subject", "assignee", "reason", "assignedBy", "assignedAt" ], "properties": { "assignedAt": { "type": "string", "format": "date-time" }, "assignedBy": { "type": "string", "format": "uuid" }, "assignee": { "$ref": "#/components/schemas/AssigneePayload" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Set once the subject was handed on or released. The row with no `endedAt` is the holder." }, "endedBy": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" }, "subject": { "$ref": "#/components/schemas/KybSubjectRef" } } }, "Theme": { "type": "object", "description": "Flat theme API response. Logo/font fields hold raw S3 keys when built from `ThemeData`; the\nhandler swaps them for presigned URLs before returning.", "required": [ "id", "name", "isDefault" ], "properties": { "borderRadius": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "dark": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThemeColorSetResponse" } ] }, "fontFamily": { "type": [ "string", "null" ] }, "fontLicense": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThemeFontLicense" } ] }, "fontUrl": { "type": [ "string", "null" ], "description": "Presigned read URL for the uploaded font (or the raw S3 key before presigning)." }, "id": { "type": "string", "format": "uuid" }, "isDefault": { "type": "boolean" }, "light": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ThemeColorSetResponse" } ] }, "name": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ThemeColorSetResponse": { "type": "object", "description": "Per-mode color set as returned by the API (logo resolved to a presigned URL).", "properties": { "accent": { "type": [ "string", "null" ] }, "background": { "type": [ "string", "null" ] }, "card": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ], "description": "Presigned read URL for this mode's logo (or the raw S3 key before the handler presigns it)." } } }, "ThemeFontLicense": { "type": "object", "description": "Attestation that the org has the right to use the uploaded font.", "required": [ "attested" ], "properties": { "attested": { "type": "boolean" }, "attestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "attestedByIdentityId": { "type": [ "string", "null" ], "format": "uuid" } } }, "TinCheckListResponse": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TinCheckResponse" }, "description": "Newest first." }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "TinCheckLookupStatus": { "type": "string", "description": "The answer of one of the lookups that run alongside the IRS match.", "enum": [ "NOT_PROCESSED", "NO_MATCH", "POSSIBLE_MATCH" ] }, "TinCheckMockOptions": { "type": "object", "description": "The answer a sandbox mock check should give, stated instead of looked up. Sandbox only.", "required": [ "outcome" ], "properties": { "addressFound": { "type": [ "boolean", "null" ], "description": "Whether a submitted address is found in the USPS database. Defaults to found." }, "deathMasterFileMatch": { "type": "boolean", "description": "Report a possible Death Master File match." }, "einNameMatch": { "type": "boolean", "description": "Report the EIN as on record under another name." }, "giinFound": { "type": [ "boolean", "null" ], "description": "Whether a submitted GIIN is found on the FATCA list. Defaults to found." }, "outcome": { "$ref": "#/components/schemas/TinCheckMockOutcome" }, "tinType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TinCheckTinType", "description": "Which kind of IRS record matched. Only read for a `MATCH`." } ] }, "watchlistMatches": { "type": [ "integer", "null" ], "format": "int32", "description": "How many entries resemble the name on each flagged list. Defaults to 2." }, "watchlists": { "type": "array", "items": { "type": "string" }, "description": "The watchlists to flag, by short code (`OFAC`, `PEP`, ...). Every other list answers clear." } } }, "TinCheckMockOutcome": { "type": "string", "description": "What a sandbox mock check answers on the IRS match itself.", "enum": [ "MATCH", "MISMATCH", "NOT_ISSUED", "INVALID_TIN", "UNAVAILABLE" ] }, "TinCheckOutcome": { "type": "string", "description": "The verdict of a TIN check: whether the TIN and name combination matches IRS records.", "enum": [ "MATCH", "MISMATCH", "NOT_ISSUED" ] }, "TinCheckQuoteResponse": { "type": "object", "description": "What the next TIN check costs this organization.", "required": [ "credits" ], "properties": { "credits": { "type": "integer", "format": "int32", "description": "The price of one check, in credits. Zero in the sandbox, where checks are free." } } }, "TinCheckResponse": { "type": "object", "description": "One TIN check and its results.", "required": [ "id", "name", "tinMasked", "outcome", "deathMasterFile", "einNameMatch", "watchlistStatus", "watchlists", "chargedCredits", "createdAt" ], "properties": { "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TinCheckSubmittedLookup", "description": "The USPS address validation. Absent when no address was submitted." } ] }, "chargedCredits": { "type": "integer", "format": "int32", "description": "What this check cost, in credits. Zero in the sandbox." }, "createdAt": { "type": "string", "format": "date-time" }, "createdByEmail": { "type": [ "string", "null" ], "description": "The email of the member who ran the check. Absent when it was not run by a person, or the\nperson is no longer known." }, "deathMasterFile": { "$ref": "#/components/schemas/TinCheckLookupStatus", "description": "Whether the subject resembles an entry on the Social Security Death Master File." }, "einNameMatch": { "$ref": "#/components/schemas/TinCheckLookupStatus", "description": "Whether the lookup service has the EIN on record under a name other than the one checked.\nFor reference only: its records come from earlier matches and may be out of date." }, "einNameMatchData": { "type": [ "string", "null" ], "description": "The name on record, as the lookup service reports it: an XML document. Absent without a\nmatch." }, "giin": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TinCheckSubmittedLookup", "description": "The FATCA GIIN lookup. Absent when no GIIN was submitted." } ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "The name that was checked, as submitted." }, "outcome": { "$ref": "#/components/schemas/TinCheckOutcome", "description": "Whether the TIN and name combination matches IRS records." }, "tinMasked": { "type": "string", "description": "The TIN with everything but its last four digits hidden, for example `XXXXX6789`. The full\nTIN is not stored." }, "tinType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TinCheckTinType", "description": "Whether the matching record is an SSN, an EIN or both. Absent unless the IRS says." } ] }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid", "description": "The KYB anchor's verification request, for a check run when an applicant submitted a KYB's\nbusiness information. Absent for a check run from the dashboard or with an API key." }, "watchlistStatus": { "$ref": "#/components/schemas/TinCheckLookupStatus", "description": "Whether the name resembles an entry on any of the screened watchlists." }, "watchlists": { "type": "array", "items": { "$ref": "#/components/schemas/TinCheckWatchlist" }, "description": "Every watchlist the name was screened against, with how many entries resemble it. A\nresemblance is a similarity on the name, to be reviewed: not a confirmed hit." } } }, "TinCheckSubmittedLookup": { "type": "object", "description": "An optional lookup that ran because a value was submitted for it: what was submitted, and the\nlookup service's answer.", "required": [ "submitted" ], "properties": { "result": { "type": [ "string", "null" ], "description": "The lookup service's answer, in its own words (English). Absent when it gave none." }, "submitted": { "type": "string", "description": "The value that was submitted." } } }, "TinCheckTinType": { "type": "string", "description": "Which kind of IRS record a matching TIN belongs to, when the IRS says.", "enum": [ "SSN", "EIN", "SSN_AND_EIN" ] }, "TinCheckWatchlist": { "type": "object", "description": "One watchlist the name was screened against, and how many of its entries resemble the name.", "required": [ "list", "flagged", "possibleMatches" ], "properties": { "flagged": { "type": "boolean", "description": "Whether the list has entries that resemble the name." }, "list": { "type": "string", "description": "The list's short name, for example `OFAC` or `PEP`." }, "matchData": { "type": [ "string", "null" ], "description": "The resembling entries, as the lookup service reports them: an XML document whose layout\nvaries by list. Absent when the list is clear." }, "possibleMatches": { "type": "integer", "format": "int32", "description": "How many entries on the list resemble the name. Zero on a clear list, and on a flagged\none whose entries the lookup service did not count." } } }, "TmAgentGuardPolicy": { "type": "object", "description": "Deterministic limits for TM auto-resolution. Amounts are currency-specific minor units;\nan absent currency or rule hash cannot be auto-closed. Empty defaults only suggest/escalate.", "properties": { "autoCloseRuleHashes": { "type": "array", "items": { "type": "string" }, "description": "Explicitly reviewed condition hashes eligible for low-risk false-positive closure." }, "maxAmountMinor": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "maxRiskProbability": { "type": "number", "format": "double" } }, "additionalProperties": false }, "TmAgentReviewEvidence": { "type": "object", "description": "The detailed record behind an automated alert review: the case file the review was based on\nand its findings about the end user. Only shown in the dashboard; never included in API\nresponses or webhooks.", "required": [ "caseFile", "findings", "mitigations", "verdict" ], "properties": { "actuationCaseFile": { "type": [ "object", "null" ], "description": "The re-read case at actuation time, present only when it differed from the analytic one." }, "caseFile": { "type": "object" }, "findings": { "type": "object" }, "mitigations": { "type": "object" }, "verdict": { "type": "object" } } }, "TmAgentReviewSummary": { "type": "object", "description": "The API-facing projection of a stored `agentReview`.\n\nThe stored review keeps the whole case file, the prosecutor's findings about the end user,\nthe identity risk score and the controls of the subject's other alerts. None of that belongs\non an API-key-authenticated route, so the SDK gets this summary and only the JWT dashboard\nroute asks for `evidence`.\n\nAlso the `resolution` field of the `transaction.alert.resolved` webhook, always without\nevidence.", "required": [ "id", "reviewedAt", "model", "mode", "recommendedStatus", "decision", "rationale", "promptVersions" ], "properties": { "decision": { "$ref": "#/components/schemas/TmDecision" }, "evidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TmAgentReviewEvidence" } ] }, "guard": { "type": [ "object", "null" ], "description": "The deterministic guard outcome that produced the enacted decision; `null` when the guard\nnever ran (the model did not recommend approval)." }, "id": { "type": "string", "format": "uuid" }, "mode": { "$ref": "#/components/schemas/KybAgenticMode" }, "model": { "type": "string" }, "promptVersions": { "type": "object" }, "rationale": { "type": "string" }, "recommendedStatus": { "$ref": "#/components/schemas/TmAlertStatus" }, "reviewedAt": { "type": "string", "format": "date-time" } } }, "TmAlertDetail": { "type": "object", "description": "An alert raised on a transaction, as returned in the transaction detail.\n\n`agentReview` is a summary of the automated review of the alert, when one ran. The detailed\nreview evidence is only shown in the dashboard and is not included in API responses.", "required": [ "id", "status", "controls" ], "properties": { "agentReview": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TmAgentReviewSummary" } ] }, "controls": {}, "id": { "type": "string", "format": "uuid" }, "ruleKey": { "type": [ "string", "null" ] }, "ruleVersion": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "$ref": "#/components/schemas/TmAlertStatus" } } }, "TmAlertRef": { "type": "object", "description": "Reference to one raised alert in an ingest response.", "required": [ "alertId" ], "properties": { "alertId": { "type": "string", "format": "uuid" }, "ruleKey": { "type": [ "string", "null" ] } } }, "TmAlertStatus": { "type": "string", "description": "Alert lifecycle.", "enum": [ "NEW", "IN_REVIEW", "ESCALATED", "CLOSED_TRUE_POSITIVE", "CLOSED_FALSE_POSITIVE", "SAR_FILED" ] }, "TmBand": { "type": "string", "description": "Which threshold band (`low`, `med` or `high`) a transaction's value fell into for a numeric\n(metric) rule. Absent on rules that are simple yes/no signals.", "enum": [ "low", "med", "high" ] }, "TmCounterpartyKind": { "type": "string", "description": "Counterparty node type.", "enum": [ "PERSON", "ORGANIZATION", "ACCOUNT", "WALLET" ] }, "TmCounterpartyRequest": { "type": "object", "description": "Counterparty leg of an ingest request.", "properties": { "address": { "type": [ "string", "null" ], "description": "Account/IBAN/wallet identifier — the canonical join key for \"same counterparty across\nidentities\" derives from it. This becomes a unique-index key, so it is capped well below\nany DB index limit." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2; derived from the IBAN prefix of `address` when omitted." }, "kind": { "$ref": "#/components/schemas/TmCounterpartyKind" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "TmDecision": { "type": "string", "description": "The synchronous verdict on a transaction: the combined `P(risk)` (noisy-OR over fired rule\nprobabilities) compared to the org's `tm_settings` thresholds.", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "TmFiredRule": { "type": "object", "description": "A monitoring rule that fired on a transaction, identifying the exact rule version (`ruleId`,\n`ruleKey`, `ruleVersion`, `ruleHash`) and how it contributed to the risk score.", "required": [ "ruleId", "ruleKey", "ruleVersion", "ruleHash", "probability", "raiseAlert" ], "properties": { "band": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TmBand", "description": "The band the metric landed in; `null` for yes/no signals." } ] }, "probability": { "type": "number", "format": "double", "description": "The rule's contributed `p` for that band." }, "raiseAlert": { "type": "boolean", "description": "Whether this rule firing raises an alert." }, "ruleHash": { "type": "string" }, "ruleId": { "type": "string", "format": "uuid" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer", "format": "int32" } } }, "TmIngestTransactionRequest": { "type": "object", "description": "Ingest one transaction event for monitoring.\n\nUnknown fields are rejected: a misspelled field name makes the request fail instead of being\nsilently ignored.", "required": [ "externalId", "identityId", "direction", "amountMinor", "currency", "occurredAt" ], "properties": { "amountMinor": { "type": "integer", "format": "int64", "description": "Integer minor units (e.g. cents) — no float money." }, "channel": { "type": [ "string", "null" ], "description": "e.g. `card`, `sepa`, `onchain`." }, "counterparty": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TmCounterpartyRequest" } ] }, "currency": { "type": "string", "description": "ISO 4217 alpha-3 (letters only, e.g. `EUR`). Uppercase on the wire; any case accepted.", "example": "EUR" }, "description": { "type": [ "string", "null" ], "description": "Payment reference / free-text description (SEPA *causale*) — the keyword-screening surface." }, "direction": { "$ref": "#/components/schemas/TmTransactionDirection" }, "externalId": { "type": "string", "description": "Client-side transaction id — the idempotency key per organization: replaying the same\n`externalId` returns the original result without re-evaluating or double-billing." }, "externalUserId": { "type": [ "string", "null" ], "description": "Optional client-side user reference (passthrough)." }, "identityId": { "type": "string", "format": "uuid", "description": "The monitored (verified) identity this event belongs to." }, "metadata": { "description": "Arbitrary client metadata, persisted verbatim for audit/replay." }, "occurredAt": { "type": "string", "format": "date-time", "description": "Client event time. Rejected if more than 24h in the future — a small clock-skew\nallowance, not an invitation to backdate/forward-date events." }, "originCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 — the monitored identity's side (defaults to the org's operating\ncountry semantics; overridable per event for multi-country books)." }, "rail": { "type": [ "string", "null" ], "description": "Provider/rail (`open_banking`, `sepa`, `card`, …)." }, "referenceDocumentId": { "type": [ "string", "null" ], "format": "uuid", "description": "Attached invoice/document reference." } }, "additionalProperties": false }, "TmIngestTransactionResponse": { "type": "object", "description": "Synchronous ingest verdict.", "required": [ "transactionId", "decision", "riskProbability", "firedRules", "alerts", "replay" ], "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/TmAlertRef" }, "description": "Alerts raised by this transaction (rules with `raiseAlert`)." }, "decision": { "$ref": "#/components/schemas/TmDecision" }, "firedRules": { "type": "array", "items": { "$ref": "#/components/schemas/TmFiredRule" }, "description": "Rules that fired on this evaluation, with full version provenance." }, "replay": { "type": "boolean", "description": "`true` when this call was an idempotent replay of a previously ingested transaction." }, "riskProbability": { "type": "number", "format": "double", "description": "Combined `P(risk)` behind the decision." }, "transactionId": { "type": "string", "format": "uuid" } } }, "TmTransactionDirection": { "type": "string", "description": "Direction of a monitored transaction relative to the monitored identity.", "enum": [ "DEPOSIT", "WITHDRAWAL", "TRANSFER" ] }, "TmTransactionResponse": { "type": "object", "description": "One monitored transaction (read view).", "required": [ "id", "externalId", "identityId", "direction", "amountMinor", "currency", "status", "occurredAt", "ingestedAt", "firedRules" ], "properties": { "alerts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/TmAlertDetail" }, "description": "Included by the detail endpoints; contains the persisted agent rationale, evidence and audit." }, "amountMinor": { "type": "integer", "format": "int64" }, "channel": { "type": [ "string", "null" ] }, "counterpartyAddress": { "type": [ "string", "null" ] }, "counterpartyCountry": { "type": [ "string", "null" ] }, "counterpartyId": { "type": [ "string", "null" ], "format": "uuid" }, "counterpartyName": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "decision": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TmDecision" } ] }, "description": { "type": [ "string", "null" ] }, "direction": { "$ref": "#/components/schemas/TmTransactionDirection" }, "externalId": { "type": "string" }, "externalUserId": { "type": [ "string", "null" ] }, "firedRules": { "type": "array", "items": { "$ref": "#/components/schemas/TmFiredRule" } }, "id": { "type": "string", "format": "uuid" }, "identityId": { "type": "string", "format": "uuid" }, "ingestedAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" }, "originCountry": { "type": [ "string", "null" ] }, "rail": { "type": [ "string", "null" ] }, "referenceDocumentId": { "type": [ "string", "null" ], "format": "uuid" }, "riskProbability": { "type": [ "number", "null" ], "format": "double" }, "status": { "$ref": "#/components/schemas/TmTransactionStatus" } } }, "TmTransactionStatus": { "type": "string", "description": "Payment lifecycle status (client-updatable via `PATCH`). Velocity counts transactions while\n`Pending`/`Settled` and backs them out on a one-time transition into a terminal-negative state.", "enum": [ "PENDING", "SETTLED", "FAILED", "CANCELED", "REVERSED" ] }, "TmUpdateTransactionStatusRequest": { "type": "object", "description": "Update the payment lifecycle status (`PATCH /sdk/organizations/{org}/transactions/{id}`).", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/TmTransactionStatus" } } }, "TopupPack": { "type": "object", "description": "A top-up pack: a one-time purchase that adds credits to the organization's balance and\ncan optionally unlock products.", "required": [ "priceId", "name", "credits", "amountCents", "currency" ], "properties": { "amountCents": { "type": "integer", "format": "int64", "description": "Price amount in the smallest currency unit (e.g. cents)" }, "credits": { "type": "integer", "format": "int64", "description": "Number of credits granted by this pack, from metadata `credits`" }, "currency": { "$ref": "#/components/schemas/Currency" }, "enabledProducts": { "type": "array", "items": { "$ref": "#/components/schemas/ProductType" }, "description": "Products this pack enables in the production environment when it is purchased. Empty\nwhen the pack grants credits only." }, "isPrivate": { "type": "boolean", "description": "`true` when the price carries `zyphe_visibility=private` metadata: a bespoke pack that\nmust never appear in the public catalog and is usable only by the organization named in\n`organization_id`. Defaults to `false` so an untagged price stays public, and so cached\ncatalog entries serialized before this field existed still deserialize." }, "name": { "type": "string", "description": "Display name: nickname > product name > price ID" }, "organizationId": { "type": [ "string", "null" ], "description": "The organization a private pack belongs to, from price metadata `organization_id`.\nMeaningless (and normally absent) on a public pack. A private pack WITHOUT this is\nusable by nobody — failing closed beats leaking a bespoke price to every customer." }, "priceId": { "type": "string", "description": "The pack's price ID. Pass it as `priceId` when creating a top-up checkout session." }, "sandboxEnabledProducts": { "type": "array", "items": { "$ref": "#/components/schemas/ProductType" }, "description": "Products this pack enables in the sandbox environment when it is purchased. Separate\nfrom `enabledProducts` because an organization may be allowed to try a product in\nsandbox without being able to use it in production. Empty when none." }, "validityMonths": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional validity window (in months) for the granted credits, from metadata `validity_months`", "minimum": 0 } } }, "TopupPacksResponse": { "type": "object", "description": "Response for the top-up pack catalog endpoint (`GET .../billing/topup-packs`).", "required": [ "packs" ], "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/TopupPack" } } } }, "TraversalSummary": { "type": "object", "description": "Summary of the automatic ownership discovery: the relevance threshold it uses, its credit\nbudget, what it has spent so far and, once finished, how it ended. Returned to your\norganization only, never to the applicant.", "required": [ "minBranchPercentage", "budgetCredits", "spentCredits" ], "properties": { "budgetCredits": { "type": "integer", "format": "int32", "description": "The step budget gated up front, in Zyphe credits. Σ of every wave's spend can never exceed\nthis: each wave's `maxBudget` is capped at what remains." }, "minBranchPercentage": { "type": "number", "format": "double", "description": "The relevance floor **currently configured** — the value every wave since the last edit\nused, not a value frozen on the run. The floor is an operational tolerance, not part of the\ncase file." }, "outcome": { "type": [ "string", "null" ], "description": "**Absent** while the traversal is still open — `skip_serializing_if` omits the key rather\nthan emitting `null`, so a client testing for an explicit null never matches. Otherwise how\nit ended — `completed`,\n`threshold_pruned`, `budget_exhausted`, `max_depth_reached`, `unexpandable`, `wave_failed`\nor `failed`." }, "spentCredits": { "type": "integer", "format": "int32", "description": "What the base run and its waves have been charged so far, in Zyphe credits. Excludes\nreviewer-initiated per-node expansions, which are billed separately and at a margin." } } }, "TraversalWave": { "type": "object", "description": "One step (wave) of the automatic ownership discovery that runs while the applicant completes\nthe flow: which nodes it explored, its status and what it cost. Returned to your organization\nonly, never to the applicant.", "required": [ "discoveryId", "wave", "status", "nodeIds", "budgetCapCents", "chargedCredits", "createdAt" ], "properties": { "budgetCapCents": { "type": "integer", "format": "int64", "description": "The provider `maxBudget` this wave carried, in provider credit cents — the reservation the\ncredit gate sees while it is live." }, "chargedCredits": { "type": "integer", "format": "int32" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "discoveryId": { "type": "string", "format": "uuid" }, "nodeIds": { "type": "array", "items": { "type": "string" }, "description": "The `budget_truncated` chips this wave opened, in the relevance order it chose them." }, "status": { "$ref": "#/components/schemas/KybDiscoveryRequestStatus" }, "stoppedReason": { "type": [ "string", "null" ] }, "wave": { "type": "integer", "format": "int32", "description": "Its position in the traversal, 1-based: wave 1 is the first continuation off the\ninteractive base run.", "minimum": 0 } } }, "TriggerReminderResponse": { "type": "object", "required": [ "enqueued" ], "properties": { "enqueued": { "type": "boolean" } } }, "UboDefinition": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Nationality of the UBO. Absent when the company register reported none." }, "dateOfBirth": { "type": [ "string", "null" ], "description": "`None` for a UBO taken from a company register as reported. Registers publish ownership,\nnot identity dossiers: a birth date is frequently absent, and demanding one would force the\napplicant to invent or look up data the register itself does not hold. Such a UBO is\nAML-screened on name alone, which the review panel is expected to treat as a thin identity." }, "emailAddress": { "type": [ "string", "null" ], "description": "Email of the UBO. `None` for a name-only UBO added without an email: such a UBO is\nAML-screened by name and is never sent a KYC invitation." }, "firstName": { "type": "string" }, "gender": { "type": [ "string", "null" ], "description": "`None` for any register-sourced UBO — no company register publishes gender. Collected only\nwhen a person enters the UBO by hand." }, "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Stable identifier for this UBO within the KYB result. Assigned on creation\n(submission or post-submission add) and used to address the UBO for removal /\nname-screening instead of a positional index. `None` only for legacy entries\ncreated before this field existed." }, "lastName": { "type": "string" } } }, "UboSuggestion": { "type": "object", "description": "One ultimate-beneficial-owner suggestion derived from the discovered ownership graph.\nSuggestions only — the applicant confirms them into real `UboDefinition`s; discovery\nnever writes `ubo_definitions` itself.", "required": [ "fullName" ], "properties": { "birthDate": { "type": [ "string", "null" ], "description": "`\"YYYY-MM-DD\"`, when the provider reported a birth date." }, "fullName": { "type": "string" }, "nationality": { "type": [ "string", "null" ] }, "totalOwnershipPercentage": { "type": [ "number", "null" ], "format": "double" } } }, "ValidationMessages": { "type": "string", "enum": [ "validation_unexpected", "validation_invalid_file_format", "validation_organization_slug_exists", "validation_flow_slug_exists", "validation_flow_id_mismatch", "validation_flow_step_name_exists", "validation_consents_not_granted", "validation_kyb_config_match", "validation_kyb_config_already_uses_this_kyc_flow_id", "validation_kyb_require_kyc_needs_kyc_flow", "validation_kyb_moderation_status_wrong", "validation_kyb_missing_required_documents", "validation_form_name_exists", "validation_database_error", "validation_flow_name_invalid", "validation_flow_slug_name_invalid", "validation_flow_step_name_invalid", "validation_flow_step_order_duplicate", "validation_flow_step_order_invalid", "validation_flow_step_id_mismatch", "validation_password_too_short", "validation_password_no_uppercase", "validation_password_no_lowercase", "validation_password_no_number", "validation_password_no_special_character", "validation_password_contains_whitespace_or_control", "validation_emails_empty", "validation_email_invalid", "validation_emails_too_many", "validation_emails_duplicate", "validation_invite_to_self", "validation_e164_format", "validation_flow_step_already_has_reference", "validation_flow_step_config_invalid", "validation_flow_not_found", "validation_empty_parameter", "validation_form_not_found", "validation_organization_not_found", "validation_workflow_graph_invalid", "validation_invalid_role_for_invitation", "validation_form_condition_forward_ref" ] }, "VaultUnlockPasskeyData": { "type": "object", "required": [ "credentialId", "challenge", "options", "prfSalt" ], "properties": { "challenge": { "type": "string", "description": "Passkey challenge for vault unlock (base64url)" }, "credentialId": { "type": "string", "description": "Credential ID for vault unlock (base64url-encoded)" }, "options": { "type": "object", "description": "Full WebAuthn `PublicKeyCredentialRequestOptions` for vault unlock.\nFrontends should pass `options.publicKey` directly to\n`navigator.credentials.get({ publicKey })`." }, "prfSalt": { "type": "string", "description": "PRF salt for vault unlock (base64url)" } } }, "VerificationIdentifier": { "type": "object", "description": "Fields that identify the user in every verification-request creation payload. Provide an\n`email`, a `WALLET` entry in `credentials`, or both. Email magic-link sign-in is enabled\nautomatically whenever an email is given and does not need to be listed in `credentials`.", "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationIdentifierCredential" }, "description": "Credentials to enable for this identity (e.g. wallet, magic-link).\nThe first `Wallet` entry determines the `zid`; all entries are provisioned on\nidentity creation." }, "email": { "type": [ "string", "null" ], "description": "Email address of the user. Used for notifications and as the `zid` when no wallet\ncredential is provided." } } }, "VerificationIdentifierCredential": { "oneOf": [ { "type": "object", "description": "Wallet credential. The `zid` is derived as `\"CHAIN:address\"` when this is the\nfirst (or only) credential and no email is provided.", "required": [ "chain", "address", "type" ], "properties": { "address": { "type": "string" }, "chain": { "$ref": "#/components/schemas/SiwxChain" }, "type": { "type": "string", "enum": [ "WALLET" ] } } }, { "type": "object", "description": "External identifier scoped to the calling organization.\nThe `organization_id` is always populated server-side and must never be\naccepted from untrusted client input.", "required": [ "externalId", "type" ], "properties": { "externalId": { "type": "string" }, "type": { "type": "string", "enum": [ "EXTERNAL_ID" ] } } } ], "description": "A credential to attach to the user when creating a verification request, selected by `type`:\n`WALLET` (a blockchain wallet address) or `EXTERNAL_ID` (your own identifier for the user).\nEmail magic-link sign-in is enabled automatically whenever an email is given and does not\nneed to be listed.", "discriminator": { "propertyName": "type" } }, "VerificationRequest": { "type": "object", "required": [ "id", "identityId", "flowId", "flowStepId", "organizationId", "customData", "status", "attemptsCount" ], "properties": { "amlResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AmlResult" } ] }, "attemptsCount": { "type": "integer", "format": "int32" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "customData": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "dvResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DvResult" } ] }, "flowId": { "type": "string", "format": "uuid" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": "string", "format": "uuid" }, "formResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FormResult" } ] }, "geolocationResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeolocationResult" } ] }, "id": { "type": "string", "format": "uuid" }, "identity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Identity" } ] }, "identityId": { "type": "string", "format": "uuid" }, "kybResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KybResult" } ] }, "organizationId": { "type": "string", "format": "uuid" }, "phoneResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PhoneResult" } ] }, "poaResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PoaResult" } ] }, "reason": { "type": [ "string", "null" ] }, "replayerZid": { "type": [ "string", "null" ] }, "spidResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpidResult" } ] }, "status": { "$ref": "#/components/schemas/VerificationRequestStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "walletResult": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WalletResult" } ] } } }, "VerificationRequestStatus": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED", "QUEUED", "PROCESSING", "REQUIRES_MANUAL_REVIEW", "REQUIRES_ADMIN_REVIEW", "REJECTED" ] }, "VerifyGeolocationProofRequest": { "type": "object", "required": [ "coords", "timestamp", "nonce", "permissionStatus", "rtcCandidates", "isSecureContext", "deviceFingerprint" ], "properties": { "cloudflareTrace": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudflareTracePayload" } ] }, "coords": { "$ref": "#/components/schemas/GeolocationCoordinates" }, "deviceFingerprint": { "type": "string" }, "isSecureContext": { "type": "boolean" }, "nonce": { "type": "string" }, "permissionStatus": { "type": "string" }, "rtcCandidates": { "type": "array", "items": { "type": "string" } }, "timestamp": { "type": "integer", "format": "int64" } } }, "VerifyGeolocationProofResponse": { "type": "object", "required": [ "verificationRequestId" ], "properties": { "verificationRequestId": { "type": "string", "format": "uuid" } } }, "VerifyPhoneCodeRequest": { "type": "object", "required": [ "code", "phoneNumberE164" ], "properties": { "code": { "type": "string" }, "phoneNumberE164": { "type": "string" } } }, "VerifyPhoneCodeResponse": { "type": "object", "required": [ "verificationRequestId" ], "properties": { "verificationRequestId": { "type": "string", "format": "uuid" } } }, "VerifyWalletSignatureRequest": { "type": "object", "required": [ "signature", "address", "chain" ], "properties": { "address": { "type": "string" }, "chain": { "$ref": "#/components/schemas/SiwxChain" }, "signature": { "type": "string" } } }, "VerifyWalletSignatureResponse": { "type": "object", "required": [ "verificationRequestId" ], "properties": { "verificationRequestId": { "type": "string", "format": "uuid" } } }, "WalletConfig": { "type": "object", "required": [ "chains" ], "properties": { "chains": { "type": "array", "items": { "$ref": "#/components/schemas/SiwxChain" } }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "example": "{ \"default\": \"Next step\" }" } } }, "WalletIdentifierPayload": { "type": "object", "description": "Blockchain wallet used as (or alongside) an email to identify a user.", "required": [ "chain", "address" ], "properties": { "address": { "type": "string" }, "chain": { "$ref": "#/components/schemas/SiwxChain" } } }, "WalletResult": { "type": "object", "required": [ "id", "status", "message", "signature", "walletAddress", "walletChain", "flowResultId" ], "properties": { "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "flowResultId": { "type": "string", "format": "uuid" }, "flowStep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FlowStep" } ] }, "flowStepId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "signature": { "type": "string" }, "status": { "$ref": "#/components/schemas/ResultStatus" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationRequestId": { "type": [ "string", "null" ], "format": "uuid" }, "walletAddress": { "type": "string" }, "walletChain": { "type": "string" } } }, "WalletStepOutput": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ResultStatus" } } }, "WebhookEventType": { "type": "string", "description": "A webhook event type. Use these values to choose which events a webhook subscription\nreceives. Existing values are stable; new event types may be added over time, so ignore any\nyou do not recognise.", "enum": [ "verification.dv.completed", "verification.dv.failed", "verification.dv.review", "verification.poa.completed", "verification.poa.failed", "verification.poa.review", "verification.form.completed", "verification.form.failed", "verification.form.review", "verification.spid.completed", "verification.spid.failed", "verification.spid.review", "verification.phone.completed", "verification.phone.failed", "verification.phone.review", "verification.wallet.completed", "verification.wallet.failed", "verification.wallet.review", "verification.kyb.completed", "verification.kyb.failed", "verification.kyb.review", "verification.kyb.submitted", "verification.geolocation.completed", "verification.geolocation.failed", "verification.geolocation.review", "verification.aml.produced", "verification.aml.refreshed", "verification.aml.moderated", "verification.document.expired", "verification.kyc.expired", "flow.risk.reevaluated", "flow.completed", "transaction.alert.created", "transaction.alert.resolved", "kyc_passport.verification.updated" ] }, "WebhookPayloadVersion": { "type": "string", "description": "Which payload shape an endpoint receives.", "enum": [ "LEGACY_V1", "V2" ] }, "WorkerScenario": { "oneOf": [ { "type": "string", "description": "User-initiated verification request via SDK/API.", "enum": [ "USER_INITIATED" ] }, { "type": "object", "description": "Started by another background process, whose kind is given as the value (e.g. an AML\nscreening started when document verification completes).", "required": [ "TRIGGERED_BY_WORKER" ], "properties": { "TRIGGERED_BY_WORKER": { "$ref": "#/components/schemas/WorkerType", "description": "Started by another background process, whose kind is given as the value (e.g. an AML\nscreening started when document verification completes)." } } }, { "type": "string", "description": "Admin-initiated manual review action.", "enum": [ "ADMIN_ACTION" ] }, { "type": "string", "description": "One-click reuse of previous verification data.", "enum": [ "ONE_CLICK_REUSE" ] } ], "description": "What started a background process. The same kind of process can be started in different\nways, e.g. an AML screening started by a completed document verification or by an admin." }, "WorkerType": { "type": "string", "description": "A kind of background process. In `source.workerType` it is the process that recorded the audit\nevent (for example `AML` for an AML screening). As the value of `TRIGGERED_BY_WORKER` it is the\nprocess that started it (for example `DV` when a completed document verification starts that\nAML screening).", "enum": [ "DV", "LIVENESS", "AML", "POA", "SPID", "FORM", "ONE_CLICK_DV", "ONE_CLICK_FORM", "MANUAL_REVIEW", "TM", "KYB_CASE" ] }, "WorkflowContext": { "type": "object", "description": "Context data available to JDM rules during flow evaluation.\n\nThis structure is serialized to JSON and passed to the Zen Engine for evaluation.\nJDM rules can access any field to make routing decisions.\n\n# Example JDM Access Patterns\n\nIn JDM rules, you can access:\n- `identity.email` - User's email address\n- `jdmData.my_step_slug.data.issuingCountry` - Output from a previous step\n- `customData.someKey` - Custom data passed during flow\n\n# Serialization\n\nFields are serialized with camelCase naming to match JDM conventions.", "required": [ "dvResults", "poaResults", "amlResults", "formResults", "kybResults", "spidResults", "phoneResults", "walletResults", "customData" ], "properties": { "amlResults": { "type": "array", "items": { "$ref": "#/components/schemas/AmlResult" }, "description": "AML screening results" }, "customData": { "type": "object", "description": "Custom data passed during flow execution", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "dvResults": { "type": "array", "items": { "$ref": "#/components/schemas/DvResult" }, "description": "Document verification results" }, "formResults": { "type": "array", "items": { "$ref": "#/components/schemas/FormResult" }, "description": "Form submission results" }, "identity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Identity", "description": "Identity information (user data)" } ] }, "jdmData": { "type": "object", "description": "Structured data from previous step executions for JDM consumption", "additionalProperties": { "$ref": "#/components/schemas/FlowStepOutput" }, "propertyNames": { "type": "string" } }, "kybResults": { "type": "array", "items": { "$ref": "#/components/schemas/KybResult" }, "description": "KYB verification results" }, "phoneResults": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneResult" }, "description": "Phone verification results" }, "poaResults": { "type": "array", "items": { "$ref": "#/components/schemas/PoaResult" }, "description": "Proof of address results" }, "spidResults": { "type": "array", "items": { "$ref": "#/components/schemas/SpidResult" }, "description": "SPID verification results" }, "walletResults": { "type": "array", "items": { "$ref": "#/components/schemas/WalletResult" }, "description": "Wallet verification results" } } }, "WorkflowEdge": { "type": "object", "description": "An edge connecting two nodes in the workflow graph.\n\nEdges represent the flow of control between nodes.\nFor conditional branching (from Operator nodes), edges can have labels\nlike \"true\" or \"false\" to indicate which path to take.", "required": [ "id", "sourceId", "targetId" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this edge." }, "label": { "type": [ "string", "null" ], "description": "Optional label for conditional edges.\n\nFor edges from Branch operator nodes:\n- \"true\": taken when condition evaluates to true\n- \"false\": taken when condition evaluates to false" }, "sourceId": { "type": "string", "format": "uuid", "description": "The ID of the source node (where this edge starts)." }, "targetId": { "type": "string", "format": "uuid", "description": "The ID of the target node (where this edge ends)." } } }, "WorkflowEvaluationResult": { "allOf": [ { "description": "Additional data returned by the evaluation (for extensibility)" }, { "type": "object", "properties": { "nextStepSlug": { "type": [ "string", "null" ], "description": "Slug of the next step to execute.\nIf None, the flow continues with linear order or completes." } } } ], "description": "Result of a workflow evaluation.\n\nThe Zen Engine returns this structure after evaluating a JDM against a context.\nThe `next_step_slug` field determines which flow step to execute next." }, "WorkflowGraph": { "type": "object", "description": "A workflow graph consisting of nodes and edges.\n\nThe graph defines the structure of a workflow:\n- One Start node where execution begins\n- One or more End nodes where execution terminates\n- Step nodes representing actual workflow steps\n- Operator nodes for conditional branching\n- Edges connecting nodes together", "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "All edges connecting nodes." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" }, "description": "All nodes in the graph." } } }, "WorkflowNode": { "oneOf": [ { "type": "object", "description": "The start node - entry point of the workflow.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this node." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkflowNodeMetadata", "description": "Optional metadata for UI layout." } ] }, "type": { "type": "string", "enum": [ "START" ] } } }, { "type": "object", "description": "An end node - terminal point of the workflow.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this node." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkflowNodeMetadata", "description": "Optional metadata for UI layout." } ] }, "type": { "type": "string", "enum": [ "END" ] } } }, { "type": "object", "description": "A step node representing a workflow step.", "required": [ "id", "stepSlug", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this node." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkflowNodeMetadata", "description": "Optional metadata for UI layout." } ] }, "stepSlug": { "type": "string", "description": "The slug of the flow step this node represents." }, "type": { "type": "string", "enum": [ "STEP" ] } } }, { "type": "object", "description": "An operator node for conditional branching.", "required": [ "id", "operator", "type" ], "properties": { "branches": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/BranchCondition" }, "description": "The branches to evaluate (required for Switch operator)." }, "condition": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Condition", "description": "The condition to evaluate (required for Branch operator)." } ] }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this node." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkflowNodeMetadata", "description": "Optional metadata for UI layout." } ] }, "operator": { "$ref": "#/components/schemas/LogicalOperator", "description": "The type of logical operator." }, "type": { "type": "string", "enum": [ "OPERATOR" ] } } }, { "type": "object", "description": "An action node for database operations.", "required": [ "id", "config", "type" ], "properties": { "config": { "$ref": "#/components/schemas/ActionConfig", "description": "The configuration for this action." }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for this node." }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkflowNodeMetadata", "description": "Optional metadata for UI layout." } ] }, "type": { "type": "string", "enum": [ "ACTION" ] } } } ], "description": "A node in the workflow graph.\n\nNodes represent different types of elements in a workflow:\n- `Start`: The entry point of the workflow\n- `End`: A terminal point where the workflow completes\n- `Step`: A workflow step that executes some action\n- `Operator`: A conditional branching point", "discriminator": { "propertyName": "type" } }, "WorkflowNodeMetadata": { "type": "object", "description": "Metadata for a workflow node.\n\nContains UI-specific information like position that doesn't affect execution logic.", "properties": { "position": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NodePosition", "description": "Position of the node in the canvas." } ] } }, "additionalProperties": { "description": "Additional metadata fields." } }, "WorkflowValue": { "type": "object", "title": "WorkflowValue", "description": "A dynamic workflow value: null, boolean, number, string, array, or object." }, "ZypheApiKey": { "type": "object", "required": [ "id", "organizationId", "keyType", "allowedOrigins", "options" ], "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "key": { "type": [ "string", "null" ], "description": "The key in clear, for Publishable keys and legacy Secret keys. `null` for Secret keys\ncreated since keys are stored by hash: those are returned once, when created." }, "keyHint": { "type": "string", "description": "Prefix and last four characters of the key (`zyphe_sk_…a1b2`), always present." }, "keyType": { "$ref": "#/components/schemas/ApiKeyType" }, "name": { "type": [ "string", "null" ] }, "options": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "organization": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Organization" } ] }, "organizationId": { "type": "string", "format": "uuid" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "zyphe_shared.types.Locale": { "type": "string", "description": "Locale identifier", "enum": [ "en", "it", "de", "es", "fr", "hi", "id", "pt" ] } }, "securitySchemes": { "jwt-auth": { "type": "apiKey", "in": "header", "name": "authorization", "description": "Set the token string including the 'Bearer ' prefix." }, "x-api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Set your API key in the x-api-key header." } } }, "tags": [ { "name": "SDK: Verification Requests" }, { "name": "SDK: Organizations" }, { "name": "SDK: KYB" }, { "name": "SDK: AML" }, { "name": "SDK: TIN Check" }, { "name": "API Keys" }, { "name": "Transaction Monitoring" } ] }