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

# Create account

> Creates a new account with holder information and generates an IBAN.

## Idempotent Endpoint

This endpoint supports idempotency to prevent duplicate account creation.

### How to Use

* Include an `Idempotency-Key` header with a unique value (UUID recommended)
* The API returns the existing account when you reuse the same key
* Retry requests safely without creating duplicates

## Overview

This endpoint creates a new account, either PRIVATE or LEGAL. It validates the provided information, generates an IBAN, and creates the account with an OPEN status. All accounts require the account holder’s name, country code, and bank details for IBAN generation, while legal accounts also require a legal entity ID. You can optionally provide a unique clientAccountId to link the account to your internal systems.


## OpenAPI

````yaml post /account-service/v2/accounts
openapi: 3.0.1
info:
  title: accounts-service
  version: '0.0'
servers:
  - url: https://api.pgw-sandbox.finventi.com
    description: Accounts sandbox environment
security: []
tags:
  - name: Account Management
    description: API for managing accounts with IBAN generation
paths:
  /account-service/v2/accounts:
    post:
      tags:
        - Account Management
      summary: Create a new account
      description: Creates a new account with holder information and generates IBAN
      operationId: createAccount
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            description: Unique string (often a UUID) used to safely retry requests
            example: 8e7aafb1-92f2-4681-a068-a4819c03c0b6
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
        required: true
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: Bad request - validation error or duplicate client account ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponse'
        '503':
          description: IBAN generation service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponse'
components:
  schemas:
    CreateAccountRequest:
      required:
        - accountHolderName
        - accountType
        - clientAccountId
      type: object
      properties:
        accountType:
          description: Type of account (PRIVATE or LEGAL)
          example: PRIVATE
          x-not-null-message: Account type is required
          allOf:
            - $ref: '#/components/schemas/AccountType'
        accountHolderName:
          minLength: 1
          type: string
          description: Name of the account holder or company name if legal
          example: Jane Doe
          x-size-message: Account holder name is required
        accountHolderNameAliases:
          type: array
          description: >-
            Optional alternative names or identifiers to improve matching (e.g.,
            acronyms, short forms like "IBM" for "International Business
            Machines")
          nullable: true
          example:
            - HGRP
          items:
            type: string
        clientAccountId:
          type: string
          description: Client's internal account ID (must be unique)
          example: '001'
        organisationIdentification:
          description: Organisation identification details (for LEGAL accounts)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OrganisationIdentificationRequest'
        iban:
          type: string
          description: Account IBAN
          nullable: true
        countryCode:
          pattern: ^[A-Z]{2}$
          type: string
          description: ISO alpha-2 country code
          nullable: true
          example: LT
          x-pattern-message: Must be a valid ISO alpha-2 code
        bankCode:
          type: string
          description: Bank code
          nullable: true
          example: '70440'
        accountCode:
          type: string
          description: Account code
          nullable: true
          example: '1869'
      description: Request to create a new account
    AccountResponse:
      required:
        - accountHolderName
        - accountType
        - clientAccountId
        - createdAt
        - iban
        - id
        - status
        - updatedAt
      type: object
      properties:
        id:
          type: integer
          description: Internal account identifier
          format: int64
          example: 1
        clientAccountId:
          type: string
          description: Client's internal account ID
          example: acc_001
        iban:
          type: string
          description: International Bank Account Number
          example: LT121000011111111111
        ibanMetadata:
          description: International Bank Account Generation Metadata
          allOf:
            - $ref: '#/components/schemas/IbanMetadataResponse'
        accountType:
          description: Type of account
          example: PRIVATE
          allOf:
            - $ref: '#/components/schemas/AccountType'
        accountHolderName:
          type: string
          description: Name of the account holder
          example: Jane Doe
        accountHolderNameAliases:
          type: array
          description: >-
            Optional alternative names or identifiers to improve matching (e.g.,
            acronyms, short forms like "IBM" for "International Business
            Machines")
          nullable: true
          example:
            - HGRP
          items:
            type: string
        status:
          description: Account status
          example: OPEN
          allOf:
            - $ref: '#/components/schemas/AccountStatus'
        organisationIdentification:
          description: Organisation identification details (for LEGAL accounts)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OrganisationIdentificationResponse'
        createdAt:
          type: string
          description: Account creation timestamp
          example: '2025-09-10T13:43:40.758Z'
        updatedAt:
          type: string
          description: Last update timestamp
          example: '2025-09-10T13:55:40.758Z'
      description: Account information response
    ApiExceptionHandler.ErrorResponse:
      required:
        - code
      type: object
      properties:
        code:
          type: string
          description: Code of error
        message:
          type: string
          description: Error message
          nullable: true
        data:
          description: 'Error data '
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponseData'
      description: Error response
    AccountType:
      type: string
      description: Type of account
      example: PRIVATE
      enum:
        - PRIVATE
        - LEGAL
    OrganisationIdentificationRequest:
      type: object
      properties:
        lei:
          type: string
          description: LEI of the organisation
          nullable: true
          example: 3423455234Y45D34
        bic:
          type: string
          description: Organisation BIC
          nullable: true
          example: DEUTDEFFXXX
        other:
          description: Other organisation identification details
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OtherOrgIdentificationRequest'
      description: Organisation identification details (for LEGAL accounts)
    IbanMetadataResponse:
      type: object
      properties:
        countryCode:
          type: string
          description: Country code
          nullable: true
          example: LT
        bankCode:
          type: string
          description: Bank code
          nullable: true
          example: '70440'
        accountCode:
          type: string
          description: Account code
          nullable: true
          example: '1869'
      description: International Bank Account Generation Metadata
    AccountStatus:
      type: string
      description: Account status
      example: OPEN
      enum:
        - OPEN
        - CLOSED
    OrganisationIdentificationResponse:
      type: object
      properties:
        lei:
          type: string
          description: LEI of the organisation
          nullable: true
          example: 3423455234Y45D34
        bic:
          type: string
          description: Organisation BIC
          nullable: true
          example: DEUTDEFFXXX
        other:
          description: Other organisation identification details
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OtherOrgIdentificationResponse'
      description: Organisation identification details (for LEGAL accounts)
    ApiExceptionHandler.ErrorResponseData:
      required:
        - errors
      type: object
      properties:
        message:
          type: string
          description: Generic message for occurred errors
          nullable: true
        errors:
          type: array
          description: All occurred errors
          items:
            $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponseViolation'
      description: Error wrapper containing all occurred errors
    OtherOrgIdentificationRequest:
      required:
        - identification
      type: object
      properties:
        identification:
          type: string
          description: Other organisation identification
          example: 123-AS-323
        schemeNameCode:
          description: Coded name of the identifier scheme
          nullable: true
          example: DUNS
          allOf:
            - $ref: '#/components/schemas/SchemeNameCode'
        schemeNameProprietary:
          type: string
          description: Proprietary scheme name
          nullable: true
          example: LocalRegistry
        issuer:
          type: string
          description: Issuing authority
          nullable: true
          example: ChamberOfCommerce
      description: Other organisation identification details
    OtherOrgIdentificationResponse:
      required:
        - identification
      type: object
      properties:
        identification:
          type: string
          description: Other organisation identification
          example: 123-AS-323
        schemeNameCode:
          type: string
          description: Coded name of the identifier scheme
          nullable: true
          enum:
            - BANK
            - CBID
            - CHID
            - CINC
            - COID
            - CUST
            - DUNS
            - EMPL
            - GS1G
            - SREN
            - SRET
            - TXID
            - BDID
            - BOID
        schemeNameProprietary:
          type: string
          description: Proprietary scheme name
          nullable: true
          example: LocalRegistry
        issuer:
          type: string
          description: Issuing authority
          nullable: true
          example: ChamberOfCommerce
      description: Other organisation identification details
    ApiExceptionHandler.ErrorResponseViolation:
      type: object
      properties:
        field_name:
          type: string
          description: Field name which failed
          nullable: true
        value:
          type: string
          description: Value which was invalid
          nullable: true
        code:
          type: string
          description: Error code
          nullable: true
        message:
          type: string
          description: Error message
          nullable: true
      description: Single error wrapper
    SchemeNameCode:
      type: string
      description: Coded name of the identifier scheme
      example: DUNS
      enum:
        - BANK
        - CBID
        - CHID
        - CINC
        - COID
        - CUST
        - DUNS
        - EMPL
        - GS1G
        - SREN
        - SRET
        - TXID
        - BDID
        - BOID

````