Lean Technologies Beneficiary Name Verification API

openapi: 3.1.0
info:
  title: Consents Account On File Account Controls (New) Account Controls (New) Beneficiary Name Verification API
  version: v0.2.3
  description: Beneficiary name retrieval operations
servers:
- url: https://sandbox.leantech.me
  description: Sandbox
- url: https://api2.leantech.me
  description: Production
security:
- bearerAuth: []
tags:
- name: Beneficiary Name Verification
  description: Beneficiary name retrieval operations
  x-displayName: Beneficiary Name Verification
paths:
  /verifications/v2/beneficiary-name:
    servers: []
    post:
      operationId: beneficiaryNameVerification
      summary: Get Beneficiary Name
      description: Retrieves the beneficiary name and account status for a given IBAN
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryNameRequest'
            example:
              iban: SA2810000011100000461309
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponseBeneficiaryNamePayload'
              examples:
                '1':
                  summary: Success - Active account
                  value:
                    status: OK
                    results_id: d2d95011-f834-4979-83eb-9c35b95f093c
                    message: Data successfully retrieved
                    timestamp: '2025-07-25T11:01:04.709087696Z'
                    meta: null
                    status_detail: null
                    verifications:
                      beneficiary_name: JON DOE
                      account_status: ACTIVE
                '2':
                  summary: Success - Blocked account
                  value:
                    status: OK
                    results_id: e894ede4-dd81-41fb-b52d-fb4fec16c16c
                    message: Data successfully retrieved
                    timestamp: '2025-05-19T12:09:54.672818827Z'
                    meta: null
                    status_detail: null
                    verifications:
                      beneficiary_name: JON DOE
                      account_status: BLOCKED
                '3':
                  summary: Failed - Unsupported by bank
                  value:
                    status: FAILED
                    results_id: f894ede4-dd81-41fb-b52d-fb4fec16c16c
                    message: Beneficiary Name Verification Failed
                    timestamp: '2024-04-30T07:54:25.224020260Z'
                    status_detail:
                      granular_status_code: UNSUPPORTED_BY_BANK
                      status_additional_info: This endpoint is currently not supported for this bank.
                '4':
                  summary: Failed - Bank issue
                  value:
                    status: FAILED
                    results_id: f894ede4-dd81-41fb-b52d-fb4fec16c16c
                    message: Beneficiary Name Verification Failed
                    timestamp: '2024-04-30T07:54:25.224020260Z'
                    status_detail:
                      granular_status_code: BANK_ISSUE
                      status_additional_info: Your bank is currently experiencing technological problems. Please try again later.
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              examples:
                InvalidIbanExample:
                  summary: Invalid IBAN format
                  value:
                    timestamp: '2025-07-25T11:01:04.709087696Z'
                    status: INVALID_PARAMETERS
                    message: The request provided invalid parameters.
                    metadata: null
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                ForbiddenExample:
                  summary: Operation not allowed
                  value:
                    timestamp: '2025-07-25T11:01:04.709087696Z'
                    status: OPERATION_NOT_ALLOWED
                    message: You are not allowed to do this operation
                    metadata: null
      tags:
      - Beneficiary Name Verification
components:
  schemas:
    ResultStatus:
      description: The status of the request
      type: string
      enum:
      - OK
      - PENDING
      - FAILED
      - CONSENT_EXPIRED
      - PROCESSING_STARTED
    Result:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ResultStatus'
        results_id:
          description: The unique identifier for the request
          type: string
          format: uuid
        message:
          description: A message describing the status of the request
          type: string
        meta:
          description: Meta information about the request
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
        timestamp:
          description: The datetime of when the request was made
          type: string
          format: date-time
        status_detail:
          description: Additional information about the status
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/StatusDetail'
      required:
      - status
      - results_id
      - message
      - timestamp
    StatusDetail:
      type:
      - object
      - 'null'
      properties:
        granular_status_code:
          description: Granular status code
          type:
          - string
          - 'null'
        status_additional_info:
          description: Additional information about the status
          type:
          - string
          - 'null'
    BeneficiaryNameRequest:
      type: object
      properties:
        iban:
          description: International Bank Account Number to retrieve beneficiary name for
          type: string
      required:
      - iban
    VerificationResponseBeneficiaryNamePayload:
      allOf:
      - $ref: '#/components/schemas/Result'
      - type: object
        properties:
          verifications:
            $ref: '#/components/schemas/BeneficiaryNamePayload'
    BeneficiaryNamePayload:
      description: Beneficiary name and account status retrieved from the bank
      type: object
      properties:
        beneficiary_name:
          description: Name of the account holder
          type: string
        account_status:
          description: Status of the bank account
          type: string
      required:
      - beneficiary_name
      - account_status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer