Lean Technologies Balance Raw Data API

openapi: 3.1.0
info:
  title: Consents Account On File Account Controls (New) Account Controls (New) Balance Raw Data API
  version: v0.2.3
servers:
- url: https://sandbox.leantech.me
  description: Sandbox
- url: https://api2.leantech.me
  description: Production
security:
- bearerAuth: []
tags:
- name: Balance Raw Data
  x-displayName: Balance Raw Data
paths:
  /data/v2/accounts/{account_id}/balances:
    servers: []
    get:
      operationId: fetchBalancesV2
      summary: Get Balances
      description: 'The `Get Balances` endpoint retrieves a list of balances associated with a specific bank account that has been linked by a user via LinkSDK, identified by both the `entity_id` and the `account_id`.

        The `account_id` can be found by making a call to the /accounts endpoint.

        Each balance object contains fields such as `balance type` (e.g., CLOSING_AVAILABLE, INTERIM_BOOKED, etc.), `amount`, `currency`, `credit/debit indicator`, and *optional* `credit_line` details that indicate available or agreed credit facilities tied to the account.Balance types can vary based on the bank and the nature of the account, and multiple types of balances may be available for the same account at the same time.

        **Requires an active entity with the `balances` permission to use.**

        '
      parameters:
      - $ref: '#/components/parameters/AccountIdParameter'
      - $ref: '#/components/parameters/AsyncParameter'
      - $ref: '#/components/parameters/PageParameter'
      - $ref: '#/components/parameters/SizeParameter'
      - $ref: '#/components/parameters/EntityIdParameter'
      - $ref: '#/components/parameters/MetaParameter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchBalancesV2Result'
              examples:
                GetBalances_V2_KSA_Example:
                  summary: Successful get balances - KSA
                  value:
                    status: OK
                    results_id: 1f6aa762-fdd0-4313-abc2-34ef31c0240e
                    message: Data successfully retrieved
                    meta: null
                    timestamp: '2025-08-06T17:43:16.041940122Z'
                    status_detail: null
                    data:
                      type: balances
                      balances:
                      - account_id: 36f0cf74-b4b0-492f-b50f-0a4680aba59f
                        credit_debit_indicator: CREDIT
                        amount:
                          currency: SAR
                          amount: 375.11
                        type: OPENING_AVAILABLE
                        date_time: '2025-08-06T14:40:42.149Z'
                        credit_line:
                        - included: false
                          amount:
                            currency: SAR
                            amount: 0
                          type: CREDIT
                      - account_id: 36f0cf74-b4b0-492f-b50f-0a4680aba59f
                        credit_debit_indicator: CREDIT
                        amount:
                          currency: SAR
                          amount: 675.11
                        type: EXPECTED
                        date_time: '2025-08-06T14:40:42.149Z'
                        credit_line: []
                      page:
                        number: 0
                        size: 50
                        total_elements: 2
                        total_pages: 1
                    type: balances
                    refreshed_at: '2025-08-06T17:40:42.210Z'
                BankIssueExample:
                  summary: Example response for bank issue
                  value:
                    status: FAILED
                    results_id: 516adc40-af36-4284-bfba-46ec69dfe6d3
                    message: Your bank is currently experiencing technological problems. Please try again later.
                    meta: null
                    timestamp: '2025-09-12T05:13:49.739987382Z'
                    status_detail:
                      granular_status_code: BANK_ISSUE
                      status_additional_info: Your bank is currently experiencing technological problems. Please try again later.
                    type: null
                    refreshed_at: null
        '202':
          description: Accepted (Asynchronous request)
          content:
            application/json:
              examples:
                GetAsyncExample:
                  $ref: '#/components/examples/AsyncProcessingV2Example'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                InvalidParametersExample:
                  $ref: '#/components/examples/InvalidParametersExample'
        '404':
          description: Account or entity not found
          content:
            application/json:
              examples:
                UnknownAccountExample:
                  $ref: '#/components/examples/UnknownAccountExample'
                UnknownEntityExample:
                  $ref: '#/components/examples/UnknownEntityExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
      tags:
      - Balance Raw Data
