openapi: 3.0.3 info: title: zyphe-sdk description: '' license: name: '' version: 1.9.1 paths: /flows/{slug}/fullflow: get: tags: - Flows summary: Get full flow details 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 nullable: true 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 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 nullable: true 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 request 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 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 nullable: true - name: credentialType in: query description: >- Credential type for wallet or external-ID based resolution (`WALLET` or `EXTERNAL_ID`). required: false schema: allOf: - $ref: '#/components/schemas/CredentialType' nullable: true - name: chain in: query description: Wallet chain. Required when `credentialType` is `WALLET`. required: false schema: allOf: - $ref: '#/components/schemas/SiwxChain' nullable: true - name: address in: query description: Wallet address. Required when `credentialType` is `WALLET`. required: false schema: type: string nullable: true - name: externalId in: query description: >- External identifier. Required when `credentialType` is `EXTERNAL_ID`. required: false schema: type: string nullable: true - 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: >- Submits identity document images for document verification. 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 nullable: true 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: >- Retrieves the liveness challenge configuration for the current verification request. Use the returned data to present the liveness capture UI 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 nullable: true 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: >- Submits liveness capture data (selfie or video) for processing. Call this after completing the liveness challenge from `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 nullable: true 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: >- Submits the user's document selection (country and document type) to complete the document selection step. description: >- Call this after `next-step` returns a `document-selection` step, then call `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 nullable: true 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 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 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/{kyb_result_id}/reminders/ubo/{recipient_index}: post: tags: - 'SDK: KYB' summary: Send a UBO KYC reminder description: >- Sends (or re-sends) the KYC invitation email to a specific UBO on a KYB case, identified by their position in `uboDefinitions`. Use this to drive UBO outreach on demand — for example when automatic UBO KYC emails are disabled for the flow. operationId: sendUboKycReminder 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: 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 description: >- Adds one or more ultimate beneficial owners to an existing KYB case and returns the updated KYB result. operationId: addKybUbos 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/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' 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 description: >- Removes an ultimate beneficial owner from a KYB case by their stable id and returns the updated KYB result. operationId: removeKybUbo 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: 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' security: - api-key: [] /sdk/organizations/{organization_id}/kyb/{kyb_result_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 returns the updated KYB result. operationId: addKybDirectors 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/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' 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 description: >- Removes a director from a KYB case by their stable id and returns the updated KYB result. operationId: removeKybDirector 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: 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' security: - api-key: [] /sdk/organizations/{organization_id}/kyb/{kyb_result_id}/document-requests/on-demand: post: tags: - 'SDK: KYB' summary: Request a KYB document description: >- Requests an additional document from the business on a KYB case and returns the created document request. operationId: requestKybDocument 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/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}/aml/screen: post: tags: - 'SDK: AML' summary: Run a live AML screening and return the raw provider matches description: >- Queries the configured screening provider (OpenSanctions/Yente or WorldCheck) and returns its raw FollowTheMoney-shaped entity matches — no risk scoring, no persistence. This is the "Stage A only" slice of the on-demand AML flow. Billed per call via pay-as-you-go. 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: [] components: schemas: ActionConfig: oneOf: - type: object description: >- Set the status of a verification result. The 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' - 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. Tags 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. Each 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. This enum represents the possible status values that can be set via 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 description: Optional redirect information for flow router actions nullable: true targetFlowId: type: string format: uuid description: Optional target flow ID for flow router actions nullable: true timestamp: type: string format: date-time token: type: string description: Optional token for the target flow nullable: true 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 description: >- When present, the person is sent a KYC invitation and must complete full KYC for the KYB to be approvable. When absent, the person is screened by name only (AML) and is not notified — a clean name-AML result is sufficient (and required) for that person. nullable: true firstName: type: string gender: type: string lastName: type: string AddKybPersonsPayload: type: object description: >- Request body for `POST .../kyb/{kyb_result_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 nullable: true building: type: string city: type: string country: type: string flat: type: string houseNumber: type: string postalCode: type: string street: type: string AdverseMediaProviderKind: type: string description: >- Selected adverse-media provider, parsed from the `adverse_media_provider` config value so it can be matched exhaustively instead of compared as a string. enum: - VERIFY - ONE_MEDIA_CHECK - GROK AmlAdverseMediaArticle: type: object description: >- A single adverse-media article persisted on an AML result. This mirrors the provider's article shape but lives in `zyphe-shared` (which cannot depend on `zyphe-clients-interface`); the worker maps the provider response into this type before persisting. required: - title - snippet - url - source - language properties: eventGroup: type: string nullable: true language: type: string locations: type: array items: type: string publishedDate: type: string format: date-time nullable: true relevanceScore: type: number format: double nullable: true snippet: type: string source: type: string title: type: string topics: type: array items: type: string url: 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' 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' totalArticleCount: type: integer minimum: 0 totalEventCount: type: integer minimum: 0 AmlAgentReview: type: object description: >- Outcome of the latest agentic (Prosecutor → Defender → Judge) review of this screening, persisted on the result so the dispatcher does not re-review an unchanged screening and so a Suggest-mode verdict is visible as a suggestion. Scoped to one screening revision: like moderation forcing, it lapses when a re-screen bumps `checked_at` past `reviewed_at` (see [`AmlRiskResult::agent_review_in_force`]). required: - reviewedAt - policyVersion - verdictAction - enactedAction - rationale - residualRiskScore - suggested properties: enactedAction: $ref: '#/components/schemas/AmlAgentReviewAction' policyVersion: type: string description: >- Decision-policy version that produced the verdict (audit traceability). 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 for a human reviewer, nothing was enacted. verdictAction: $ref: '#/components/schemas/AmlAgentReviewAction' AmlAgentReviewAction: type: string description: >- The action a review decision resolves to, independent of its action-specific payload — the serde tag of the review engine's `Decision`. The camelCase encodings (`approve` / `requestClarification` / `escalate`) match the strings previously stored on `metadata.agentReview`, so existing records deserialize unchanged. 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. `#[serde(default)]` keeps existing person/company result rows (written before adverse-media screening) deserializable as `false`. 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 - dateOfBirth properties: dateOfBirth: type: string firstName: type: string 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. `#[serde(default)]` (→ `false`) covers legacy cached payloads that predate adverse-media screening. createdAt: type: string format: date-time data: allOf: - $ref: '#/components/schemas/AmlRiskResult' nullable: true id: type: string format: uuid namedPersonRef: type: string format: uuid description: >- For a name-only (email-less) UBO/director screening, the screened person's stable id (the `UboDefinition`/`DirectorDefinition` `id`); lets consumers correlate this AML row to its named person. `None` for verification-request-backed rows (person/company screenings). nullable: true pep: type: boolean sanctions: type: boolean subjectType: $ref: '#/components/schemas/AmlSubjectType' updatedAt: type: string format: date-time verificationRequestId: type: string format: uuid nullable: true AmlRiskMetadata: type: object required: - summary - checkedAt - controls properties: adverseMedia: allOf: - $ref: '#/components/schemas/AmlAdverseMediaResult' nullable: true agentReview: allOf: - $ref: '#/components/schemas/AmlAgentReview' nullable: true checkedAt: type: string format: date-time companyQuery: allOf: - $ref: '#/components/schemas/AmlCompanyQueryMetadata' nullable: true controls: type: array items: $ref: '#/components/schemas/ResultControlOperation' moderation: allOf: - $ref: '#/components/schemas/AmlModerationStatus' nullable: true query: allOf: - $ref: '#/components/schemas/AmlQueryMetadata' nullable: true 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 nullable: true AmlSubjectType: type: string description: >- The screened subject of an AML result. DTO mirror of the DB `AmlSubjectType` entity enum (converted via `From`); lets consumers tell a company AML result from a person one. Defaults to `Person` (every result predating this field was a person). enum: - PERSON - COMPANY ApiKeyType: type: string enum: - PUBLISHABLE - SECRET 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 format: date-time description: >- When this derivation last became active. Informational; `None` for legacy rows. nullable: true id: type: string format: uuid removedAt: type: string format: date-time description: Tombstone. `None` == active. This is the active predicate. nullable: true source: $ref: '#/components/schemas/RiskTagSource' tag: type: string weight: type: number format: double AssignedRiskTags: type: array items: $ref: '#/components/schemas/AssignedRiskTag' description: >- Newtype wrapper for the list of assigned risk tags stored as JSONB in the database. Required because SeaORM's `FromJsonQueryResult` cannot be derived for bare `Vec`. AuditAction: type: string description: >- All auditable actions. `JsonDisplay` / `JsonFromStr` keep `Display` and `FromStr` in sync with serde, so `.to_string()` always produces the DB-compatible string (e.g., `AuditAction::FlowCreated` → `"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_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 - 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_METADATA_PATCHED - KYB_BUSINESS_INFORMATION_EDITED - KYB_UBOS_ADDED - KYB_UBO_REMOVED - KYB_DIRECTORS_ADDED - KYB_DIRECTOR_REMOVED - KYB_AGENT_REVIEWED - 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 - 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 format: uuid nullable: true actorIp: type: string nullable: true actorRole: type: string nullable: true actorZid: type: string nullable: true createdAt: type: string format: date-time details: {} id: type: string format: uuid isSandbox: type: boolean description: >- Whether this entry originated from a sandbox operation. `null` = cross-cutting event (auth, org management) that spans both environments. nullable: true organizationId: type: string format: uuid nullable: true outcomeStatus: allOf: - $ref: '#/components/schemas/AuditOutcome' nullable: true resourceId: type: string format: uuid nullable: true resourceType: $ref: '#/components/schemas/AuditResourceType' sessionId: type: string description: >- Login-session identifier (`fid`). Stable across token refreshes within one browser session. nullable: true source: allOf: - $ref: '#/components/schemas/AuditSource' nullable: true 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 format: int32 description: >- Application-level error code from [`BaxeError`] (e.g. 200 for validation, 201 for deserialization). `None` when the error was not produced by the application's error framework. nullable: true minimum: 0 status: type: integer format: int32 description: Numeric HTTP status code (e.g. 400, 404, 500). minimum: 0 tag: type: string description: >- Semantic error tag string (e.g. `"BAD_REQUEST"`, `"NOT_FOUND"`, `"UNAUTHORIZED"`). nullable: true type: type: string enum: - httpError - type: object required: - type properties: type: type: string enum: - workerOk - type: object description: Background worker failed. required: - variant - type properties: type: type: string enum: - workerError variant: type: string description: >- Rust error-enum variant name (e.g. `"VaultLocked"`, `"UpsertDvResult"`). description: >- The outcome of the operation that produced an audit entry. Serialised to JSONB in the `outcomeStatus` column so the type structure is preserved and queryable (e.g. `WHERE "outcomeStatus"->>'type' = 'httpError'`). ## Variants - `httpSuccess { status }` — HTTP response with 2xx status code. - `httpError { status, code, tag }` — HTTP response with a non-2xx status. `status` is the numeric HTTP code; `code` and `tag` come from the [`BaxeError`] payload so investigators can see the application-level error identity without reading the response body. - `workerOk` — background worker completed successfully. - `workerError { variant }` — background worker failed; `variant` is the Rust error-enum variant name (e.g. `"VaultLocked"`, `"UpsertDvResult"`). discriminator: propertyName: type AuditResourceType: type: string description: >- All auditable resource types. Stored as PascalCase in the `resource_type` column. `Unknown` is used for auto-generated events where the middleware cannot determine the resource type (e.g. streaming responses, system operations), and as a catch-all for unrecognised values from the database. enum: - Search - Identity - Organization - OrganizationSettings - OrganizationTheme - OrganizationInvite - OrganizationBilling - SubscriptionPlan - KybJurisdictionPricing - ApiKey - Bot - Flow - FlowStep - FlowResult - FlowPartnerInvite - VerificationRequest - DvResult - AmlResult - PoaResult - KybResult - FormResult - Form - RiskWeight - ContextualFactor - ScoreDefinition - ScoreTag - AuditLog - ChatMessage - DocumentSelection - GeolocationResult - PhoneVerification - SpidResult - WalletVerification - Vault - KybUboData - DocumentDefinition - ConfigOverride - ShortUrl - Cache - 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: Background worker trigger. required: - workerType - scenario - type properties: scenario: $ref: '#/components/schemas/WorkerScenario' type: type: string enum: - WORKER workerType: $ref: '#/components/schemas/WorkerType' - 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: >- The origin/trigger of an audit event. All audit events MUST have a source - this allows filtering/excluding events by their origin and provides context for investigations. ## Variants - `Http` — Event originated from an HTTP request (method + path). - `Worker` — Event emitted by a background worker (type + scenario). - `Scheduled` — Event from a scheduled/cron task (task name). discriminator: propertyName: type AutoOneClickKycConfig: type: object required: - partnerConfigs properties: labels: type: object additionalProperties: 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 items: $ref: '#/components/schemas/Flow' description: Full partner flow objects (populated by rehydrate_flow_step) nullable: true 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 If 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 nullable: true BotTokenScope: type: string description: >- Describes the visibility scope of a bot token. - `Organization` — the bot is connected to one specific organisation and is only visible in that organisation's bot list. - `Platform` — the bot is a platform-root identity (no `default_organization_id`) and is visible in every organisation's bot list. Stored inside the `credentialData` JSONB of the `BOT_TOKEN` credential row. `Organization` is the default to ensure backward-compatible deserialization of 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' 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 description: >- The AI agent's one-sentence explanation of why this match classification was chosen. Present only when the agent was invoked (i.e. an LLM cross-check was performed). nullable: true catalogValue: type: string description: The value extracted from the company catalog API. nullable: true disagreementSources: type: array items: $ref: '#/components/schemas/BusinessInfoDisagreementSource' description: Sources that disagree with one another for this field. documentValue: type: string description: The value extracted from the uploaded document(s). nullable: true matchType: $ref: '#/components/schemas/BusinessInfoMatchType' submittedValue: type: string description: The user-submitted value for this field. nullable: true suggestedValue: type: string description: >- The canonical corrected value recommended by the AI agent. When a suggested value is safely applied, `run_business_info_cross_check` stores the field as `AutoCorrect`. `Mismatch` and `NotFound` suggestions are surfaced for manual review without mutating the stored record. nullable: true 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 BusinessInformationClarificationResponse: type: object description: >- Parsed representation of the client's clarification response stored inside `reviewReason` JSON. Present only on document requests of that type after the 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 items: $ref: '#/components/schemas/BusinessInformationClarificationResponseField' description: >- Field updates proposed by the client. Absent or empty when `decision` is `"confirm"`. Stored metadata uses key `"updates"`; API and legacy use `"fields"`. nullable: true 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. CheckStatus: type: string description: >- Provider-agnostic check status. This enum represents the canonical outcome of any verification check, abstracting away provider-specific status codes. # Deserialization Supports both string format ("passed", "failed", etc.) and legacy integer codes: - 0 = Passed (OK in Regula) - 1 = Failed (Error in Regula) - 2 = NotPerformed (Was not done in Regula) 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 nullable: true ip: type: string nullable: true loc: type: string nullable: true ts: type: string nullable: true visitScheme: type: string nullable: true 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 CreateTopupCheckoutRequest: type: object description: >- Request to create a payment-mode Stripe Checkout session for a one-time credit top-up purchase (`POST .../billing/topup/checkout`). required: - priceId properties: priceId: type: string description: |- The Stripe price ID of the top-up pack to purchase, as returned by `GET .../billing/topup-packs`. redirectUri: type: string description: >- Optional redirect URI after checkout. If not provided, redirects to the webapp root. nullable: true CreateVerificationRequestPayload: allOf: - $ref: '#/components/schemas/VerificationIdentifier' - type: object required: - termsAndConditionsAccepted - privacyPolicyAccepted - cookiesPolicyAccepted properties: continueUrl: type: string nullable: true cookiesPolicyAccepted: type: boolean customData: type: object additionalProperties: {} nullable: true flowStepId: type: string format: uuid nullable: true 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 apart from admin- or partner-provisioned orgs (e.g. to force self-serve orgs to pick a real plan instead of the custom plan). - `SelfServe` — public signup with no invite. - `Admin` — created by platform staff; also the default for pre-existing orgs. - `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 required: - type properties: type: type: string enum: - periodEnd - type: object required: - type properties: type: type: string enum: - never - type: object description: |- Rolling validity: each grant expires `months` after it was granted, snapped 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, snapped 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: |- Plan credit expiry policy — replaces the former `carry_over` bool. Determines the `expires_at` of Stripe Credit Grants created at renewal. Stored as JSONB on `SubscriptionPlan.creditExpiryPolicy`. discriminator: propertyName: type Currency: type: string example: usd CustomDocumentConfig: type: object required: - name - id properties: enabled: type: boolean id: type: string format: uuid name: type: string required: type: boolean DirectorDefinition: type: object required: - firstName - lastName - dateOfBirth - country - gender properties: country: type: string dateOfBirth: type: string emailAddress: type: string description: >- Email of the director. `None` for a name-only director added without an email. nullable: true firstName: type: string gender: type: string id: type: string format: uuid description: >- Stable identifier for this director within the KYB result. See [`UboDefinition::id`]. nullable: true lastName: type: string Document: type: object required: - id - metadata - path - type - typeName - createdAt - updatedAt - vaultId properties: createdAt: type: string format: date-time expiresAt: type: string format: date-time nullable: true 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 DocumentConfig: type: object properties: onDemand: type: boolean description: >- Whether this document is requested on demand by a reviewer (excluded from the required-document gate and the end-user's upload form) instead of being demanded upfront. Configurable per document. `None` means "unset" — the backend then applies the document's default: `proofOfAttorney` defaults to on-demand (`true`), every other default document defaults to upfront (`false`). An explicit value overrides that default. nullable: true required: type: boolean DocumentData: type: object required: - documentNumber - issuingState - issuingAuthority properties: documentCan: type: string documentClassCode: type: string documentNumber: type: string expiryDate: type: string format: date nullable: true issuingAuthority: type: string issuingDate: type: string format: date nullable: true issuingState: type: string mrzStrings: 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 DocumentScanStatus: type: object description: >- Status of various document scan checks. # Deserialization Supports both new abstract format and legacy Regula format: **New format:** ```json { "overall": "passed", "documentType": "passed", "expiry": "passed", "mrz": "passed" } ``` **Legacy Regula format:** ```json { "overallStatus": 0, "detailsOptical": { "docType": 1, "expiry": 0, "mrz": 2, ... }, "optical": 0, "portrait": 1, "rfid": 2, ... } ``` required: - overall - documentType - expiry - mrz properties: documentType: $ref: '#/components/schemas/CheckStatus' expiry: $ref: '#/components/schemas/CheckStatus' mrz: $ref: '#/components/schemas/CheckStatus' overall: $ref: '#/components/schemas/CheckStatus' DocumentSelectionConfig: type: object required: - countriesFilter - documentTypesFilter - enabledGovernmentProviders properties: allowedDocumentsPerCountry: type: object additionalProperties: type: array items: type: string nullable: true countriesFilter: $ref: '#/components/schemas/CountriesFilter' documentTypesFilter: $ref: '#/components/schemas/DocumentTypeFilter' documentTypesFilterPerCountry: type: object description: >- Optional per-country overrides for the document-type filter. Keys are ISO 3166-1 alpha-2 country codes. When a country is present here, its `DocumentTypeFilter` fully overrides `document_types_filter` for that country (no union/intersection). An explicit empty entry rejects the country entirely (the country gate fails, not just the document-type gate). The custom deserializer validates each key via `CountryInfo::from_any_country_code` and normalises the stored key to its `iso_alpha_2` upper-case form. additionalProperties: $ref: '#/components/schemas/DocumentTypeFilter' nullable: true enabledGovernmentProviders: type: object additionalProperties: type: array items: $ref: '#/components/schemas/SpidDocumentType' labels: type: object additionalProperties: type: string example: '{ "en_button_label": "Next step" }' DocumentSelectionStepOutput: type: object description: Document selection step output for workflow decisions. properties: country: type: string nullable: true documentType: type: integer format: int64 nullable: true DocumentTypeFilter: type: object required: - types properties: types: type: array items: type: string DocumentUpload: type: object required: - filename properties: documentType: type: string nullable: true filename: type: string presignedUrl: type: string nullable: true s3Key: type: string nullable: true DvConfig: type: object required: - minimumAge properties: amlAgenticMode: allOf: - $ref: '#/components/schemas/KybAgenticMode' default: DISABLED documentSelectionStepId: type: string format: uuid incodeConfigurationId: type: string description: >- Incode configuration ID the frontend must use when creating the capture session. Computed server-side during rehydration from `poa_from_govcheck` and the sandbox/live environment (see [`crate::types::dto::DvConfig`] rehydration in the core handler). It is never persisted: it defaults to `None` and is skipped when serializing `None`, so storing a config round-trips cleanly. nullable: true kycValiditySeconds: type: integer format: int64 description: |- How long (in seconds) a successful DV result remains valid before re-KYC is required. `None` = never expires (existing behaviour). nullable: true labels: type: object additionalProperties: type: string example: '{ "en_button_label": "Next step" }' maxAttempts: type: integer format: int32 example: '5' nullable: true minimum: 0 minimumAge: type: integer format: int32 minimum: 0 poaFromGovcheck: type: boolean description: >- When true, route Incode through the government-validation flow and, after the document scan, produce a PoA result (source DLDV) from the driver's-license address validation. Backward compatible: missing key deserializes to false. processImagesOverrides: allOf: - $ref: '#/components/schemas/ProcessImagesOverrides' nullable: true requiredDocumentFields: type: array items: $ref: '#/components/schemas/RequiredDocumentField' reverificationLeadSeconds: type: integer format: int64 description: >- How long (in seconds) *before* a result's expiry to begin re-verification: the flow is reopened and a re-verify reminder email is sent, so the holder can renew while their current result is still valid (continuous validity). `None` defaults to one week ([`DvConfig::DEFAULT_REVERIFICATION_LEAD_SECONDS`]). Ignored when `kyc_validity_seconds` is `None`; clamped to the validity window. nullable: true thresholds: type: object additionalProperties: type: number format: float nullable: true 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 - 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 DvResult: type: object required: - id - status - reasons - data - processAdditionalData - authenticityChecks properties: adminComment: type: string nullable: true authenticityChecks: type: array items: type: array items: type: integer format: int64 browser: type: string nullable: true class: type: string nullable: true countryCode: type: string nullable: true createdAt: type: string format: date-time nullable: true data: type: object additionalProperties: {} documentId: type: string format: uuid nullable: true documentScorePercent: type: integer format: int32 nullable: true documentType: type: integer format: int32 nullable: true flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid manualReviewAt: type: string format: date-time nullable: true manualReviewNote: type: string nullable: true manualReviewerId: type: string format: uuid nullable: true manualReviewerZid: type: string nullable: true originalVrHistoryId: type: string format: uuid nullable: true platform: type: string nullable: true portraitMatchPercent: type: integer format: int32 nullable: true processAdditionalData: $ref: '#/components/schemas/ProcessAdditionalData' provinceCode: type: string nullable: true reasons: type: array items: $ref: '#/components/schemas/DvReason' status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true validUntil: type: string format: date-time description: >- When this KYC result expires and re-verification is required (re-KYC validity). `null` means it never expires (no `kyc_validity_seconds` configured, or a legacy result). nullable: true verificationRequestId: type: string format: uuid nullable: true DvStepOutput: type: object required: - status - numberOfAttempts properties: amlPep: type: boolean nullable: true amlRiskScorePercent: type: integer format: int32 nullable: true amlSanctions: type: boolean nullable: true dateOfExpiry: type: string format: date-time nullable: true documentType: type: integer format: int32 nullable: true issuingCountry: type: string nullable: true livenessStatus: allOf: - $ref: '#/components/schemas/ResultStatus' nullable: true 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 (name, surname, date of birth, age, etc.). Each entry maps a stable `condition_hash` (16-char hex, see `matcher::precompile::condition_hash`) to the boolean result of evaluating that condition against the live in-memory `VaultDocument` at the moment the DV background job ran. Flattened into the serialized output so each hash becomes a top-level sibling of `status`, `issuingCountry`, etc. — referenceable as `"dv_step."`. At JDM evaluation time, `vault_condition::resolve_precompiled_graph` replaces any condition whose hash is present here with `Condition::Literal { value }`, so no vault PII ever needs to be stored in or read from the database. 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 - websocket - 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 - graph_validation - external_api - share_already_has_write_access - share_does_not_have_write_access - write_access_already_revoked - invite_required - billing - product_not_active ExecutedAction: type: object description: Represents an executed action with its ID and type. required: - actionId - actionConfig properties: actionConfig: $ref: '#/components/schemas/ActionConfig' actionId: type: string format: uuid description: The unique identifier of the action node. FactorKey: oneOf: - type: object required: - type - value 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 answer maps to its own FORM factor — e.g. a country select). `AnswerValue` on a `Select` field authors one `ScoreFactor` row per enumerated `SelectOptions.values` entry at form-sync time (`form_risk_sync::DesiredRisk::from_sections`), sharing the factor's multiplier, so any of those answers resolves to a real multiplier at score time. **Remaining gap (D-13):** a field has no enumerable option set to author against when it is not a `Select` (e.g. free-text `Text`), or when it is a `Select` with `isOtherAllowed: true` and the submitted answer is the free-text "Other" value. In those cases the emitted `AnswerValue` key in `FormResult.riskFactorKeys` has no matching `ScoreFactor` row, the score-time lookup returns `None`, and the factor's multiplier is silently skipped (undercounting the contextual 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 description: >- Target ScoreDefinition key. None = "forms" (100% backward compatible). nullable: true key: $ref: '#/components/schemas/FactorKey' multiplier: type: number format: double when: allOf: - $ref: '#/components/schemas/Condition' nullable: true FieldRiskTag: type: object required: - tag - weight properties: definitionKey: type: string description: >- Target ScoreDefinition key. None = "forms" (100% backward compatible). nullable: true tag: type: string weight: type: number format: double when: allOf: - $ref: '#/components/schemas/Condition' nullable: true 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 - webhookUrl - successUrl - steps - jdm properties: createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true 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 format: uuid description: >- The theme this flow renders with; `None` means use the org default theme. nullable: true updatedAt: type: string format: date-time nullable: true webhookUrl: type: string 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 format: date-time nullable: true customData: type: object additionalProperties: {} nullable: true dvResults: type: array items: $ref: '#/components/schemas/DvResult' flow: allOf: - $ref: '#/components/schemas/Flow' nullable: true 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: allOf: - $ref: '#/components/schemas/Identity' nullable: true jdmData: type: object additionalProperties: $ref: '#/components/schemas/FlowStepOutput' kybResults: type: array items: $ref: '#/components/schemas/KybResult' organization: allOf: - $ref: '#/components/schemas/Organization' nullable: true organizationId: type: string format: uuid phoneResults: type: array items: $ref: '#/components/schemas/PhoneResult' poaResults: type: array items: $ref: '#/components/schemas/PoaResult' reviewSuggestion: allOf: - $ref: '#/components/schemas/ReviewSuggestion' nullable: true riskScorePercent: type: integer format: int32 description: >- Composed global risk score for the flow (0–100). `None` if not yet scored. nullable: true spidResults: type: array items: $ref: '#/components/schemas/SpidResult' status: $ref: '#/components/schemas/VerificationRequestStatus' updatedAt: type: string format: date-time nullable: true 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 format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - DV updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/FormConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - FORM updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/PoaConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - POA updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/KybConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - KYB updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/SpidConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - SPID updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/PhoneConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - PHONE updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/WalletConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - WALLET updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/LivenessConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - LIVENESS updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/AutoOneClickKycConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - AUTO_ONE_CLICK_KYC updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/DocumentSelectionConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - DOCUMENT_SELECTION updatedAt: type: string format: date-time nullable: true - type: object required: - id - name - slug - config - flowId - order - type properties: config: $ref: '#/components/schemas/GeolocationConfig' createdAt: type: string format: date-time nullable: true failureUrl: type: string nullable: true flowId: type: string format: uuid gotoStepId: type: string format: uuid nullable: true id: type: string format: uuid name: type: string order: type: integer format: int32 slug: type: string successUrl: type: string nullable: true type: type: string enum: - GEOLOCATION updatedAt: type: string format: date-time nullable: true 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 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 format: date-time nullable: true FAILURE_URL: type: string nullable: true FLOW_ID: type: string format: uuid GOTO_STEP_ID: type: string format: uuid nullable: true 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 nullable: true UPDATED_AT: type: string format: date-time nullable: true FlowStepOutput: oneOf: - type: object required: - type - data properties: data: $ref: '#/components/schemas/DvStepOutput' type: type: string enum: - DV - type: object required: - type - data properties: data: $ref: '#/components/schemas/PoaStepOutput' type: type: string enum: - POA - type: object required: - type - data properties: data: $ref: '#/components/schemas/SpidStepOutput' type: type: string enum: - SPID - type: object required: - type - data properties: data: $ref: '#/components/schemas/WalletStepOutput' type: type: string enum: - WALLET - type: object required: - type - data properties: data: $ref: '#/components/schemas/PhoneStepOutput' type: type: string enum: - PHONE - type: object required: - type - data properties: data: $ref: '#/components/schemas/FormStepOutput' type: type: string enum: - FORM - type: object required: - type - data properties: data: $ref: '#/components/schemas/KybStepOutput' type: type: string enum: - KYB - type: object required: - type - data properties: data: $ref: '#/components/schemas/LivenessStepOutput' type: type: string enum: - LIVENESS - type: object required: - type - data properties: data: $ref: '#/components/schemas/AutoOneClickKycStepOutput' type: type: string enum: - AUTO_ONE_CLICK_KYC - type: object required: - type - data properties: data: $ref: '#/components/schemas/ActionStepOutput' type: type: string enum: - ACTION - type: object required: - type - data properties: data: $ref: '#/components/schemas/DocumentSelectionStepOutput' type: type: string enum: - DOCUMENT_SELECTION - type: object required: - type - data properties: data: $ref: '#/components/schemas/GeolocationStepOutput' type: type: string enum: - GEOLOCATION discriminator: propertyName: type FlowStepType: type: string enum: - DV - FORM - POA - KYB - SPID - PHONE - WALLET - LIVENESS - AUTO_ONE_CLICK_KYC - DOCUMENT_SELECTION - GEOLOCATION Form: type: object required: - id - organizationId - name - sections properties: createdAt: type: string format: date-time nullable: true description: type: string nullable: true id: type: string format: uuid name: type: string organizationId: type: string format: uuid sections: type: array items: $ref: '#/components/schemas/FormSection' updatedAt: type: string format: date-time nullable: true FormAnswerSection: type: object required: - name - answers properties: answers: type: object additionalProperties: {} name: type: string FormConfig: type: object required: - formId properties: form: allOf: - $ref: '#/components/schemas/Form' nullable: true formId: type: string format: uuid labels: type: object additionalProperties: type: string example: '{ "default": "Next step" }' oneClickMaxAgeSeconds: type: integer format: int64 nullable: true FormItem: oneOf: - type: object required: - type - content properties: content: $ref: '#/components/schemas/InputField' type: type: string enum: - InputField - type: object required: - type - content 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 items: $ref: '#/components/schemas/AssignedRiskTag' description: Risk tags assigned during form scoring. `None` if not scored. nullable: true createdAt: type: string format: date-time nullable: true flowResultId: type: string format: uuid flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true form: allOf: - $ref: '#/components/schemas/Form' nullable: true formId: type: string format: uuid nullable: true id: type: string format: uuid reason: allOf: - $ref: '#/components/schemas/FormReason' nullable: true riskFactorKeys: type: array items: type: string description: Risk factor keys matched during form scoring. `None` if not scored. nullable: true sections: type: array items: $ref: '#/components/schemas/FormSection' status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true FormSection: type: object required: - name - label - items properties: items: type: array items: $ref: '#/components/schemas/FormItem' label: type: object additionalProperties: type: string name: type: string FormStepOutput: type: object description: >- Form step output for workflow decisions. # Field Name Restrictions The `fields` HashMap is flattened during serialization. Form field names must not conflict with the reserved field names "status" and "riskScorePercent", as this would create duplicate keys in the serialized JSON output, resulting in invalid JSON. required: - status properties: status: $ref: '#/components/schemas/ResultStatus' additionalProperties: description: >- Dynamic form fields flattened into the output. Note: Field names must not conflict with "status" or "riskScorePercent" to avoid duplicate keys during serialization. GeolocationConfig: type: object properties: ipValidation: type: boolean example: 'true' labels: type: object additionalProperties: 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 nullable: true createdAt: type: string format: date-time nullable: true deviceFingerprint: type: string nullable: true flowResultId: type: string format: uuid flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid ipAddress: type: string nullable: true reason: type: string nullable: true status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true vpn: type: boolean GeolocationStepOutput: type: object description: Geolocation step output for workflow decisions. properties: blacklistedIp: type: boolean country: type: string nullable: true deviceFingerprint: type: string nullable: true ipAddress: type: string nullable: true 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 items: type: string nullable: true organizationId: type: string format: uuid organizationName: type: string settings: $ref: '#/components/schemas/Settings' theme: allOf: - $ref: '#/components/schemas/Theme' nullable: true 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. The `mode` discriminant tells the client which capture flow to perform: - `"ACTIVE"` — head-movement challenge; the client captures movements and uploads movement images + video + calibration image. - `"PASSIVE"` — selfie-only; the client uploads only a calibration image. No movements are required. discriminator: propertyName: mode GetNextStepPayload: type: object properties: address: type: string description: Wallet address. Required when `credentialType` is `WALLET`. nullable: true chain: allOf: - $ref: '#/components/schemas/SiwxChain' nullable: true credentialType: allOf: - $ref: '#/components/schemas/CredentialType' nullable: true email: type: string description: >- Email address of the user whose verification progress should be queried. nullable: true externalId: type: string description: >- External identifier. Required when `credentialType` is `EXTERNAL_ID`. nullable: true GetNextStepResponse: type: object required: - isCompleted properties: customData: type: object description: Custom data associated with the flow result, if one exists. additionalProperties: {} nullable: true 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 format: uuid description: The ID of the flow result record, if one exists for this user. nullable: true isCompleted: type: boolean description: Whether the user has completed all required steps in the flow. nextStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true GetVerificationRequestResponse: type: object required: - verificationRequest - identity properties: externalId: type: string description: External ID credential configured for this identity, if any. nullable: true identity: $ref: '#/components/schemas/Identity' passkey: allOf: - $ref: '#/components/schemas/VaultUnlockPasskeyData' nullable: true verificationRequest: $ref: '#/components/schemas/VerificationRequest' wallet: allOf: - $ref: '#/components/schemas/WalletIdentifierPayload' nullable: true 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 format: date-time nullable: true defaultOrganizationId: type: string format: uuid nullable: true email: type: string nullable: true emailVerified: type: boolean id: type: string format: uuid isActive: type: boolean role: $ref: '#/components/schemas/Role' settings: $ref: '#/components/schemas/IdentitySettings' updatedAt: type: string format: date-time nullable: true zid: type: string IdentitySettings: type: object required: - locale properties: lastEnvironmentIsSandbox: type: boolean locale: $ref: '#/components/schemas/Locale' ImageQualityCheckResult: type: object description: >- Result of an image quality check. # Deserialization Supports both new abstract format and legacy Regula format: **New format:** ```json { "checkType": "focus", "result": "passed", "probability": 97 } ``` **Legacy Regula format (single item from 'list'):** ```json { "type": 1, "result": 0, "probability": 97, "featureType": 0, "mean": 0.0, "stdDev": 0.0 } ``` required: - checkType - result properties: checkType: $ref: '#/components/schemas/ImageQualityCheckType' probability: type: integer format: int32 nullable: true result: $ref: '#/components/schemas/CheckStatus' ImageQualityCheckType: type: string description: |- Types of image quality checks. # Deserialization Supports both string format and legacy Regula integer type codes: - 0 = Glare (ImageGlares) - 1 = Focus (ImageFocus) - 2 = Resolution (ImageResolution) - 3 = Colorness (ImageColorness) - 4 = Perspective (ImagePerspective) - 5 = Bounds (ImageBounds) - 6 = ScreenCapture (ImageScreenCapture) - 7 = Portrait (ImagePortrait) enum: - glare - focus - resolution - colorness - perspective - bounds - screen_capture - portrait - image_quality - unknown InputField: oneOf: - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - date value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - text validationRegex: type: string description: >- Optional regex pattern validated against the submitted value. Written by the platform admin at form-build time; both frontend and backend validate against it on submission. nullable: true value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - number validationRegex: type: string description: >- Optional regex pattern validated against the stringified submitted number. nullable: true value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - textarea validationRegex: type: string description: Optional regex pattern validated against the submitted value. nullable: true value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - checkbox value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: $ref: '#/components/schemas/FileOptions' requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - file value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - optionLabels - type properties: label: type: object additionalProperties: 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 options: $ref: '#/components/schemas/SelectOptions' requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - select value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true - type: object required: - label - name - options - type properties: label: type: object additionalProperties: type: string name: type: string options: {} requiredWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true risk: allOf: - $ref: '#/components/schemas/FieldRiskConfig' nullable: true type: type: string enum: - place value: nullable: true visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true 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' source: type: string description: Image source identifier value: type: string description: Base64-encoded image data InputImagePageIndex: type: string description: |- Page index for input images. Serialized as camelCase strings for frontend compatibility: "front" and "back". enum: - front - back KybAgenticMode: type: string description: >- Per-domain agentic review mode shared by the compliance review agents (KYB, AML, …): `Disabled` → never dispatched; `Suggest` → the terminal approve/clear action is suppressed and recorded as a suggestion; `AutoPilot` → the actuator may enact it behind the deterministic guards. `JsonFromStr`/`JsonDisplay` let deployment config carry a mode as its serde string (e.g. `SUGGEST`). Kept as the `KybAgenticMode` OpenAPI component for API compatibility. enum: - DISABLED - SUGGEST - AUTO_PILOT KybCommunication: type: object required: - id - kybResultId - senderIdentityId - recipientEmail - subject - body properties: body: type: string documentRequestId: type: string format: uuid nullable: true id: type: string format: uuid kybResultId: type: string format: uuid recipientEmail: type: string senderIdentityId: type: string format: uuid sentAt: type: string format: date-time nullable: true subject: type: string KybConfig: type: object required: - kycFlowId properties: agenticMode: allOf: - $ref: '#/components/schemas/KybAgenticMode' default: DISABLED amlAgenticMode: allOf: - $ref: '#/components/schemas/KybAgenticMode' default: DISABLED articlesOfAssociation: allOf: - $ref: '#/components/schemas/DocumentConfig' nullable: true autoSendUboKycEmail: type: boolean description: >- When `false`, the KYC invitation email is NOT automatically sent to UBOs on KYB submission; a reviewer instead triggers it on demand via the UBO reminder endpoint (which sends the initial invitation for un-onboarded UBOs). Defaults to `true` (auto-send), preserving existing behavior. default: 'true' example: 'true' certificateOfIncorporation: allOf: - $ref: '#/components/schemas/DocumentConfig' nullable: true collectDirectors: type: boolean default: 'false' example: 'false' customCountryDocuments: type: object description: >- Per-org, per-country document overrides set by the org admin in the flow builder. Takes priority over platform-level document definitions for matching countries. Stored in the flow step config JSON. NOT used in extraction/cross-check. Keys are ISO 3166-1 alpha-2 codes (normalised from any ISO format on input). additionalProperties: type: array items: $ref: '#/components/schemas/KybCountryDocument' customDocuments: type: array items: $ref: '#/components/schemas/CustomDocumentConfig' nullable: true documentsPerCountry: type: object description: >- Merged per-country document map populated at rehydration time. Built by `rehydrate_flow_step` by merging platform-level DB definitions with org-admin `custom_country_documents` (custom wins per-country). This is the single source of truth for document requirements at runtime. Frontend uses this to render upload UI — no priority logic needed client-side. Also round-trips through cache so frontend always sees correct data. additionalProperties: type: array items: $ref: '#/components/schemas/KybCountryDocument' nullable: true kycFlowId: type: string format: uuid labels: type: object additionalProperties: 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 organizationalStructureChart: allOf: - $ref: '#/components/schemas/DocumentConfig' nullable: true proofOfAttorney: allOf: - $ref: '#/components/schemas/DocumentConfig' nullable: true KybCountryDocument: type: object description: |- A document required for KYB in a specific country. Populated at runtime via rehydration from the platform-level `document_definitions` table. Contains the extraction/validation schema for future LLM-driven field extraction. required: - key - label properties: key: type: string description: |- Machine-readable key used as the document type identifier (e.g. `"visura_camerale"`, `"certificate_of_incorporation"`). Unique within (scope, country). label: type: string description: Human-readable label shown to the user during the KYB flow. onDemand: type: boolean description: >- When `true`, the document is NOT demanded upfront (excluded from the required-document gate) and is instead requested on demand by a reviewer during review. Defaults to `false`. required: type: boolean description: |- Whether upload of this document is mandatory for KYB approval. Defaults to `true`. validationSchema: description: >- JSON schema for extraction/validation. Opaque for now — will be used by `KybDocumentIntelligenceService` for schema-driven field extraction. KybDocumentRequest: type: object required: - id - kybResultId - requestedByIdentityId - documentName - requestType - status properties: clarificationFields: type: array items: type: string description: >- Clarification field keys requested for review (for clarification requests only). nullable: true clarificationResponse: allOf: - $ref: '#/components/schemas/BusinessInformationClarificationResponse' nullable: true createdAt: type: string format: date-time nullable: true description: type: string nullable: true documentName: type: string fieldStatuses: type: object description: >- Per-field review statuses for clarification requests. Keys are field names (e.g. "companyName"), values are the review status for that field. additionalProperties: $ref: '#/components/schemas/FieldReviewStatus' nullable: true fulfilledAt: type: string format: date-time nullable: true id: type: string format: uuid kybResultId: type: string format: uuid presignedUrl: type: string nullable: true previousValues: type: object description: >- Snapshot of old business information field values before the client submitted updated values. Keys are field names, values are the previous string values. additionalProperties: type: string nullable: true requestType: $ref: '#/components/schemas/KybDocumentRequestType' requestedByIdentityId: type: string format: uuid reviewReason: allOf: - $ref: '#/components/schemas/KybDocumentReviewReason' nullable: true status: $ref: '#/components/schemas/KybDocumentRequestStatus' updatedAt: type: string format: date-time nullable: true uploadedFilename: type: string nullable: true uploadedS3Key: type: string nullable: true KybDocumentRequestStatus: type: string enum: - PENDING - UPLOADED - APPROVED - REJECTED KybDocumentRequestType: type: string description: >- The type of a KYB document request. - `Standard` — operator requests a named document (e.g. certificate of incorporation). The client uploads a file. - `Clarification` — operator requests the client to re-confirm or update specific business information fields. Supports per-field review via `field_statuses`. enum: - STANDARD - CLARIFICATION KybDocumentReviewReason: oneOf: - type: string - $ref: '#/components/schemas/BusinessInformationClarificationResponse' KybMetadata: type: object description: The KYB result metadata bag. Empty by default. properties: ownershipStructure: allOf: - $ref: '#/components/schemas/OwnershipStructure' nullable: true additionalProperties: description: >- Any other top-level key. Opaque to the backend, passed through verbatim. KybResult: type: object required: - id - status - pepAndSanctionsStatus properties: assignedAt: type: string format: date-time nullable: true assignedToIdentityId: type: string format: uuid nullable: true businessInformation: allOf: - $ref: '#/components/schemas/BusinessInformation' nullable: true businessInformationVerification: type: object additionalProperties: $ref: '#/components/schemas/BusinessInfoFieldVerification' nullable: true createdAt: type: string format: date-time nullable: true directorDefinitions: type: array items: $ref: '#/components/schemas/DirectorDefinition' nullable: true documentUploads: type: array items: $ref: '#/components/schemas/DocumentUpload' nullable: true effectiveRequiredDocuments: type: array items: $ref: '#/components/schemas/KybCountryDocument' description: >- The effective list of required KYB documents for this result's country. Resolved by `DocumentDefinitionService::resolve_for_country` using the full priority chain: platform DB definitions → org-admin `custom_country_documents` → global legacy fields. `None` until explicitly set by a caller with DB access (e.g. the MCP `get_kyb_result` tool). Not computed in the `From` conversion. nullable: true flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true fundedAt: type: string format: date-time nullable: true id: type: string format: uuid metadata: type: object description: |- Admin-curated metadata. Organizations read it; only admins write it. Empty (`{}`) when nothing has been recorded. nextAction: allOf: - $ref: '#/components/schemas/NextAction' nullable: true pepAndSanctionsStatus: $ref: '#/components/schemas/PepAndSanctionsStatus' reason: type: string nullable: true report: type: string nullable: true status: $ref: '#/components/schemas/ModerationResultStatus' uboDefinitions: type: array items: $ref: '#/components/schemas/UboDefinition' nullable: true updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true KybStepOutput: type: object description: KYB (Know Your Business) step output for workflow decisions. required: - status properties: amlPep: type: boolean nullable: true amlRiskScorePercent: type: integer format: int32 nullable: true amlSanctions: type: boolean nullable: true businessName: type: string nullable: true country: type: string nullable: true moderationStatus: allOf: - $ref: '#/components/schemas/ModerationResultStatus' nullable: true pepAndSanctionsStatus: allOf: - $ref: '#/components/schemas/PepAndSanctionsStatus' nullable: true registrationNumber: type: string nullable: true status: $ref: '#/components/schemas/ResultStatus' ListAllFlowResultsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/FlowResult' totalCount: type: integer format: int64 minimum: 0 ListAllUsersResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Identity' totalCount: type: integer format: int64 minimum: 0 ListAuditLogResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/AuditLogEntry' totalCount: type: integer format: int64 minimum: 0 ListOrganizationApiKeysResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/ZypheApiKey' totalCount: type: integer format: int64 minimum: 0 ListOrganizationFlowResultHistoryResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/VerificationRequest' totalCount: type: integer format: int64 minimum: 0 ListOrganizationFlowResultsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/FlowResult' totalCount: type: integer format: int64 minimum: 0 ListOrganizationFlowsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Flow' totalCount: type: integer format: int64 minimum: 0 ListOrganizationFormsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Form' totalCount: type: integer format: int64 minimum: 0 ListOrganizationInvitesResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/OrganizationInvite' totalCount: type: integer format: int64 minimum: 0 ListOrganizationUsersResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Identity' totalCount: type: integer format: int64 minimum: 0 ListOrganizationVerificationRequestsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/VerificationRequest' totalCount: type: integer format: int64 minimum: 0 ListOrganizationsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Organization' totalCount: type: integer format: int64 minimum: 0 ListSharedKycResultsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/FlowResult' totalCount: type: integer format: int64 minimum: 0 ListThemesResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/Theme' totalCount: type: integer format: int64 minimum: 0 ListUserInvitesResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/OrganizationInvite' totalCount: type: integer format: int64 minimum: 0 LivenessConfig: type: object required: - documentStepId properties: biometricCheckEnabled: type: boolean description: >- When `true` the liveness step also performs a biometric match against the stored portrait. Set to `false` to keep the liveness UX but skip biometric verification. nullable: true documentStepId: type: string format: uuid labels: type: object additionalProperties: type: string example: '{ "en_button_label": "Next step" }' maxAttempts: type: integer format: int32 example: '5' nullable: true minimum: 0 passiveLiveness: type: boolean description: >- When `true`, passive liveness (selfie-only, no head movements) is used instead of active challenge-based liveness. Configured by admin only. Defaults to `false`. performAntispoof: type: boolean nullable: true skipIfPreviousLivenessPassed: type: boolean description: >- When enabled (the default when unset), the liveness step is skipped during a one-click KYC reuse if the reused document verification result already carries a successful liveness outcome (`processAdditionalData.rawLivenessData`). The reused liveness must originate from a flow of the same organization, unless the one-click was authenticated via passkey — in which case cross-organization reuse is allowed. Set to `false` to always require a fresh liveness. nullable: true thresholds: type: object additionalProperties: type: number format: float nullable: true 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 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 ModerateKybResultPayload: type: object properties: pepAndSanctionsStatus: allOf: - $ref: '#/components/schemas/PepAndSanctionsStatusField' nullable: true reportFile: type: string format: binary nullable: true status: allOf: - $ref: '#/components/schemas/ModerationResultStatusField' nullable: true ModerateKybResultResponse: type: object required: - success properties: success: type: boolean ModerationResultStatus: type: string enum: - ACQUIRING - 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 Organization: type: object required: - id - slug - name - registrationNumber - country - address - website - email - phone - creationSource properties: address: type: string country: type: string createdAt: type: string format: date-time nullable: true creationSource: $ref: '#/components/schemas/CreationSource' email: type: string id: type: string format: uuid industry: type: string nullable: true name: type: string phone: type: string postcode: type: string nullable: true registrationNumber: type: string settings: allOf: - $ref: '#/components/schemas/Settings' nullable: true slug: type: string updatedAt: type: string format: date-time nullable: true website: type: string OrganizationInvite: type: object required: - id - email - organizationId - used - validBefore - role properties: createdAt: type: string format: date-time nullable: true email: type: string id: type: string format: uuid inviter: allOf: - $ref: '#/components/schemas/OrganizationInviterInfo' nullable: true organizationId: type: string format: uuid revoked: type: boolean nullable: true revokedAt: type: string format: date-time nullable: true role: $ref: '#/components/schemas/Role' used: type: boolean validBefore: type: string format: date-time OrganizationInviterInfo: type: object required: - role properties: email: type: string nullable: true role: $ref: '#/components/schemas/Role' 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 OwnershipEdge: type: object required: - id - fromId - toId - percentage properties: fromId: type: string id: type: string percentage: type: number format: double source: type: string nullable: true 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 internally tagged enum: the `type` tag selects the variant, so a tag that disagrees with its 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 reference provider already emits `found`, `budget_truncated`, `placeholder`, and `coverage_unavailable`, and a fifth value must not fail a write. `status` is the load-bearing truncation signal: an unexplored node must render differently 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: allOf: - $ref: '#/components/schemas/OwnershipBirthDate' nullable: true name: $ref: '#/components/schemas/OwnershipIndividualName' nationality: type: string nullable: true OwnershipIndividualName: type: object required: - fullName properties: fullName: type: string OwnershipNode: allOf: - $ref: '#/components/schemas/OwnershipEntity' - type: object required: - nodeId - flags properties: flags: $ref: '#/components/schemas/OwnershipFlags' nodeId: type: string totalOwnershipPercentage: type: number format: double nullable: true description: >- A graph node. `entity` is flattened and tagged on `type`, so a `company`-typed node cannot 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 description: >- Why graph traversal stopped, when it stopped early (e.g. `max_depth_reached`). Free-form: provider-defined and admin-entered, so a closed enum would reject an unrecognised value at write time. nullable: true PagedCommunicationsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/KybCommunication' totalCount: type: integer format: int64 minimum: 0 PagedDocumentRequestsResponse: type: object required: - page - totalCount properties: page: type: array items: $ref: '#/components/schemas/KybDocumentRequest' totalCount: type: integer format: int64 minimum: 0 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 example: '{ "default": "Next step" }' PhoneResult: type: object required: - id - status - phoneNumberLast4 - flowResultId properties: createdAt: type: string format: date-time nullable: true documentId: type: string format: uuid nullable: true flowResultId: type: string format: uuid flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid phoneNumberE164: type: string nullable: true phoneNumberLast4: type: string status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true PhoneStepOutput: type: object required: - status properties: status: $ref: '#/components/schemas/ResultStatus' Plaintext: type: object required: - text properties: text: type: object additionalProperties: type: string visibleWhen: allOf: - $ref: '#/components/schemas/Condition' nullable: true PoaConfig: type: object required: - documentFilter properties: documentFilter: type: array items: $ref: '#/components/schemas/PoaDocumentType' labels: type: object additionalProperties: 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 format: date-time nullable: true createdAt: type: string format: date-time documentId: type: string format: uuid nullable: true documentType: allOf: - $ref: '#/components/schemas/PoaDocumentType' nullable: true flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid reason: allOf: - $ref: '#/components/schemas/PoaReason' nullable: true status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time verificationRequestId: type: string format: uuid nullable: true PoaStepOutput: type: object required: - status properties: documentAgeDays: type: integer format: int64 nullable: true documentType: type: string nullable: true status: $ref: '#/components/schemas/ResultStatus' ProcessAdditionalData: type: object description: >- Typed representation of process_additional_data stored in DV results. This struct captures all the additional data associated with document verification processing, including document scan status, image quality checks, security checks, and liveness data. # Deserialization Supports both new abstract format and legacy Regula format. The main difference is in the `imageQuality` field: **New format:** ```json { "imageQuality": [ { "checkType": "focus", "result": "passed", "probability": 97 } ] } ``` **Legacy Regula format:** ```json { "imageQuality": [ { "count": 6, "list": [ { "type": 1, "result": 0, "probability": 97, ... } ], "result": 0 } ] } ``` properties: autoOneClickKycData: allOf: - $ref: '#/components/schemas/AutoOneClickKycData' nullable: true biometricCheckData: description: Biometric check data (for face matching results) nullable: true documentExpiredWebhookSentAt: type: string format: date description: >- Date on which a DocumentExpired webhook was last sent for this DV result. Used by the AML worker to deduplicate repeated expiry notifications across refresh ticks — once set, the webhook is not re-enqueued. nullable: true imageQuality: type: array items: $ref: '#/components/schemas/ImageQualityCheckResult' description: Image quality check results nullable: true rawLivenessData: description: Raw liveness data from face verification nullable: true securityChecks: type: object description: Security check results (mapped by check type) additionalProperties: type: string nullable: true status: allOf: - $ref: '#/components/schemas/DocumentScanStatus' nullable: true 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. `0` = first submission (`Created`); `> 0` = retry (`Updated`). jobId: type: string verificationRequestId: type: string format: uuid ProcessDocumentSelectionPayload: type: object properties: country: type: string description: >- ISO 3166-1 alpha-2 country code of the document to be verified (e.g. `"US"`, `"GB"`). Optional — omit to allow any country. nullable: true documentType: type: integer format: int64 description: >- Numeric document type identifier. Optional — omit to allow any document type. nullable: true 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 nullable: true countryCode: type: string forceDocumentType: type: integer format: int64 nullable: true images: type: array items: $ref: '#/components/schemas/InputImage' description: >- Images to process (base64-encoded, provider-agnostic format). Either images OR (session_token + interview_id) must be provided, not both. interviewId: type: string description: >- Interview/session ID for session-based providers (e.g. Incode). If provided along with session_token, the backend will fetch results from the provider. nullable: true platform: type: string nullable: true provinceCode: type: string nullable: true sessionToken: type: string description: >- Session token for session-based providers (e.g. Incode JWT). If provided along with interview_id, the backend will fetch results from the provider. nullable: true 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 additionalProperties: {} nullable: true checkAuth: type: boolean nullable: true scenario: type: string nullable: true 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 RequestOnDemandDocumentPayload: type: object description: >- Request body for `POST .../kyb/{kyb_result_id}/document-requests/on-demand`. Asks the client for a specific on-demand per-country document (identified by its catalog `key`). The server validates the key resolves to an on-demand document for the KYB's country, creates a `Standard` document request from it, and notifies the client. required: - documentKey properties: body: type: string description: >- Optional email body; defaults to a generated body referencing the document. nullable: true description: type: string description: >- Optional description shown to the client; defaults to a generated message. nullable: true documentKey: type: string description: >- Catalog `key` of the on-demand document to request (must be on-demand for this country). recipientEmail: type: string description: Optional recipient override; defaults to the business contact email. nullable: true subject: type: string description: >- Optional email subject; defaults to a generated subject referencing the document. nullable: true 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 nullable: true - type: object required: - reject properties: reject: type: object properties: reason: type: string nullable: true - type: object required: - escalate properties: escalate: type: object properties: reason: type: string nullable: true 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: Snapshot of the FORM factor keys matched for a form step (JSONB column). 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 format: uuid nullable: true 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 required: - kind properties: kind: type: string enum: - legacy description: >- Provenance for an `AssignedRiskTag` derivation. Determines whether a machine-driven recompute 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 SdkAmlScreenQuery: type: object description: >- Every meaningful OpenSanctions/Yente search field as an optional string. Result-only fields (sanctions, topics, position occupancies) are not exposed as inputs. properties: address: type: string nullable: true alias: type: string nullable: true birthCountry: type: string nullable: true birthDate: type: string nullable: true birthPlace: type: string nullable: true country: type: string nullable: true email: type: string nullable: true firstName: type: string nullable: true gender: type: string nullable: true lastName: type: string nullable: true middleName: type: string nullable: true name: type: string nullable: true nationality: type: string nullable: true passportNumber: type: string nullable: true phone: type: string nullable: true position: type: string nullable: true registrationNumber: type: string nullable: true title: type: string nullable: true 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 marker, currently always `"ftm/1"` (FollowTheMoney). provider: type: string description: >- The screening provider that produced these results (e.g. `"yente"`, `"worldcheck"`). Field richness is provider-dependent — see the SDK docs for coverage differences. SdkCreateVerificationRequestPayload: allOf: - $ref: '#/components/schemas/VerificationIdentifier' - type: object properties: customData: type: object description: >- Arbitrary key-value metadata to attach to this verification request. additionalProperties: {} nullable: true description: >- SDK payload for creating or resuming a verification request on behalf of a user. At least one of `email` or `wallet` must be provided (enforced by [`VerificationIdentifier`] validation). Both may be provided simultaneously: wallet takes priority for `zid`, email is stored as a contact address. SdkCreateVerificationRequestResponse: type: object required: - verificationRequest - zypheAccessSig - zypheToken - zid - isSandbox - flowSlug - flowStepSlug properties: email: type: string description: >- The email address associated with the verified user's identity, if available. nullable: true 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. verificationRequest: $ref: '#/components/schemas/VerificationRequest' 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. 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 - black_and_white_copy - document_alteration - document_tampering - fake_document - paper_copy - unknown SelectOptions: type: object required: - values - isOtherAllowed properties: isOtherAllowed: type: boolean values: type: array items: type: string Settings: type: object properties: askPasskeyCreation: type: boolean description: >- When true (default), prompt users to create a passkey during the verification flow. When false, skip the passkey creation step. Optional so that patch requests only write this field when explicitly provided. nullable: true createdAt: type: string format: date-time nullable: true delayFlowResults: type: boolean nullable: true emailNotifications: type: array items: type: string nullable: true extendedWebhook: type: boolean nullable: true oneClickAlwaysRequestUnlockVault: type: boolean description: >- When true (default), always require vault unlock for one-click KYC even if a grant already exists. When false, skip vault unlock if an active KYC grant already exists for the organization. Optional so that patch requests only write this field when explicitly provided. nullable: true published: type: boolean skipSignedAccess: type: boolean slackNotifications: type: array items: type: string nullable: true telegramNotifications: type: array items: type: string nullable: true updatedAt: type: string format: date-time nullable: true webhookSecret: type: string nullable: true webhookWithLegacy: type: boolean nullable: true SiwxChain: type: string enum: - ETHEREUM - ETHEREUM_TESTNET - SOLANA - SOLANA_TESTNET SpidConfig: type: object properties: documentSelectionStepId: type: string format: uuid description: >- The ID of the `DocumentSelection` step that precedes this SPID step. Mirrors the same field on [`DvConfig`] — makes the step link explicit and independent of step ordering. labels: type: object additionalProperties: type: string example: '{ "default": "Next step" }' SpidDocumentType: type: string enum: - ITALIAN_SPID - AADHAAR SpidResult: type: object required: - id - status - path properties: createdAt: type: string format: date-time nullable: true flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid path: type: string reason: type: string nullable: true status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true SpidResultDetails: type: object properties: address: type: string nullable: true companyName: type: string nullable: true companyVatNumber: type: string nullable: true countryOfBirth: type: string nullable: true dateOfBirth: type: string nullable: true digitalAddress: type: string nullable: true email: type: string nullable: true firstName: type: string nullable: true fiscalNumber: type: string nullable: true fullName: type: string nullable: true gender: type: string nullable: true id: type: string nullable: true lastName: type: string nullable: true mobilePhone: type: string nullable: true placeOfBirth: type: string nullable: true registeredOffice: type: string nullable: true spidCode: type: string nullable: true username: type: string nullable: true 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 Theme: type: object description: >- Flat theme API response. Logo/font fields hold raw S3 keys when built from `ThemeData`; the handler swaps them for presigned URLs before returning. required: - id - name - isDefault properties: borderRadius: type: string nullable: true createdAt: type: string format: date-time nullable: true dark: allOf: - $ref: '#/components/schemas/ThemeColorSetResponse' nullable: true fontFamily: type: string nullable: true fontLicense: allOf: - $ref: '#/components/schemas/ThemeFontLicense' nullable: true fontUrl: type: string description: >- Presigned read URL for the uploaded font (or the raw S3 key before presigning). nullable: true id: type: string format: uuid isDefault: type: boolean light: allOf: - $ref: '#/components/schemas/ThemeColorSetResponse' nullable: true name: type: string updatedAt: type: string format: date-time nullable: true ThemeColorSetResponse: type: object description: >- Per-mode color set as returned by the API (logo resolved to a presigned URL). properties: accent: type: string nullable: true background: type: string nullable: true card: type: string nullable: true logoUrl: type: string description: >- Presigned read URL for this mode's logo (or the raw S3 key before the handler presigns it). nullable: true 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 format: date-time nullable: true attestedByIdentityId: type: string format: uuid nullable: true TopupPack: type: object description: >- A top-up pack: a one-time Stripe Price tagged with `zyphe_type=credit_topup` metadata. Produced by [`list_topup_prices`] from Stripe one-time prices whose product is active and whose metadata carries `zyphe_type=credit_topup`. `credits` and `validity_months` are parsed from price metadata (`credits`, `validity_months`). [`list_topup_prices`]: https://docs.stripe.com/api/prices/list 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' name: type: string description: 'Display name: nickname > product name > price ID' priceId: type: string description: The Stripe price ID (e.g., "price_xxx") validityMonths: type: integer format: int32 description: >- Optional validity window (in months) for the granted credits, from metadata `validity_months` nullable: true 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' TriggerReminderResponse: type: object required: - enqueued properties: enqueued: type: boolean UboDefinition: type: object required: - firstName - lastName - dateOfBirth - country - gender properties: country: type: string dateOfBirth: type: string emailAddress: type: string description: >- Email of the UBO. `None` for a name-only UBO added without an email: such a UBO is AML-screened by name and is never sent a KYC invitation. nullable: true firstName: type: string gender: type: string id: type: string format: uuid description: >- Stable identifier for this UBO within the KYB result. Assigned on creation (submission or post-submission add) and used to address the UBO for removal / name-screening instead of a positional index. `None` only for legacy entries created before this field existed. nullable: true lastName: type: string Uuid: type: string format: uuid description: A UUID string 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_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. Frontends should pass `options.publicKey` directly to `navigator.credentials.get({ publicKey })`. prfSalt: type: string description: PRF salt for vault unlock (base64url) VerificationIdentifier: type: object description: >- Identity fields shared by all verification-request creation payloads. At least one of `email` or a [`VerificationIdentifierCredential::Wallet`] inside `credentials` must be provided — a wallet is the only credential that can form a `zid` without an email address. Flatten this into your payload struct with `#[serde(flatten)]` to keep the fields at the top level of the JSON object — backward-compatible with callers that only send `email`. `MagicLink` is provisioned automatically by [`VerificationIdentifier::resolve`] for any email-bearing identity 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). The first `Wallet` entry determines the `zid`; all entries are provisioned on identity creation. email: type: string description: >- Email address of the user. Used for notifications and as the `zid` when no wallet credential is provided. nullable: true VerificationIdentifierCredential: oneOf: - type: object description: >- Wallet credential. The `zid` is derived as `"CHAIN:address"` when this is the first (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. The `organization_id` is always populated server-side and must never be accepted from untrusted client input. required: - externalId - type properties: externalId: type: string type: type: string enum: - EXTERNAL_ID description: >- A credential that can be provisioned via a verification-request creation payload. Tagged with the same `type` discriminant strings as [`CredentialType`] so that `"WALLET"` / `"EXTERNAL_ID"` are consistent across the whole API surface. Only the variants that carry public-API meaning are included here; internal credentials such as `PASSWORD`, `PASSKEY`, `BOT_TOKEN`, and `MAGIC_LINK` are not exposed — `MAGIC_LINK` is always provisioned automatically by [`VerificationIdentifier::resolve`] for any email-bearing identity. discriminator: propertyName: type VerificationRequest: type: object required: - id - identityId - flowId - flowStepId - organizationId - customData - status - attemptsCount properties: amlResult: allOf: - $ref: '#/components/schemas/AmlResult' nullable: true attemptsCount: type: integer format: int32 createdAt: type: string format: date-time nullable: true customData: type: object additionalProperties: {} dvResult: allOf: - $ref: '#/components/schemas/DvResult' nullable: true flowId: type: string format: uuid flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid formResult: allOf: - $ref: '#/components/schemas/FormResult' nullable: true geolocationResult: allOf: - $ref: '#/components/schemas/GeolocationResult' nullable: true id: type: string format: uuid identity: allOf: - $ref: '#/components/schemas/Identity' nullable: true identityId: type: string format: uuid kybResult: allOf: - $ref: '#/components/schemas/KybResult' nullable: true organizationId: type: string format: uuid phoneResult: allOf: - $ref: '#/components/schemas/PhoneResult' nullable: true poaResult: allOf: - $ref: '#/components/schemas/PoaResult' nullable: true reason: type: string nullable: true replayerZid: type: string nullable: true spidResult: allOf: - $ref: '#/components/schemas/SpidResult' nullable: true status: $ref: '#/components/schemas/VerificationRequestStatus' updatedAt: type: string format: date-time nullable: true walletResult: allOf: - $ref: '#/components/schemas/WalletResult' nullable: true 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: allOf: - $ref: '#/components/schemas/CloudflareTracePayload' nullable: true 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 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 format: date-time nullable: true flowResultId: type: string format: uuid flowStep: allOf: - $ref: '#/components/schemas/FlowStep' nullable: true flowStepId: type: string format: uuid nullable: true id: type: string format: uuid message: type: string reason: type: string nullable: true signature: type: string status: $ref: '#/components/schemas/ResultStatus' updatedAt: type: string format: date-time nullable: true verificationRequestId: type: string format: uuid nullable: true walletAddress: type: string walletChain: type: string WalletStepOutput: type: object required: - status properties: status: $ref: '#/components/schemas/ResultStatus' WorkerScenario: oneOf: - type: string description: User-initiated verification request via SDK/API. enum: - USER_INITIATED - type: object required: - TRIGGERED_BY_WORKER properties: TRIGGERED_BY_WORKER: $ref: '#/components/schemas/WorkerType' - 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: |- The scenario/context that triggered a worker. This helps distinguish between different flows that can trigger the same worker type (e.g. AML worker triggered by DV vs scheduled refresh). WorkerType: type: string description: >- Types of background workers that can emit audit events. This enum is used in audit event sources and in job records to track which worker triggered an action (e.g., AML triggered by DV). `Display` (via `JsonDisplay`) renders the SCREAMING_SNAKE_CASE serde name (e.g. `DV`, `ONE_CLICK_FORM`) — the same value shown in `source.workerType`. enum: - DV - LIVENESS - AML - POA - SPID - FORM - ONE_CLICK_DV - ONE_CLICK_FORM - MANUAL_REVIEW WorkflowContext: type: object description: >- Context data available to JDM rules during flow evaluation. This structure is serialized to JSON and passed to the Zen Engine for evaluation. JDM rules can access any field to make routing decisions. # Example JDM Access Patterns In JDM rules, you can access: - `identity.email` - User's email address - `jdmData.my_step_slug.data.issuingCountry` - Output from a previous step - `customData.someKey` - Custom data passed during flow # Serialization Fields 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: {} 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: allOf: - $ref: '#/components/schemas/Identity' nullable: true jdmData: type: object description: Structured data from previous step executions for JDM consumption additionalProperties: $ref: '#/components/schemas/FlowStepOutput' 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. Edges represent the flow of control between nodes. For conditional branching (from Operator nodes), edges can have labels like "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 description: |- Optional label for conditional edges. For edges from Branch operator nodes: - "true": taken when condition evaluates to true - "false": taken when condition evaluates to false nullable: true 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 description: |- Slug of the next step to execute. If None, the flow continues with linear order or completes. nullable: true description: >- Result of a workflow evaluation. The Zen Engine returns this structure after evaluating a JDM against a context. The `next_step_slug` field determines which flow step to execute next. WorkflowGraph: type: object description: |- A workflow graph consisting of nodes and edges. The graph defines the structure of a workflow: - One Start node where execution begins - One or more End nodes where execution terminates - Step nodes representing actual workflow steps - Operator nodes for conditional branching - 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: allOf: - $ref: '#/components/schemas/WorkflowNodeMetadata' nullable: true 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: allOf: - $ref: '#/components/schemas/WorkflowNodeMetadata' nullable: true 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: allOf: - $ref: '#/components/schemas/WorkflowNodeMetadata' nullable: true 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 items: $ref: '#/components/schemas/BranchCondition' description: The branches to evaluate (required for Switch operator). nullable: true condition: allOf: - $ref: '#/components/schemas/Condition' nullable: true id: type: string format: uuid description: Unique identifier for this node. metadata: allOf: - $ref: '#/components/schemas/WorkflowNodeMetadata' nullable: true operator: $ref: '#/components/schemas/LogicalOperator' type: type: string enum: - OPERATOR - type: object description: An action node for database operations. required: - id - config - type properties: config: $ref: '#/components/schemas/ActionConfig' id: type: string format: uuid description: Unique identifier for this node. metadata: allOf: - $ref: '#/components/schemas/WorkflowNodeMetadata' nullable: true type: type: string enum: - ACTION description: |- A node in the workflow graph. Nodes represent different types of elements in a workflow: - `Start`: The entry point of the workflow - `End`: A terminal point where the workflow completes - `Step`: A workflow step that executes some action - `Operator`: A conditional branching point discriminator: propertyName: type WorkflowNodeMetadata: type: object description: >- Metadata for a workflow node. Contains UI-specific information like position that doesn't affect execution logic. properties: position: allOf: - $ref: '#/components/schemas/NodePosition' nullable: true 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 - key - keyType - allowedOrigins - options properties: allowedOrigins: type: array items: type: string createdAt: type: string format: date-time nullable: true description: type: string nullable: true id: type: string format: uuid key: type: string keyType: $ref: '#/components/schemas/ApiKeyType' name: type: string nullable: true options: type: object additionalProperties: {} organization: allOf: - $ref: '#/components/schemas/Organization' nullable: true organizationId: type: string format: uuid updatedAt: type: string format: date-time nullable: true 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: API Keys