Lean Technologies Credit Obligations (New) API

openapi: 3.2.0
info:
  title: Lean Technologies Credit Obligations (New) API
  version: v2.0.0
  description: 'Operations tagged Credit Obligations (New) across 2 of this provider''s published API definitions: lean-technologies-insights-openapi.yml, lean-technologies-ksa-insights-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://sandbox.leantech.me
  description: Sandbox
- url: https://api2.leantech.me
  description: Production
- url: https://sandbox.sa.leantech.me
  description: Sandbox
- url: https://api2.sa.leantech.me
  description: Production
security:
- bearerAuth: []
tags:
- name: Credit Obligations (New)
paths:
  /insights/v3/credit-obligations:
    servers: []
    get:
      operationId: getCreditObligationsV3
      summary: Get Credit Obligations
      description: Delivers a structured view of a user's borrowing activity as per the connected account.  Shows repayments and disbursements broken down by lender name and credit type.
      parameters:
      - name: entity_id
        in: query
        description: The `entity_id` you're querying for.
        required: true
        schema:
          type: string
          format: uuid
      - name: start_date
        in: query
        description: The start date in UTC (in the format YYYY-MM-DD) of the analysis window. When omitted, defaults to the earliest transaction available for the entity.
        required: false
        schema:
          type: string
          format: date
        x-field-extra-annotation: '@jakarta.validation.constraints.PastOrPresent'
      - name: end_date
        in: query
        description: The end date in UTC (in the format YYYY-MM-DD) of the analysis window (inclusive — transactions on this date are included). When omitted, defaults to the current time.
        required: false
        schema:
          type: string
          format: date
        x-field-extra-annotation: '@jakarta.validation.constraints.PastOrPresent'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    insights:
                      $ref: '#/components/schemas/CreditObligationsV2Payload'
                    type:
                      $ref: '#/components/schemas/InsightsResultType'
                  type: object
              examples:
                Get_CreditObligations:
                  summary: Successful get credit obligations
                  value:
                    status: OK
                    results_id: 6cdf799f-6beb-4fb5-a9de-bf07771c8da3
                    message: Data successfully retrieved
                    meta: null
                    timestamp: '2026-06-04T07:19:41.702056182Z'
                    status_detail: null
                    type: credit-obligations
                    insights:
                      credit_obligations:
                        repayments:
                          overall:
                            transaction_count: 6
                            total_amount:
                              currency: AED
                              amount: 2410.61
                            average_monthly_amount:
                              currency: AED
                              amount: 66.96
                            average_monthly_amount_active:
                              currency: AED
                              amount: 602.65
                            average_monthly_transactions: 0.17
                            active_months: 4
                            lender_count: 2
                            lender_organizations:
                            - TABBY
                            - Tamara
                          breakdown:
                          - lender_name: TABBY
                            credit_type: BNPL
                            transaction_count: 3
                            total_amount:
                              currency: AED
                              amount: 1497.92
                            average_monthly_amount:
                              currency: AED
                              amount: 41.61
                            average_monthly_amount_active:
                              currency: AED
                              amount: 748.96
                            first_transaction_date: '2025-07-27'
                            last_transaction_date: '2025-08-26'
                            active_months: 2
                          - lender_name: Tamara
                            credit_type: BNPL
                            transaction_count: 3
                            total_amount:
                              currency: AED
                              amount: 912.69
                            average_monthly_amount:
                              currency: AED
                              amount: 25.35
                            average_monthly_amount_active:
                              currency: AED
                              amount: 304.23
                            first_transaction_date: '2025-06-27'
                            last_transaction_date: '2025-09-26'
                            active_months: 3
                        disbursements:
                          overall:
                            transaction_count: 1
                            total_amount:
                              currency: AED
                              amount: 44482.5
                            average_monthly_amount:
                              currency: AED
                              amount: 1235.63
                            average_monthly_amount_active:
                              currency: AED
                              amount: 44482.5
                            average_monthly_transactions: 0.03
                            active_months: 1
                            lender_count: 1
                            lender_organizations:
                            - tamweelaloula
                          breakdown:
                          - lender_name: tamweelaloula
                            transaction_count: 1
                            total_amount:
                              currency: AED
                              amount: 44482.5
                            average_monthly_amount:
                              currency: AED
                              amount: 1235.63
                            average_monthly_amount_active:
                              currency: AED
                              amount: 44482.5
                            first_transaction_date: '2025-07-17'
                            last_transaction_date: '2025-07-17'
                            active_months: 1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResult'
              examples:
                InvalidParametersExample:
                  $ref: '#/components/examples/InsightsInvalidParametersExample'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResult'
              examples:
                UserPermissionsNotGrantedExample:
                  $ref: '#/components/examples/InsightsUserPermissionsNotGrantedExample'
                ConsentExpiredExample:
                  $ref: '#/components/examples/InsightsConsentExpiredExample'
                TransactionRangeNotGrantedExample:
                  $ref: '#/components/examples/InsightsTransactionRangeNotGrantedExample'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResult'
              examples:
                UnknownEntityExample:
                  $ref: '#/components/examples/InsightsUnknownEntityExample'
                DataNotFoundExample:
                  $ref: '#/components/examples/InsightsDataNotFoundExample'
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResult'
              examples:
                TimeoutExample:
                  $ref: '#/components/examples/InsightsTimeoutExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightsResult'
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InsightsInternalServerErrorExample'
      tags:
      - Credit Obligations (New)
components:
  schemas:
    CreditObligationsDisbursementBreakdown:
      description: Aggregate disbursement stats for a single lender.
      type: object
      properties:
        lender_name:
          description: Lender organization name.
          type: string
        transaction_count:
          description: Number of disbursement transactions from this lender.
          type: integer
        total_amount:
          description: Total disbursement amount from this lender.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount:
          description: Average monthly disbursement amount across the full analysis window.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount_active:
          description: Average monthly disbursement amount across active months only.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        first_transaction_date:
          description: Date of the first disbursement transaction from this lender.
          type: string
          format: date
        last_transaction_date:
          description: Date of the most recent disbursement transaction from this lender.
          type: string
          format: date
        active_months:
          description: Number of months with at least one disbursement from this lender.
          type: integer
      additionalProperties: false
      required:
      - lender_name
      - transaction_count
      - total_amount
      - average_monthly_amount
      - average_monthly_amount_active
      - first_transaction_date
      - last_transaction_date
      - active_months
    BehavioralCategoryBreakdown:
      description: Aggregate stats for one (primary_category, secondary_category) combination.
      type: object
      properties:
        primary_category:
          description: Primary category name.
          type: string
        secondary_category:
          description: Secondary category name.
          type: string
        merchant_names:
          description: Distinct merchant names observed within this category.
          type: array
          items:
            type: string
        merchant_count:
          description: Number of distinct merchants in this category.
          type: integer
        total_amount:
          description: Total spend within this category.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_transaction_amount:
          description: Average amount per transaction in this category.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        transaction_count:
          description: Number of transactions in this category.
          type: integer
        average_monthly_transactions:
          description: Average monthly transaction count across the full analysis window.
          type: number
          format: double
          x-java-type: java.math.BigDecimal
        average_monthly_transactions_active:
          description: Average monthly transaction count across months that had at least one transaction in this category.
          type: number
          format: double
          x-java-type: java.math.BigDecimal
        average_monthly_amount:
          description: Average monthly spend across the full analysis window.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount_active:
          description: Average monthly spend across active months only.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        first_transaction_date:
          description: Timestamp of the first transaction in this category.
          type: string
          format: date-time
        last_transaction_date:
          description: Timestamp of the most recent transaction in this category.
          type: string
          format: date-time
        active_months:
          description: Number of months with at least one transaction in this category.
          type: integer
      required:
      - primary_category
      - secondary_category
      - merchant_names
      - merchant_count
      - total_amount
      - average_transaction_amount
      - transaction_count
      - average_monthly_transactions
      - average_monthly_transactions_active
      - average_monthly_amount
      - average_monthly_amount_active
      - first_transaction_date
      - last_transaction_date
      - active_months
    BigPayments:
      type: object
      properties:
        periods:
          type: array
          items:
            $ref: '#/components/schemas/BigPaymentsPeriod'
      required:
      - periods
    FreelancerPeriodFactors:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/Period'
        total_amount:
          description: Total amount for the period
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_amount:
          description: Average amount for the period
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
    CreditDebitBehaviourPeriod:
      type: object
      properties:
        period:
          description: The time period
          type: string
        grand_average_credit_amount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        grand_average_credit_count:
          description: The average credit transaction count
          type: integer
        grand_average_debit_amount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        grand_average_debit_count:
          description: The average debit transaction count
          type: integer
        grand_average_credit_debit_amount_ratio:
          description: The ratio of credit to debit amounts
          type: number
        grand_average_credit_debit_count_ratio:
          description: The ratio of credit to debit transaction counts
          type: number
        total_volume_of_credit:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        total_volume_of_debit:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        total_volume_of_credit_debit_ratio:
          description: The ratio of total credit to debit volumes
          type: number
      required:
      - period
      - grand_average_credit_amount
      - grand_average_credit_count
      - grand_average_debit_amount
      - grand_average_debit_count
      - grand_average_credit_debit_amount_ratio
      - grand_average_credit_debit_count_ratio
      - total_volume_of_credit
      - total_volume_of_debit
      - total_volume_of_credit_debit_ratio
    Currency:
      description: The ISO 3 letter currency code
      type: string
      examples:
      - AED
      pattern: ^[A-Z]{3}$
    CashBalanceTotal:
      type: object
      properties:
        average_balance:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        initial_balance:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        current_balance:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        available_balance:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        frequency_of_contributions:
          description: How often deposits are made to the account
          type: string
    CurrencyAmount:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        amount:
          description: The amount of money in the currency specified.
          type: number
      required:
      - currency
      - amount
    FrequencyTime:
      description: Frequency of contributions
      type: string
      enum:
      - MONTHLY
      - WEEKLY
      - DAILY
    CashBalanceOutflowFactors:
      type: object
      properties:
        spike_transactions:
          type: array
          items:
            $ref: '#/components/schemas/MonthlyAmount'
      allOf:
      - $ref: '#/components/schemas/BaseInflowOutflowFactors'
      required:
      - spike_transactions
      x-child: true
    CashFlowNet:
      type: object
      properties:
        overall_amount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        net_cashflow:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
    CreditAssessmentComputedIndicators:
      description: Derived financial indicators used in credit assessment decisions.
      type: object
      properties:
        average_monthly_net_cashflow:
          description: Average monthly net cashflow (weighted income minus total expenses).
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        dbr:
          description: monthly credit obligations ÷ weighted monthly income, with the lender's configurable ceiling (default 0.45) and the maximum new installment affordable before that ceiling
          allOf:
          - $ref: '#/components/schemas/CreditAssessmentRatioIndicator'
        affordability:
          description: (essential expenses + credit obligations) ÷ weighted monthly income over configured essential categories, with the lender's configurable ceiling (default 0.70) and the maximum new installment affordable before that ceiling.
          allOf:
          - $ref: '#/components/schemas/CreditAssessmentRatioIndicator'
      additionalProperties: false
      required:
      - average_monthly_net_cashflow
      - dbr
      - affordability
    CreditObligationsRepaymentBreakdown:
      description: Aggregate repayment stats for a single lender.
      type: object
      properties:
        lender_name:
          description: Lender organization name.
          type: string
        credit_type:
          description: The type of credit product (e.g. "BNPL").
          type: string
        transaction_count:
          description: Number of repayment transactions with this lender.
          type: integer
        total_amount:
          description: Total repayment amount with this lender.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount:
          description: Average monthly repayment amount across the full analysis window.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount_active:
          description: Average monthly repayment amount across active months only.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        first_transaction_date:
          description: Date of the first repayment transaction with this lender.
          type: string
          format: date
        last_transaction_date:
          description: Date of the most recent repayment transaction with this lender.
          type: string
          format: date
        active_months:
          description: Number of months with at least one repayment to this lender.
          type: integer
      additionalProperties: false
      required:
      - lender_name
      - credit_type
      - transaction_count
      - total_amount
      - average_monthly_amount
      - average_monthly_amount_active
      - first_transaction_date
      - last_transaction_date
      - active_months
    BalanceFactorsPeriod:
      type: object
      properties:
        period:
          description: The time period
          type: string
        average_balance:
          description: The average balance for the period
          type: number
      x-class-extra-annotation: '@lombok.AllArgsConstructor'
    NonCreditObligationsBreakdownBy:
      type: object
      properties:
        by:
          description: The breakdown category type (e.g., RECURRING_TRANSACTIONS)
          type: string
        breakdowns:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NonCreditObligationsBreakdown'
    FreelancerInflowsOutflows:
      type: object
      properties:
        total_amount:
          description: Total amount of inflows/outflows
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        transactions_count:
          description: Total number of transactions
          type: integer
        periods:
          description: Historical data for different periods
          type: array
          items:
            $ref: '#/components/schemas/FreelancerPeriodFactors'
    EmployerDetails:
      type: object
      properties:
        name:
          description: Official name of the employer in English and Arabic.
          allOf:
          - $ref: '#/components/schemas/Translation'
        cr_number:
          description: Employer’s Commercial Registration (CR) number.
          type:
          - integer
          - 'null'
          format: int64
    CashFlowPatternMonthlyTotal:
      type: object
      properties:
        month:
          description: The month in YYYY-MM format.
          type: string
          examples:
          - 2026-01
        amount:
          description: The total amount for this month.
          type: object
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        transaction_count:
          description: The number of transactions in this month.
          type: integer
      required:
      - month
      - amount
      - transaction_count
    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
    Behaviors:
      description: 'Behavioral insights aggregating debit transactions over a period: three breakdown sections (by category, by merchant, by location), each carrying its own detected-* counts and entry breakdown.'
      type: object
      properties:
        by_category:
          $ref: '#/components/schemas/BehaviorsCategorySection'
        by_merchant:
          $ref: '#/components/schemas/BehaviorsMerchantSection'
        by_location:
          $ref: '#/components/schemas/BehaviorsLocationSection'
      required:
      - by_category
      - by_merchant
      - by_location
    CashBalance:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/CashBalanceTotal'
        monthly_totals:
          type: array
          items:
            $ref: '#/components/schemas/CashBalanceMonthlyTotal'
        balance_factors:
          $ref: '#/components/schemas/BalanceFactors'
      additionalProperties: false
    EmploymentPayload:
      type: object
      properties:
        employment_details:
          type: array
          items:
            $ref: '#/components/schemas/EmploymentDetails'
      additionalProperties: false
    CreditAssessments:
      description: Credit evaluation data including income, expenses, balance, and computed indicators.
      type: object
      properties:
        income:
          $ref: '#/components/schemas/CreditAssessmentIncome'
        expenses:
          $ref: '#/components/schemas/CreditAssessmentExpenses'
        balance:
          $ref: '#/components/schemas/CreditAssessmentBalance'
        computed_indicators:
          $ref: '#/components/schemas/CreditAssessmentComputedIndicators'
      additionalProperties: false
      required:
      - income
      - expenses
      - balance
      - computed_indicators
    MonthlyTotalExpenses:
      type: object
      properties:
        month:
          description: 'Number of month within the year (e.g.: January is represented as 1 and December is represented as 12)'
          type: integer
          format: int32
        year:
          description: Year.
          type: integer
          format: int32
        amount:
          description: Total expenses for the month.
          type: number
          x-java-type: java.math.BigDecimal
        count:
          description: Number of expense transactions in the month.
          type: integer
          format: int32
        is_month_complete:
          description: Determines if Lean retrieved the data for all days for the month. This will always be `true`, except for the first and last month retrieved.
          type: boolean
        breakdown:
          description: Breakdown of expenses by category.
          type: array
          items:
            $ref: '#/components/schemas/Breakdown'
      required:
      - amount
      - breakdown
    CashBalanceInflowFactors:
      type: object
      properties:
        percent_salary_transaction:
          description: Percentage of salary inflows
          type: number
      allOf:
      - $ref: '#/components/schemas/BaseInflowOutflowFactors'
      required:
      - pct_salary
      x-child: true
    ExpensesTransaction:
      type: object
      properties:
        account_id:
          description: The account ID for the transaction
          type: string
          format: uuid
        transaction_id:
          description: The unique transaction identifier
          type: string
        transaction_information:
          description: Additional information about the transaction
          type:
          - string
          - 'null'
        booking_date_time:
          description: The date and time when the transaction was booked
          type: string
          format: date-time
        amount:
          description: The transaction amount
          type: number
        category:
          description: The expense category
          type: string
      required:
      - account_id
      - transaction_id
      - booking_date_time
      - amount
      - category
    CategoryMonthlyBreakdownElement:
      type: object
      properties:
        category:
          description: The category of the transaction.
          type: string
        amount:
          description: Total expenses for the category.
          type: number
          x-java-type: java.math.BigDecimal
        count:
          description: Number of expenses transactions for the category.
          type: integer
          format: int32
        fraction_of_total_expenses:
          description: Fraction of the total expenses that this category represents.
          type: number
          x-java-type: java.math.BigDecimal
      required:
      - category
      - amount
    ResultStatus:
      description: The status of the request
      type: string
      enum:
      - OK
      - PENDING
      - FAILED
      - CONSENT_EXPIRED
      - RECONNECT_REQUIRED
      - PROCESSING_STARTED
    NonCreditObligationsTotal:
      type: object
      properties:
        amount:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        count:
          description: Total number of transactions
          type: integer
          format: int32
        first_date_time:
          description: Date and time of the first transaction
          type:
          - string
          - 'null'
          format: date-time
          x-java-type: java.time.Instant
        last_date_time:
          description: Date and time of the last transaction
          type:
          - string
          - 'null'
          format: date-time
          x-java-type: java.time.Instant
        average_monthly_amount:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_count:
          description: Average number of transactions per month
          type: number
        maximum_monthly_amount:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/NonCreditObligationsMonthlyAmount'
        minimum_monthly_amount:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/NonCreditObligationsMonthlyAmount'
        breakdown:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NonCreditObligationsBreakdownBy'
      required:
      - average_monthly_amount
    BehavioralLocationBreakdown:
      description: Aggregate stats for one location.
      type: object
      properties:
        location:
          description: Location name where transactions occurred.
          type: string
        transaction_count:
          description: Number of transactions in this location.
          type: integer
        total_amount:
          description: Total spend in this location.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_transaction_amount:
          description: Average transaction amount in this location.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_transactions:
          description: Average monthly transaction count in this location across the full analysis window.
          type: number
          format: double
          x-java-type: java.math.BigDecimal
        average_monthly_transactions_active:
          description: Average monthly transaction count in this location across active months only.
          type: number
          format: double
          x-java-type: java.math.BigDecimal
        average_monthly_amount:
          description: Average monthly spend in this location across the full analysis window.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        average_monthly_amount_active:
          description: Average monthly spend in this location across active months only.
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        first_transaction_date:
          description: Timestamp of the first transaction in this location.
          type: string
          format: date-time
        last_transaction_date:
          description: Timestamp of the most recent transaction in this location.
          type: string
          format: date-time
        active_months:
          description: Number of months with at least one transaction in this location.
          type: integer
      required:
      - location
      - transaction_count
      - total_amount
      - average_transaction_amount
      - average_monthly_transactions
      - average_monthly_transactions_active
      - average_monthly_amount
      - average_monthly_amount_active
      - first_transaction_date
      - last_transaction_date
      - active_months
    BreakdownElement:
      oneOf:
      - $ref: '#/components/schemas/CategoryMonthlyBreakdownElement'
      - $ref: '#/components/schemas/CategoryTotalBreakdownElement'
    AmountCount:
      type: object
      properties:
        amount:
          allOf:
          - $ref: '#/components/schemas/CurrencyAmount'
        count:
          description: The total number of transactions
          type:
          - integer
          - 'null'
          format: int32
      required:
      - amount
    BalanceFactors:
      type: object
      properties:
        periods:
          type: ar

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lean-technologies/refs/heads/main/openapi/lean-technologies-credit-obligations-new-api-openapi.yml