> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a bank account

> Replaces the account’s editable details (holder name, corridor, routing) and re-runs Cleff-side validation, resetting validation_status. Malformed details are rejected (422) and the row is left unchanged. The identifier is re-encrypted at rest; the response is the masked projection.



## OpenAPI

````yaml PUT /v1/beneficiaries/{id}/bank-accounts/{accountId}
openapi: 3.0.0
info:
  title: Cleff API
  description: >-
    Payout orchestration platform. All endpoints under /v1/ require an API key
    in the Authorization header (Bearer ck_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/beneficiaries/{id}/bank-accounts/{accountId}:
    put:
      tags:
        - Beneficiaries
      summary: Edit a Beneficiary’s bank account
      description: >-
        Replaces the account’s editable details (holder name, corridor, routing)
        and re-runs Cleff-side validation, resetting validation_status.
        Malformed details are rejected (422) and the row is left unchanged. The
        identifier is re-encrypted at rest; the response is the masked
        projection.
      operationId: BeneficiariesController_updateBankAccount
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: accountId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterBankAccountDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterBankAccountResponseDto'
        '401':
          description: Missing or invalid credentials
        '404':
          description: Beneficiary or bank account not found
      security:
        - api_key: []
components:
  schemas:
    RegisterBankAccountDto:
      type: object
      properties:
        account_holder_name:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 of the bank country
        currency:
          type: string
          description: ISO 4217 currency code
        account_number:
          type: string
          description: Domestic account number (US/JP/etc.)
        routing_code:
          type: string
          description: US ABA, UK sort code, BR branch_code, etc.
        iban:
          type: string
          description: IBAN — required for European corridors
        swift_bic:
          type: string
          description: SWIFT/BIC — required for cross-border SWIFT routing
        clabe:
          type: string
          description: CLABE — Mexican domestic routing (18 digits)
        pix_key:
          type: string
          description: Pix key — Brazilian instant-payment identifier
        bank_name:
          type: string
        account_type:
          type: string
          enum:
            - checking
            - savings
          description: >-
            ACH account type (US). Defaults to checking at enrollment when
            unset.
      required:
        - account_holder_name
        - country
        - currency
    RegisterBankAccountResponseDto:
      type: object
      properties:
        bank_account:
          $ref: '#/components/schemas/BankAccountDto'
      required:
        - bank_account
    BankAccountDto:
      type: object
      properties:
        id:
          type: string
        account_holder_name:
          type: string
        currency:
          type: string
          description: ISO 4217 currency code
        country:
          type: string
          description: ISO 3166-1 alpha-2 of the bank country
        status:
          type: string
          enum:
            - verified
            - pending_verification
            - suspended
        validation_status:
          type: string
          enum:
            - unvalidated
            - validated
          description: >-
            Cleff-side format/modulus validation outcome. Distinct from
            ownership verification on `status`.
        payout_usable:
          type: boolean
          description: >-
            Derived: true only when the account is `validated`, `verified`, AND
            not rail-rejected. The single flag a Payout destination check should
            read.
        rail_rejection_reason:
          type: object
          nullable: true
          description: >-
            The payment rail rejected this specific bank at registration, with
            the captured reason — e.g. a routing number the sponsor bank won't
            accept. null when the rail never rejected it. Reflects only the rail
            outcome, never KYC/compliance.
        last4:
          type: string
          description: Last 4 of the account identifier; masked
        account_type:
          type: string
          enum:
            - checking
            - savings
          nullable: true
          description: >-
            ACH account type; null when not captured. Non-sensitive, no
            decryption.
      required:
        - id
        - account_holder_name
        - currency
        - country
        - status
        - validation_status
        - payout_usable
        - last4
        - account_type
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````