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

# Create bank account

> Create a bank account for the authenticated user.



## OpenAPI

````yaml POST /bank-accounts
openapi: 3.0.3
info:
  title: Wealthyhood Bank Accounts API
  version: 1.0.0
  description: |
    Endpoints to create and manage bank accounts for users.

    All requests require a bearer token and the `x-user-id` header.
servers:
  - url: https://{host}
    variables:
      host:
        default: api.wealthyhood.com
        description: Wealthyhood API host name.
security:
  - bearerAuth: []
tags:
  - name: Bank Accounts
    description: Create and manage user bank accounts.
paths:
  /bank-accounts:
    post:
      tags:
        - Bank Accounts
      summary: Create bank account
      description: Create a bank account for the authenticated user.
      parameters:
        - $ref: '#/components/parameters/ExternalUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreateRequest'
            examples:
              basic:
                value:
                  holderName: Jane Doe
                  iban: GR1601101250000000012300695
                  bic: ETHNGRAA
      responses:
        '201':
          description: Bank account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          description: Duplicate or conflicting bank account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                status: 409
                error:
                  message: Bank account already exists for this user
                  description: Conflict
                responseId: 7c91c5fe-d5a8-4b82-8e3f-5af2e30e43c2
components:
  parameters:
    ExternalUserId:
      name: x-user-id
      in: header
      description: The external user identifier of the acting customer.
      required: true
      schema:
        type: string
        example: bank-user-12345
  schemas:
    BankAccountCreateRequest:
      type: object
      required:
        - holderName
        - iban
        - bic
      properties:
        holderName:
          type: string
          description: Name of the account holder
          example: Jane Doe
        iban:
          type: string
          description: >-
            IBAN (International Bank Account Number). Must be a valid IBAN
            format.
          example: GR1601101250000000012300695
        bic:
          type: string
          description: BIC (Bank Identifier Code). Used to identify the bank.
          example: ETHNGRAA
    BankAccount:
      type: object
      required:
        - id
        - userId
        - holderName
        - iban
        - currency
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^[a-f0-9]{24}$
          description: Unique identifier of the bank account (MongoDB ObjectId)
          example: 64f0c51e7fb3fc001234abcd
        userId:
          type: string
          description: Identifier of the user who owns this bank account
          example: bank-user-12345
        holderName:
          type: string
          description: Name of the account holder
          example: Jane Doe
        iban:
          type: string
          description: IBAN (International Bank Account Number)
          example: GR1601101250000000012300695
        bic:
          type: string
          description: BIC (Bank Identifier Code)
          example: ETHNGRAA
        bankName:
          type: string
          description: Name of the bank, derived from BIC
          example: National Bank of Greece
        currency:
          type: string
          enum:
            - EUR
            - GBP
            - USD
          description: >-
            ISO 4217 currency code. Always EUR for bank accounts created through
            this API.
          example: EUR
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message
            description:
              type: string
              description: Additional error details
              nullable: true
        responseId:
          type: string
          format: uuid
          description: Unique identifier for this error response
      additionalProperties: false
  responses:
    BadRequestError:
      description: Bad request – invalid parameters or malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 400
            error:
              message: Invalid account number
              description: Operation failed
            responseId: 7c91c5fe-d5a8-4b82-8e3f-5af2e30e43c2
    UnauthorizedError:
      description: Unauthorized – missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 401
            error:
              message: User not found
            responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a
    ForbiddenError:
      description: Forbidden – valid credentials but insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 403
            error:
              message: Access denied
              description: Inaccessible resource
            responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````