components:
  schemas:
    DataResult:
      type: object
      allOf:
      - $ref: '#/components/schemas/Result'
      - type: object
        properties:
          refreshed_at:
            description: The datetime of when the data was refreshed
            type:
            - string
            - 'null'
            format: date-time
          type:
            description: The endpoint the original request was made to.
            type:
            - string
            - 'null'
    Currency:
      description: The ISO 3 letter currency code
      type: string
      examples:
      - AED
      pattern: ^[A-Z]{3}$
    PageMetadata:
      description: Metadata about the current page of results
      type: object
      properties:
        number:
          description: The current page being returned by the API
          type: integer
          format: int32
        size:
          description: The page size requested
          type: integer
          format: int32
        total_elements:
          description: The total number of elements in all pages
          type: integer
          format: int64
        total_pages:
          description: The total number of pages retrievable
          type: integer
          format: int32
        sort:
          description: Sort parameters applied to the results
          type: array
          items:
            type: string
      required:
      - number
      - size
      - total_elements
      - total_pages
    FetchBalancesV2Result:
      type: object
      allOf:
      - $ref: '#/components/schemas/DataResult'
      - properties:
          data:
            $ref: '#/components/schemas/BalancesData'
        type: object
      x-toBuilder: true
    Balance:
      type: object
      properties:
        entity_id:
          description: The unique identifier for the entity. Provided as a UUID.
          type: string
          format: uuid
        account_id:
          description: The account_id this balance is related to.
          type: string
          format: uuid
        credit_debit_indicator:
          $ref: '#/components/schemas/CreditDebitIndicator'
        type:
          $ref: '#/components/schemas/BalanceType'
        amount:
          $ref: '#/components/schemas/CurrencyAmount'
        date_time:
          description: The date and time that this balance object was checked.
          type:
          - string
          - 'null'
          format: date-time
        credit_line:
          description: Represents the credit limits associated with the account. Each object defines a specific credit facility and its assigned limit
          type: array
          items:
            $ref: '#/components/schemas/CreditLine'
      required:
      - amount
    CurrencyAmount:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        amount:
          description: The amount of money in the currency specified.
          type: number
      required:
      - currency
      - amount
    BalanceType:
      description: 'The type of balance for the account. Note: Banks support different types for presenting account balance.'
      type: string
      enum:
      - CLOSING_AVAILABLE
      - CLOSING_BOOKED
      - CLOSING_CLEARED
      - EXPECTED
      - FORWARD_AVAILABLE
      - INFORMATION
      - INTERIM_AVAILABLE
      - INTERIM_BOOKED
      - INTERIM_CLEARED
      - OPENING_AVAILABLE
      - OPENING_BOOKED
      - OPENING_CLEARED
      - PREVIOUSLY_CLOSED_BOOKED
      - UNSUPPORTED
    BalancesData:
      type: object
      properties:
        type:
          description: The endpoint the original request was made to.
          type: string
        balances:
          description: An array of balances associated with the account.
          type: array
          items:
            $ref: '#/components/schemas/Balance'
        page:
          $ref: '#/components/schemas/PageMetadata'
      required:
      - type
      - page
      - balances
      x-toBuilder: true
    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
    CreditDebitIndicator:
      description: Indicates whether the balance is a credit or debit balance
      type: string
      enum:
      - CREDIT
      - DEBIT
      - UNSUPPORTED
    ResultStatus:
      description: The status of the request
      type: string
      enum:
      - OK
      - PENDING
      - FAILED
      - CONSENT_EXPIRED
      - RECONNECT_REQUIRED
      - PROCESSING_STARTED
    CreditLineType:
      description: The type of credit line
      type: string
      enum:
      - AVAILABLE
      - CREDIT
      - EMERGENCY
      - PRE_AGREED
      - TEMPORARY
      - UNSUPPORTED
    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'
    CreditLine:
      type: object
      properties:
        included:
          description: 'Indicates whether or not a credit line is included in the balance of the account. Usage: If false, credit line is not included in the balance amount of the account'
          type: boolean
          default: false
        amount:
          $ref: '#/components/schemas/CurrencyAmount'
        type:
          $ref: '#/components/schemas/CreditLineType'
  examples:
    InternalServerErrorExample:
      summary: Internal server error response
      description: Response when an unexpected server error occurs
      value:
        results_id: 516adc40-af36-4284-bfba-46ec69dfe6d3
        timestamp: '2025-08-07T13:07:38.834977945Z'
        status: INTERNAL_SERVER_ERROR
        message: Something has gone wrong. If you continue to see this error, please get in touch with Lean.
        metadata: null
    UnknownAccountExample:
      summary: Account not found error response
      description: Response when the provided account_id does not match an account for the entity_id
      value:
        results_id: 516adc40-af36-4284-bfba-46ec69dfe6d3
        timestamp: '2025-09-11T18:55:42.579432745Z'
        status: UNKNOWN_ACCOUNT
        message: The account_id provided does not match an account with the entity_id provided.
        metadata: null
    UnknownEntityExample:
      summary: Entity not found error response
      description: Response when the provided entity_id is not found
      value:
        results_id: 516adc40-af36-4284-bfba-46ec69dfe6d3
        timestamp: '2025-09-10T21:03:05.413806605Z'
        status: UNKNOWN_ENTITY
        message: The entity_id provided did not match an account in our records.
        metadata: null
    InvalidParametersExample:
      summary: Invalid parameters error response
      description: Response when required parameters are missing or invalid
      value:
        results_id: 516adc40-af36-4284-bfba-46ec69dfe6d3
        timestamp: '2025-09-10T21:05:59.919233187Z'
        status: INVALID_PARAMETERS
        message: 'The request is badly formatted or a parameter of the wrong type has been provided, field: entity_id, value: e34d8e49-9af2-4252-a53e-bd2df855134.'
        metadata: null
    AsyncProcessingV2Example:
      summary: Asynchronous processing response with async=true
      description: Response to request with async=true
      value:
        status: PENDING
        results_id: df73d596-7138-46df-af96-cbcbe9a8af59
        message: Please wait for a webhook or try again later.
        meta: null
        timestamp: '2025-09-11T19:15:07.829993148Z'
        status_detail: null
        data: null
        type: null
        refreshed_at: null
  parameters:
    MetaParameter:
      name: meta
      description: 'Additional data you would like to store against the request. Example: {"foo": "val"}'
      in: query
      required: false
      schema:
        type: string
    AccountIdParameter:
      name: account_id
      description: The account_id used to fetch requested data
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SizeParameter:
      name: size
      description: The number of objects you want to return as a page size.
      in: query
      required: false
      schema:
        type: integer
        default: 50
        maximum: 100
        minimum: 1
    EntityIdParameter:
      name: entity_id
      description: The entity_id you're querying for, which is created by LinkSDK `.connect()` function.
      in: query
      required: false
      schema:
        type: string
        format: uuid
    AsyncParameter:
      name: async
      in: query
      description: 'When true the API will return a results_id which can be fetched from the /data/v2/results endpoint when ready. **Note: it''s recommended to use the sync flow (async=false) for all requests by adapting the [data workflow](https://docs.leantech.me/docs/data-workflow) for connected entities.**'
      required: false
      schema:
        type: boolean
        default: false
      deprecated: true
    PageParameter:
      name: page
      in: query
      description: The page you're requesting - returns page 0 of a response if not specified.
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer