> ## 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.

# Search accounts

> Searches accounts with filters.

## Overview

This endpoint searches your accounts using various filters with cursor-based pagination.
You can filter by IBAN, client account ID, account holder name, or account status.

#### Cursor-Based Pagination

This endpoint uses cursor-based pagination for large datasets.
Start with an initial request, then use nextPageToken to fetch the next page and previousPageToken to go back. Use the limit parameter to control results per page (1–100, default 20).


## OpenAPI

````yaml get /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:
    get:
      tags:
        - Account Management
      summary: Search accounts with cursor-based pagination
      description: >-
        Searches accounts with filters using cursor-based pagination for
        efficient large dataset traversal
      operationId: getAccounts
      parameters:
        - name: iban
          in: query
          explode: false
          schema:
            type: string
            description: IBAN to search for (exact match)
            nullable: true
            example: LT121000011111111111
        - name: clientAccountId
          in: query
          explode: false
          schema:
            type: string
            description: Client account ID to search for (exact match)
            nullable: true
            example: 123e4567-e89b-12d3-a456-426614174000
        - name: accountHolderName
          in: query
          explode: false
          schema:
            type: string
            description: >-
              Account holder name to search for (partial match, case
              insensitive)
            nullable: true
            example: John Doe
        - name: status
          in: query
          explode: false
          schema:
            type: string
            description: Account status to filter by
            nullable: true
            example: OPEN
            enum:
              - OPEN
              - CLOSED
        - name: previousPageToken
          in: query
          explode: false
          schema:
            type: string
            description: >-
              Token representing current page position (internal account ID).
              Use previousPageToken or nextPageToken from response for
              navigation.
            nullable: true
            example: '123'
        - name: nextPageToken
          in: query
          explode: false
          schema:
            type: string
            description: >-
              Token representing current page position (internal account ID).
              Use previousPageToken or nextPageToken from response for
              navigation.
            nullable: true
            example: '123'
        - name: limit
          in: query
          explode: false
          schema:
            maximum: 100
            minimum: 1
            type: integer
            description: Number of results per page (1-100)
            format: int32
            nullable: true
            example: 20
            default: 20
      responses:
        '200':
          description: Accounts found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorAccountsResponse'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiExceptionHandler.ErrorResponse'
components:
  schemas:
    CursorAccountsResponse:
      required:
        - accounts
        - meta
      type: object
      properties:
        meta:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PageMeta'
        accounts:
          type: array
          description: List of accounts
          items:
            $ref: '#/components/schemas/AccountResponse'
      description: Cursor-based paginated response containing accounts
    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
    PageMeta:
      type: object
      properties:
        previousPageToken:
          type: string
          description: Token for fetching previous page
          nullable: true
          example: '10'
        nextPageToken:
          type: string
          description: Token for fetching next page
          nullable: true
          example: '20'
      description: Pagination metadata
    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.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
    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
    AccountType:
      type: string
      description: Type of account
      example: PRIVATE
      enum:
        - PRIVATE
        - LEGAL
    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.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
    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

````