Lean Technologies Open Banking Accounts API

openapi: 3.1.0
info:
  title: Consents Account On File Account Controls (New) Account Controls (New) Open Banking Accounts API
  version: v0.2.3
servers:
- url: https://sandbox.leantech.me
  description: Sandbox
- url: https://api2.leantech.me
  description: Production
security:
- bearerAuth: []
tags:
- name: Open Banking Accounts
  x-displayName: Open Banking Accounts
paths:
  /open-banking/account-information/2022.11.01-final-errata2/accounts:
    servers: []
    get:
      operationId: GetAccountsV1
      summary: Get Open Banking Accounts
      description: 'Retrieves a list of bank accounts linked by a user via LinkSDK for the KSA Open Banking (SAMA) ecosystem.

        Each account object contains account identification, status, currency, account type, account identifiers

        (such as IBAN), and other account-level data.

        Requires ReadAccountsBasic or ReadAccountsDetail consent permission.

        '
      parameters:
      - $ref: '#/components/parameters/FapiInteractionId'
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/CustomerId'
      - $ref: '#/components/parameters/OBPageParm'
      - $ref: '#/components/parameters/OBSizeParam'
      responses:
        '200':
          description: Accounts Read
          headers:
            x-fapi-interaction-id:
              description: An RFC4122 UID used as a correlation id.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OBGetAccountsResponse'
              examples:
                GetAccountsSuccess:
                  summary: Successful accounts response
                  value:
                    Status: OK
                    Message: Data successfully retrieved
                    Timestamp: '2026-04-09T10:30:00.000Z'
                    RefreshedAt: '2026-04-09T10:25:00.000Z'
                    StatusDetail: null
                    Meta:
                      TotalPages: 1
                    Links:
                      Self: https://api.leantech.me/open-banking/account-information/2022.11.01-final-errata2/accounts?page=0&size=50
                      First: https://api.leantech.me/open-banking/account-information/2022.11.01-final-errata2/accounts?page=0&size=50
                      Prev: null
                      Next: null
                      Last: https://api.leantech.me/open-banking/account-information/2022.11.01-final-errata2/accounts?page=0&size=50
                    Data:
                      Account:
                      - EntityId: 550e8400-e29b-41d4-a716-446655440000
                        AccountId: 7c8a9f12-3456-4abc-b123-9876543210ab
                        AccountHolderName: Ahmed Abdullah Al-Rashidi
                        AccountHolderShortName: Ahmed
                        Status: Active
                        StatusUpdateDateTime: '2025-08-01T10:30:00.000Z'
                        Currency: SAR
                        AccountType: KSAOB.Retail
                        AccountSubType: CurrentAccount
                        Description: Personal current account
                        Nickname: Main Account
                        OpeningDate: '2023-01-15T00:00:00.000Z'
                        MaturityDate: null
                        AccountIdentifiers:
                        - IdentificationType: KSAOB.IBAN
                          Identification: SA4420000001234567891234
                          Name: Ahmed Abdullah Al-Rashidi
                        - IdentificationType: KSAOB.AccountNumber
                          Identification: '20000001234567891234'
                          Name: Ahmed Abdullah Al-Rashidi
                        Servicer:
                          IdentificationType: KSAOB.BICFI
                          Identification: RIBLSARI
                      - EntityId: 550e8400-e29b-41d4-a716-446655440000
                        AccountId: 9d2e4f56-7890-4bcd-e345-fedcba987654
                        AccountHolderName: Ahmed Abdullah Al-Rashidi
                        AccountHolderShortName: Ahmed
                        Status: Active
                        StatusUpdateDateTime: '2025-07-15T14:20:00.000Z'
                        Currency: SAR
                        AccountType: KSAOB.Retail
                        AccountSubType: Savings
                        Description: Personal savings account
                        Nickname: Savings Account
                        OpeningDate: '2023-03-20T00:00:00.000Z'
                        MaturityDate: null
                        AccountIdentifiers:
                        - IdentificationType: KSAOB.IBAN
                          Identification: SA8830000009876543210987
                          Name: Ahmed Abdullah Al-Rashidi
                        Servicer:
                          IdentificationType: KSAOB.BICFI
                          Identification: RIBLSARI
                BankIssueExample:
                  summary: Failed request due to bank technical issues
                  value:
                    Status: FAILED
                    Message: Your bank is currently experiencing technological problems. Please try again later.
                    Timestamp: '2026-04-09T10:30:00.000Z'
                    RefreshedAt: null
                    StatusDetail:
                      GranularStatusCode: BANK_ISSUE
                      StatusAdditionalInfo: Your bank is currently experiencing technological problems. Please try again later.
                    Meta: null
                    Links: null
                    Data: null
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                MissingEntityId:
                  summary: Missing or invalid entity_id
                  value:
                    Status: FAILED
                    Message: entity_id is required and must be a valid UUID
                    Timestamp: '2026-04-09T10:30:00.000Z'
                    RefreshedAt: null
                    StatusDetail:
                      GranularStatusCode: INVALID_PARAMETERS
                      StatusAdditionalInfo: The provided entity_id is not a valid UUID format
                    Meta: null
                    Links: null
                    Data: null
        '404':
          description: Entity not found
          content:
            application/json:
              examples:
                EntityNotFound:
                  summary: Entity not found
                  value:
                    Status: FAILED
                    Message: Entity not found
                    Timestamp: '2026-04-09T10:30:00.000Z'
                    RefreshedAt: null
                    StatusDetail:
                      GranularStatusCode: ENTITY_NOT_FOUND
                      StatusAdditionalInfo: No entity found for the provided entity_id
                    Meta: null
                    Links: null
                    Data: null
        '500':
          description: Internal Server Error
          content:
            application/json:
              examples:
                BankIssue:
                  summary: Bank technical issue
                  value:
                    Status: FAILED
                    Message: Your bank is currently experiencing technological problems. Please try again later.
                    Timestamp: '2025-09-12T05:13:49.739987382Z'
                    RefreshedAt: null
                    StatusDetail:
                      GranularStatusCode: BANK_ISSUE
                      StatusAdditionalInfo: Your bank is currently experiencing technological problems. Please try again later.
                    Meta: null
                    Links: null
                    Data: null
      tags:
      - Open Banking Accounts
components:
  schemas:
    OBAccount:
      description: Unambiguous identification of the account to which credit and debit entries are made.
      type: object
      properties:
        EntityId:
          description: Lean entity identifier for the connected customer.
          type: string
          format: uuid
        AccountId:
          description: Lean account identifier, uniquely identifying this account within Lean.
          type: string
          format: uuid
        AccountHolderName:
          description: Name or names of the account owner(s) represented at the account level.
          type: string
        AccountHolderShortName:
          description: Short name or nickname of the account holder.
          type:
          - string
          - 'null'
        Status:
          $ref: '#/components/schemas/OBAccountStatus'
        StatusUpdateDateTime:
          description: Date and time at which the account status was last updated. ISO 8601 format, e.g. 2017-04-05T10:43:07+00:00.
          type:
          - string
          - 'null'
          format: date-time
        Currency:
          description: ISO 4217 currency code in which the account is held.
          type: string
          examples:
          - SAR
          pattern: ^[A-Z]{3,3}$
        AccountType:
          $ref: '#/components/schemas/OBAccountType'
        AccountSubType:
          description: Sub-type of the account (product family group).
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBAccountSubType'
        Description:
          description: Description of the account sub-type.
          type:
          - string
          - 'null'
          maxLength: 35
          minLength: 1
        Nickname:
          description: Nickname assigned by the account holder for easier identification.
          type:
          - string
          - 'null'
          maxLength: 70
          minLength: 1
        OpeningDate:
          description: Date on which the account started to be operational. ISO 8601 format.
          type:
          - string
          - 'null'
          format: date-time
        MaturityDate:
          description: Date on which the account matures (applicable for fixed term loans or savings). ISO 8601 format.
          type:
          - string
          - 'null'
          format: date-time
        AccountIdentifiers:
          description: List of account identifiers (e.g. IBAN, account number).
          type: array
          items:
            $ref: '#/components/schemas/OBAccountIdentifier'
        Servicer:
          description: Party that manages the account on behalf of the account owner.
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBAccountServicer'
      required:
      - EntityId
      - AccountId
      - AccountHolderName
      - Status
      - Currency
      - AccountType
      - AccountIdentifiers
    OBAccountType:
      description: Specifies the type of account (Retail or Corporate).
      type: string
      enum:
      - KSAOB.Retail
      - KSAOB.Corporate
    OBAccountStatus:
      description: 'Status of the account:

        * Active — account exists and is active

        * NotActive — inactive for 6 to 12 months

        * Dormant — inactive for 1 to 5 years

        * Unclaimed — inactive for more than 5 years

        * Deceased — account holder has passed away

        * Suspended — account suspended (e.g. for security reasons)

        * Closed — account is closed

        '
      type: string
      enum:
      - Active
      - NotActive
      - Dormant
      - Unclaimed
      - Deceased
      - Suspended
      - Closed
    OBAccountIdentifier:
      description: Details to identify an account using a specific identification scheme.
      type: object
      properties:
        IdentificationType:
          $ref: '#/components/schemas/OBAccountIdentificationType'
        Identification:
          description: Account identification value under the given scheme (e.g. IBAN value, masked PAN, account number).
          type: string
          maxLength: 400
          minLength: 1
        Name:
          description: Name of the account owner(s) at the account identifier level.
          type:
          - string
          - 'null'
          maxLength: 350
          minLength: 1
      required:
      - IdentificationType
      - Identification
    OBServicerIdentificationType:
      description: Name of the identification scheme for the servicing institution.
      type: string
      enum:
      - KSAOB.BICFI
      - KSAOB.OTHER
    OBLinks:
      description: Links relevant to the resource for pagination navigation.
      type: object
      properties:
        Self:
          description: A link to the current resource.
          type: string
          format: uri
        First:
          description: A link to the first page in a paginated result set.
          type:
          - string
          - 'null'
          format: uri
        Prev:
          description: A link to the previous page in a paginated result set.
          type:
          - string
          - 'null'
          format: uri
        Next:
          description: A link to the next page in a paginated result set.
          type:
          - string
          - 'null'
          format: uri
        Last:
          description: A link to the last page in a paginated result set.
          type:
          - string
          - 'null'
          format: uri
      required:
      - Self
    OBAccountIdentificationType:
      description: Name of the identification scheme for the account.
      type: string
      enum:
      - KSAOB.IBAN
      - KSAOB.MaskedPAN
      - KSAOB.AccountNumber
      - KSAOB.CommercialRegistrationNumber
      - KSAOB.Email
      - KSAOB.MobileNumber
      - KSAOB.NationalID
      - KSAOB.IqamaNumber
      - KSAOB.PassportNumber
    OBAccountsData:
      description: Container for the list of Open Banking accounts.
      type: object
      properties:
        CustomerId:
          description: Lean provided customer ID
          type:
          - string
          - 'null'
          format: uuid
        Account:
          description: List of accounts associated with the entity.
          type: array
          items:
            $ref: '#/components/schemas/OBAccount'
      required:
      - Account
    OBAccountSubType:
      description: Specifies the sub-type of account (product family group).
      type: string
      enum:
      - CurrentAccount
      - Savings
      - CreditCard
      - PrePaidCard
      - EMoney
      - ChargeCard
      - Other
    OBStatusDetail:
      type:
      - object
      - 'null'
      properties:
        GranularStatusCode:
          description: Granular status code providing additional information on the request status.
          type:
          - string
          - 'null'
        StatusAdditionalInfo:
          description: Additional human-readable information about the status.
          type:
          - string
          - 'null'
    OBAccountServicer:
      description: Party that manages the account on behalf of the account owner, managing registration and booking of entries.
      type: object
      properties:
        IdentificationType:
          $ref: '#/components/schemas/OBServicerIdentificationType'
        Identification:
          description: Unique identification of the servicing institution.
          type: string
          maxLength: 35
          minLength: 1
      required:
      - IdentificationType
      - Identification
    OBMeta:
      description: Metadata relevant to the resource.
      type: object
      properties:
        TotalPages:
          description: Total number of pages where a result set is paginated.
          type:
          - integer
          - 'null'
          format: int32
          minimum: 0
    OBGetAccountsResponse:
      description: Response envelope for the Open Banking accounts list.
      type: object
      properties:
        Data:
          description: Container for the list of Open Banking accounts. Null when the request fails.
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBAccountsData'
        Status:
          description: Status of the request.
          type: string
          enum:
          - OK
          - PENDING
          - FAILED
          - CONSENT_EXPIRED
        Message:
          description: Human-readable message describing the status of the request.
          type: string
        Timestamp:
          description: Date and time when the response was generated.
          type: string
          format: date-time
        RefreshedAt:
          description: Date and time when the data was last refreshed from the bank.
          type:
          - string
          - 'null'
          format: date-time
        StatusDetail:
          description: Additional details about the request status.
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBStatusDetail'
        Meta:
          description: Metadata relevant to the resource, including pagination information.
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBMeta'
        Links:
          description: Links relevant to the resource for pagination navigation.
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/OBLinks'
      required:
      - Data
      - Status
      - Message
      - Timestamp
  parameters:
    EntityId:
      name: EntityId
      in: query
      description: The entity_id of the connected customer.
      required: false
      schema:
        type: string
        format: uuid
    OBPageParm:
      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
    FapiInteractionId:
      name: x-fapi-interaction-id
      in: header
      description: An RFC4122 UID used as a correlation id.
      required: false
      schema:
        type: string
    OBSizeParam:
      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
    CustomerId:
      name: CustomerId
      in: query
      description: The customer_id of the connected customer.
      required: false
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer