openapi: 3.2.0
info:
  title: Caliza API documentation reference KYC/KYB V1 API
  description: The Caliza API enables seamless integration of financial services including payments, payouts, currency conversions, and compliance workflows.
  version: v1
  contact:
    name: Caliza API Support
    email: api-support@caliza.com
    url: https://docs.caliza.com
  termsOfService: https://caliza.com/terms
servers:
- url: https://api.sandbox.com
  description: Sandbox Environment
- url: https://api.caliza.com
  description: Production Environment
- url: https://api.sandbox.caliza.com
  description: Sandbox Environment (backoffice)
security:
- bearerAuth: []
tags:
- name: KYC/KYB V1
  description: Manage KYC (Know Your Customer) and KYB (Know Your Business) verification for beneficiaries. Create interactive verification sessions that redirect users to a third-party provider and track verification status.
paths:
  /v1/beneficiaries/{beneficiaryId}/verification:
    post:
      tags:
      - KYC/KYB V1
      summary: Create verification
      description: Creates an interactive KYC or KYB verification session for a beneficiary. The system determines whether to run KYC (for individuals) or KYB (for businesses) based on the beneficiary type. Returns a verification URL where the end user must be redirected to complete the identity verification process with a third-party provider. If an active verification session already exists (status PENDING), the existing session is returned instead of creating a new one. After the user completes verification, the status updates asynchronously — poll the GET endpoint or subscribe to webhooks to track progress.
      operationId: createVerification
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary to verify.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
        required: false
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
    get:
      tags:
      - KYC/KYB V1
      summary: Get verification status
      description: Retrieves the current verification status for a beneficiary. Returns the verification session details including the current status, type (KYC or KYB), verification URL (if still pending), and timestamps. Use this endpoint to poll for verification progress after redirecting the user to the verification URL.
      operationId: getVerificationStatus
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '404':
          description: No verification found for this beneficiary.
  /v1/beneficiaries/{beneficiaryId}/verification/sandbox/approve:
    post:
      tags:
      - KYC/KYB V1
      summary: Approve verification (sandbox only)
      description: Manually approves a KYX workflow execution in sandbox environments without going through the third-party verification provider. After approval, the beneficiary status is updated to CREATED and all downstream flows (webhook notifications, etc.) are triggered as if the verification completed normally. This endpoint is only available in sandbox environments — calling it in production returns a 412 Precondition Failed error.
      operationId: approveVerificationSandbox
      parameters:
      - name: beneficiaryId
        in: path
        description: Unique identifier of the beneficiary to approve.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxApproveRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxApproveResponse'
        '404':
          description: Workflow execution not found for the given id, beneficiary, or status is not approvable (PENDING or PROCESSING).
        '412':
          description: Operation not allowed outside sandbox environment.
components:
  schemas:
    SandboxApproveResponse:
      type: object
      description: Response after manually approving a KYX verification in sandbox.
      properties:
        id:
          type: string
          description: Unique identifier of the approved workflow execution.
          example: 6925dd986a93002882da640b
        beneficiaryId:
          type: string
          description: Unique identifier of the beneficiary.
          example: 6925dd986a93002882da640b
        status:
          type: string
          description: The updated verification status.
          enum:
          - SUCCEEDED
          example: SUCCEEDED
    VerificationResponse:
      type: object
      description: KYC/KYB verification session details including status, type, and the verification URL for interactive sessions.
      properties:
        id:
          type: string
          description: Unique identifier of the verification session.
          example: 6925dd986a93002882da640b
        beneficiaryId:
          type: string
          description: Unique identifier of the beneficiary being verified.
          example: 6925dd986a93002882da640b
        type:
          type: string
          description: Beneficiary type. `INDIVIDUAL` triggers KYC workflows, `BUSINESS` triggers KYB workflows.
          enum:
          - INDIVIDUAL
          - BUSINESS
          example: INDIVIDUAL
        verificationType:
          type: string
          description: The verification mode used for this session.
          enum:
          - INTERACTIVE
          example: INTERACTIVE
        verificationUrl:
          type:
          - string
          - 'null'
          description: URL where the end user must be redirected to complete verification. Present when status is `PENDING`. Becomes `null` once verification is no longer pending.
          example: https://verification.aiprise.com/session/abc123
        status:
          type: string
          description: Current status of the verification session.
          enum:
          - PENDING
          - PROCESSING
          - SUCCEEDED
          - FAILED
          example: PENDING
        createdDate:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the verification session was created.
          example: '2025-01-15T16:47:20.568Z'
        lastModifiedDate:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp of the last status update.
          example: '2025-01-15T16:47:20.568Z'
    SandboxApproveRequest:
      type: object
      description: Request to manually approve a KYX verification in sandbox environments.
      required:
      - workflowId
      properties:
        workflowId:
          type: string
          description: The verification session id (returned as `id` when creating the verification session) to approve.
          example: 6925dd986a93002882da640b
    VerificationRequest:
      type: object
      description: Request to create a KYC/KYB verification session. The request body is optional — if omitted, the verification defaults to interactive mode.
      properties:
        verificationMode:
          type: string
          description: The verification mode. Use `INTERACTIVE` to redirect the user to a third-party verification provider.
          enum:
          - INTERACTIVE
          default: INTERACTIVE
          example: INTERACTIVE
  securitySchemes:
    bearerAuth:
      type: http
      description: 'JWT Bearer token authentication. Include your access token in the Authorization header:


        `Authorization: Bearer YOUR_ACCESS_TOKEN`


        Tokens are obtained through the Caliza authentication flow and typically expire after 24 hours.

        Refresh your token before expiration to maintain uninterrupted access.

        '
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: searched
  source: https://docs.caliza.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.caliza.com/reference/accepttermsandconditions.md
  - https://docs.caliza.com/reference/addrelatedpersondocument.md
  - https://docs.caliza.com/reference/approveverificationsandbox.md
  - https://docs.caliza.com/reference/createfakecryptodeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit.md
  - https://docs.caliza.com/reference/createfakepixindeposit_1.md
  - https://docs.caliza.com/reference/createfakespeiindeposit.md
  - https://docs.caliza.com/reference/createfakeusddeposit.md
  - https://docs.caliza.com/reference/createpayment.md
  - https://docs.caliza.com/reference/createpaymentwithdocuments.md
  - https://docs.caliza.com/reference/createrecipient.md
  - https://docs.caliza.com/reference/createrelatedperson.md
  - https://docs.caliza.com/reference/createsimulation.md
  - https://docs.caliza.com/reference/createsimulation_1.md
  - https://docs.caliza.com/reference/createtransaction.md
  - https://docs.caliza.com/reference/createtransaction_1.md
  - https://docs.caliza.com/reference/createverification.md
  - https://docs.caliza.com/reference/createvirtualaccount.md
  - https://docs.caliza.com/reference/deletebeneficiary.md
  - https://docs.caliza.com/reference/deleterecipient.md
  - https://docs.caliza.com/reference/deleterelatedperson.md
  - https://docs.caliza.com/reference/disablebeneficiary.md
  - https://docs.caliza.com/reference/enablebeneficiary.md
  - https://docs.caliza.com/reference/findorcreatewallet.md
  - https://docs.caliza.com/reference/getall.md
  - https://docs.caliza.com/reference/getalltransactions.md
  - https://docs.caliza.com/reference/getbeneficiary.md
  - https://docs.caliza.com/reference/getbeneficiarybalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalance.md
  - https://docs.caliza.com/reference/getbeneficiarydetailedbalancebycurrencies.md
  - https://docs.caliza.com/reference/getcapabilitiesbyintegratorid.md
  - https://docs.caliza.com/reference/getdepositinfo.md
  - https://docs.caliza.com/reference/getdepositinstructions.md
  - https://docs.caliza.com/reference/getintegratorbalances.md
  - https://docs.caliza.com/reference/getintegratorwebhooks.md
  - https://docs.caliza.com/reference/getintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/getme.md
  - https://docs.caliza.com/reference/getpaymentinstructions.md
  - https://docs.caliza.com/reference/getproof.md
  - https://docs.caliza.com/reference/getrecipient.md
  - https://docs.caliza.com/reference/getrecipients.md
  - https://docs.caliza.com/reference/getrelatedperson.md
  - https://docs.caliza.com/reference/getsimulationbyid.md
  - https://docs.caliza.com/reference/getsimulationbyidv2.md
  - https://docs.caliza.com/reference/gettermsandconditions.md
  - https://docs.caliza.com/reference/gettransactionbyid.md
  - https://docs.caliza.com/reference/gettransactionbyid_1.md
  - https://docs.caliza.com/reference/gettransactionbyidwithdocuments.md
  - https://docs.caliza.com/reference/gettransactionproofofpayment.md
  - https://docs.caliza.com/reference/getverificationstatus.md
  - https://docs.caliza.com/reference/issuedelegatetoken.md
  - https://docs.caliza.com/reference/issuemanualattestation.md
  - https://docs.caliza.com/reference/listrelatedpersons.md
  - https://docs.caliza.com/reference/listvirtualaccounts.md
  - https://docs.caliza.com/reference/payouts.md
  - https://docs.caliza.com/reference/savebeneficiary.md
  - https://docs.caliza.com/reference/searchvasps.md
  - https://docs.caliza.com/reference/simulatetravelruleclearance.md
  - https://docs.caliza.com/reference/startmicrotransfertest.md
  - https://docs.caliza.com/reference/submitproof.md
  - https://docs.caliza.com/reference/sweeppayouts.md
  - https://docs.caliza.com/reference/updatebeneficiary.md
  - https://docs.caliza.com/reference/updateintegratorwebhooksecret.md
  - https://docs.caliza.com/reference/updateme.md
  - https://docs.caliza.com/reference/updaterecipient.md
  - https://docs.caliza.com/reference/updaterelatedperson.md
  - https://docs.caliza.com/reference/updatewebhookconfig.md
  - https://docs.caliza.com/reference/uploaddocument.md
  merge:
    pages: 68
    deduped: 414
    conflicts_kept_first: 0