---
title: "List loans"
method: GET
path: "/v2/loans"
tags: ["Loans"]
---

# List loans

`GET /v2/loans`

## Request

- Base URL: `https://sandbox.pismolabs.io/lending`
- URL: `https://sandbox.pismolabs.io/lending/v2/loans`
- Auth: HTTP bearer

List loans

## Query parameters

- `nextCursor` string, required: Opaque pagination cursor returned by the API. Pass back exactly as received to retrieve the next page; do not parse or modify it.
- `limit` integer: Maximum returned list size. Default = `10`.
- `status` 'PENDING' | 'BOOKED' | 'ACTIVE' | 'CANCELED' | 'SETTLED' | 'RENEGOTIATED': Loan status `PENDING`-The loan has been created but has not yet been booked. Terms may still be under review or awaiting confirmation. `BOOKED`-The loan has been approved and booked. The payment schedule is confirmed and the loan is ready for disbursement. `ACTIVE`-The loan is active and in progress. Funds have been disbursed and the borrower is expected to make repayments according to the agreed schedule. `CANCELED`-A repayment is no longer expected to be paid. `SETTLED`-The loan has been fully repaid and is closed. No further repayments are expected. `RENEGOTIATED`-The original loan terms have been modified after booking, typically due to a change in repayment conditions or borrower circumstances.
- `loanProductId` string: Loan product ID. Accepts either a lowercase UUID (e.g., "2717a296-124a-47cc-b2a1-91e80dc723eb") or an uppercase alphanumeric string with underscores (e.g., "MY_LOAN_PRODUCT_001"). If not provided during creation, a UUID is auto-generated.
- `accountId` string
- `expand` boolean: Boolean value
- `authorizationId` number: Authorization ID

## Response `200`

Loan retrieved.

- object
  - `has_next` boolean: Does the query have additional items to return?
  - `next_cursor` string: Opaque pagination cursor returned by the API. Pass back exactly as received to retrieve the next page; do not parse or modify it.
  - `items` LendingLoanRepaymentResponse[]
    - `account_id` integer, required: Account ID
    - `created_at` string, date-time, required: Loan created date in UTC. Format = YYYY-MM-DDThh:mm:ss.SSSZ
    - `loan_amount` number, double, required: Loan amount
    - `loan_id` string, required: Custom ID for the loan. Must consist of uppercase alphanumeric characters and underscores.
    - `product_id` string, required: Loan product ID. Accepts either a lowercase UUID (e.g., "2717a296-124a-47cc-b2a1-91e80dc723eb") or an uppercase alphanumeric string with underscores (e.g., "MY_LOAN_PRODUCT_001"). If not provided during creation, a UUID is auto-generated.
    - `start_date` string, date, required: Date loan was first active. Format = YYYY-MM-DD.
    - `status` 'PENDING' | 'BOOKED' | 'ACTIVE' | 'CANCELED' | 'SETTLED' | 'RENEGOTIATED', required: Loan status `PENDING`-The loan has been created but has not yet been booked. Terms may still be under review or awaiting confirmation. `BOOKED`-The loan has been approved and booked. The payment schedule is confirmed and the loan is ready for disbursement. `ACTIVE`-The loan is active and in progress. Funds have been disbursed and the borrower is expected to make repayments according to the agreed schedule. `CANCELED`-A repayment is no longer expected to be paid. `SETTLED`-The loan has been fully repaid and is closed. No further repayments are expected. `RENEGOTIATED`-The original loan terms have been modified after booking, typically due to a change in repayment conditions or borrower circumstances.
    - `total_payable` TotalPayable, required
      - `amount_due` object
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `arrears` object: Outstanding amount owed across all installments currently in `PAST_DUE` or `OVERDUE` status, broken down by component. Offers the total in arrears at loan level without summing individual installments. Zero when no installment is `PAST_DUE` or `OVERDUE` status.
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `charge` number, double: Charge amount
      - `fee` number, double: Fee amount
      - `interest` number, double: Interest amount
      - `penalty` number, double: Penalty amount
      - `principal` number, double: Principal amount
      - `tax` number, double: Tax amount
      - `total` number, double: Total amount
    - `total_paid` TotalPaid: Consolidated loan-level amount that has already been paid across all repayments, aggregated server-side and broken down by component under `amount_paid`. Removes the need to total all repayment-level objects. Loan progress can be derived from `total_paid.amount_paid.total` versus `total_payable.total`.
      - `amount_paid` object
        - `principal` number, double: Principal amount
        - `interest` number, double: Interest amount
        - `fee` number, double: Fee amount
        - `tax` number, double: Tax amount
        - `charge` number, double: Charge amount
        - `penalty` number, double: Penalty amount
        - `total` number, double: Total amount
    - `updated_at` string, date-time, required: Loan last updated date in UTC. Format = YYYY-MM-DDThh:mm:ss.SSSZ.
    - `authorization_tracking_id` string, uuid: Authorization tracking ID
    - `contracted_installment_count` integer: Number of installments contracted when the loan was booked. For loans booked before this value was stored, it is the number of installments the loan has, cancelled installments included.
    - `days_past_due` integer: Number of calendar days elapsed since the real due date of the loan's most overdue repayment. Computed from repayments currently in a past due or overdue status. A value of `0` indicates the loan has no past due or overdue repayments.
    - `disbursement` LoanDisbursement: Disbursement details for the loan. The consolidated fields `total_disbursed_amount`, `remaining_to_disburse_amount` and `can_disburse_more` are present only for `MULTIPLE` disbursement loans and are omitted for `SINGLE` and `NONE`.
      - `can_disburse_more` boolean: Does the loan still have remaining disbursement capacity? (Meaning, the `remaining_to_disburse_amount` is greater than 0.) Present only for `MULTIPLE` disbursement loans; omitted for `SINGLE` and `NONE`.
      - `remaining_to_disburse_amount` number, double: Remaining amount available to disburse, computed as `loan_principal_amount` minus `total_disbursed_amount`, never goes below 0. Present only for `MULTIPLE` disbursement loans; omitted for `SINGLE` and `NONE`.
      - `schedule` DisbursementScheduleItem[]: List of disbursement schedules
        - `amount` number, double: Disbursement amount
        - `authorization_id` integer: Authorization ID
        - `date` string, date: Disbursement date. Format = YYYY-MM-DD.
        - `disbursement_account` LoanDisbursementAccount
          - `account_id` integer: ID of the account receiving the disbursed funds
          - `account_type` 'INTERNAL' | 'EXTERNAL': Whether funds are disbursed to an account inside Pismo (`INTERNAL`) or an external account (`EXTERNAL`)
        - `id` string, uuid: Disbursement ID
        - `status` 'SCHEDULED' | 'PROCESSING' | 'CANCELED' | 'EXPIRED' | 'PAID': Disbursement status
        - `tracking_id` string, uuid: Tracking ID
        - `transactions_ids` integer[]: List of transaction IDs
      - `total_disbursed_amount` number, double: Sum of the amounts of all active disbursements, excluding those that are `CANCELED` or `EXPIRED`. Present only for `MULTIPLE` disbursement loans; omitted for `SINGLE` and `NONE`.
      - `type` 'SINGLE' | 'MULTIPLE': Disbursement type
    - `external_id` string: External ID
    - `grace_period_days` integer: Number of calendar days after the installment due date during which late fees and delinquency are not applied. A value of `0` or omitted indicates no grace period.
    - `initial_amounts` InitialAmounts: Loan amounts contracted at booking including principal, interest, amount charged, tax, fees, and penalties. For loans booked before these amounts were stored, each missing component is the sum of that component across the installments' booking postings (`tax` from the Brazilian IOF posting, `penalty` is zero). The sum of all components is the `total`.
      - `principal` number, double: Principal amount
      - `interest` number, double: Interest amount
      - `charge` number, double: Charge amount
      - `tax` number, double: Tax amount
      - `fee` number, double: Fee amount
      - `penalty` number, double: Penalty amount
      - `total` number, double: Total amount
    - `insurance_summary` LoanInsuranceSummary: Loan-level insurance history summary. Returned only when `includeInsuranceHistory=true` and the loan has an insurance policy. It is omitted entirely for loans that were never insured. Per-installment `insurance_premium_state` values remain the source of truth.
      - `installment_counts` object, required: Count of insured installments grouped by derived premium state. Paid + canceled + pending installments equals the total number of insured installments.
        - `canceled` integer, required: Number of installments whose premium was canceled and never collected (`insurance_premium_state = CANCELED`)
        - `paid` integer, required: Number of installments whose premium was collected (`insurance_premium_state = PAID`)
        - `pending` integer, required: Number of installments still awaiting premium collection (`insurance_premium_state = PENDING`)
      - `insurance_ever_active` boolean, required: Was insurance ever collected in the history of the loan? Set to `true` when at least one insurance premium has been collected (at least one installment has `insurance_premium_state = PAID`); `false` when the loan has an insurance policy but no premium was ever collected.
      - `last_covered_date` string, date: Date value. Format = YYYY-MM-DD.
    - `loan_principal_amount` number, double: Principal portion of the loan amount, excluding interest, fees, taxes, and penalty
    - `original_loan_id` string, uuid: Original loan ID. When a loan is created from a restructure, this field contains the ID of the original loan that was restructured.
    - `prepayments` PrepaymentSummaryV2Response[]: List of prepayments registered for this loan. Only populated when the loan aggregate is fully expanded (single GET, or paginated GET with `expand=true`). Only prepayments in `REGISTERED` status are returned.
      - `amount_paid` number: Total prepayment amount paid by the customer
      - `created_at` string, date-time: When the prepayment record was created. Format = YYYY-MM-DDThh:mm:ss.SSSZ.
      - `insurance_amount_paid` number: Insurance portion settled with the prepayment, if any
      - `new_remaining_total` number: Outstanding total of the loan after this prepayment was applied
      - `penalty_amount_paid` number: Penalty amount charged on the prepayment, if any
      - `prepayment_id` string, uuid: Identifier of the prepayment
      - `reduce_option` 'INSTALLMENT' | 'TERM': Defines the way that the outstanding loan amount is reduced.
      - `settlement_date` string, date-time: Settlement date of the prepayment. Format = YYYY-MM-DDThh:mm:ss.SSSZ.
      - `status` 'CREATED' | 'PROCESSING' | 'REGISTERED': Lifecycle status of the prepayment
      - `tax_amount_paid` number: Tax amount applied to the prepayment
      - `updated_at` string, date-time: When the prepayment record was last updated. Format = YYYY-MM-DDThh:mm:ss.SSSZ.
    - `rates` LoansRates: Loan rates including annual interest rate and effective annual and monthly costs
      - `annual_interest_rate` number, double: Annual interest rate
      - `effective_annual_cost` number, double: Effective annual cost of the loan in configured currency
      - `effective_monthly_cost` number, double: Effective monthly cost of the loan in configured currency
      - `interest_rate` number, double: Loan interest rate
    - `repayment_schedule` object[]: Repayment schedule installments for this loan
      - `repayment_id` string, uuid: Repayment ID
      - `transactions_ids` integer[]: List of transaction IDs
      - `status` 'PENDING' | 'PROCESSING' | 'SCHEDULED' | 'PAST_DUE' | 'PAID' | 'PARTIALLY_PAID' | 'CANCELED' | 'PENDING_PAYMENT' | 'PAST_DUE_PENDING_PAYMENT' | 'ACTIVE' | 'OVERDUE' | 'OVERDUE_PENDING_PAYMENT' | 'IN_GRACE_PERIOD' | 'IN_GRACE_PERIOD_PENDING_PAYMENT' | 'PARTIALLY_PAID_IN_GRACE_PERIOD' | 'PAID_WITHIN_GRACE' | 'PARTIALLY_PAID_PENDING_PAYMENT' | 'PAST_DUE_PARTIALLY_PAID' | 'OVERDUE_PARTIALLY_PAID' | 'PAST_DUE_PARTIALLY_PAID_PENDING_PAYMENT' | 'OVERDUE_PARTIALLY_PAID_PENDING_PAYMENT' | 'PARTIALLY_PAID_IN_GRACE_PERIOD_PENDING_PAYMENT': Current lifecycle status of a loan installment. **Normal lifecycle:** `SCHEDULED` → (due date passes) → `PAST_DUE` → (penalty accrual window closes) → `OVERDUE` → (payment received) → `PAID` **Grace period lifecycle:** `SCHEDULED` → `IN_GRACE_PERIOD` → (grace period expires) → `PAST_DUE` → `OVERDUE` → `PAID` `SCHEDULED` → `IN_GRACE_PERIOD` → (payment within grace period) → `PAID_WITHIN_GRACE` **Partial payment lifecycle:** `PAST_DUE` → (partial payment made) → `PARTIALLY_PAID` → (due date passes) → `PAST_DUE_PARTIALLY_PAID` → (accrual window closes) → `OVERDUE_PARTIALLY_PAID` → (remaining balance paid) → `PAID` `IN_GRACE_PERIOD` → (partial payment made) → `PARTIALLY_PAID_IN_GRACE_PERIOD` → (grace period expires) → `PARTIALLY_PAID` **`PAST_DUE` vs `OVERDUE`:** - `PAST_DUE`: the due date has passed and daily penalty charges are actively accruing. - `OVERDUE`: the penalty accrual window has closed (configurable per loan product). No further charges accrue; the installment balance is frozen. **`PAST_DUE_PARTIALLY_PAID` vs `OVERDUE_PARTIALLY_PAID`:** - `PAST_DUE_PARTIALLY_PAID`: a partial payment has been received, the due date has passed, and daily penalty charges are still accruing on the remaining balance. - `OVERDUE_PARTIALLY_PAID`: a partial payment has been received and the penalty accrual window has closed. No further charges accrue on the remaining balance. **Pending payment suffixes (`*_PENDING_PAYMENT`):** When a group payment or prepayment is initiated, the installment moves to a `*_PENDING_PAYMENT` variant (for example, `PAST_DUE` → `PAST_DUE_PENDING_PAYMENT`). If the payment is confirmed the installment is settled; if it expires the installment reverts to its base status. Penalty accrual follows the base status while a payment is pending: `PAST_DUE_*` variants keep accruing on the remaining balance, `OVERDUE_*` variants do not. Pending-payment variants of partially paid installments: - `PARTIALLY_PAID_PENDING_PAYMENT`: a group payment is pending on a partially paid installment (outside the grace-period and past-due contexts). - `PAST_DUE_PARTIALLY_PAID_PENDING_PAYMENT`: a group payment is pending on a `PAST_DUE_PARTIALLY_PAID` installment; penalty charges keep accruing until confirmation. Moves to `OVERDUE_PARTIALLY_PAID_PENDING_PAYMENT` when the accrual window closes, reverts to `PAST_DUE_PARTIALLY_PAID` if the payment expires, or settles to `PAID` once confirmed. - `OVERDUE_PARTIALLY_PAID_PENDING_PAYMENT`: a group payment is pending on an `OVERDUE_PARTIALLY_PAID` installment; no further charges accrue. Reverts to `OVERDUE_PARTIALLY_PAID` if the payment expires, or settles to `PAID` once confirmed. - `PARTIALLY_PAID_IN_GRACE_PERIOD_PENDING_PAYMENT`: a group payment is pending on a `PARTIALLY_PAID_IN_GRACE_PERIOD` installment. Moves to `PAST_DUE_PENDING_PAYMENT` when the grace period expires, or reverts to `PARTIALLY_PAID_IN_GRACE_PERIOD` if the payment expires.
      - `period` integer: Period
      - `due_date` string, date: Loan payment due date. Format = YYYY-MM-DD.
      - `real_due_date` string, date: Adjusted due date. Format = YYYY-MM-DD.
      - `present_value_amount` number, double
      - `present_value_discount` number, double
      - `amount_due` object: Balance details for a loan
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `amount_paid` object: Balance details for a loan
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `initial_amount` object: Balance details for a loan
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `insurance` object: Balance details for a loan
        - `charge` number, double: Charge amount
        - `fee` number, double: Fee amount
        - `interest` number, double: Interest amount
        - `penalty` number, double: Penalty amount
        - `principal` number, double: Principal amount
        - `tax` number, double: Tax amount
        - `total` number, double: Total amount
      - `insurance_premium_state` 'PAID' | 'CANCELED' | 'PENDING': Derived state of an installment's insurance premium. Present only when `includeInsuranceHistory=true` and the installment belongs to an insured loan. The platform reads the information from the current installment status (it is not persisted). For uninsured loans and for installments with no linked insurance record you do not see this state. `PAID` - The insurance premium was collected. The installment status is settled (`PAID` or `PAID_WITHIN_GRACE`). `CANCELED` - The insurance was canceled and the premium was never collected (installment status `CANCELED`). Covers both cancellation before the first premium and mid-plan cancellation of later installments. `PENDING` - The premium is still awaiting collection (includes the `*_PENDING_PAYMENT` statuses).
    - `restructure_loan_id` string, uuid: Restructure loan ID. When a loan has been restructured, this field contains the ID of the new loan created from the restructure.
    - `restructured_initial_amounts` InitialAmounts: Loan amounts contracted at booking including principal, interest, amount charged, tax, fees, and penalties. For loans booked before these amounts were stored, each missing component is the sum of that component across the installments' booking postings (`tax` from the Brazilian IOF posting, `penalty` is zero). The sum of all components is the `total`.
      - `principal` number, double: Principal amount
      - `interest` number, double: Interest amount
      - `charge` number, double: Charge amount
      - `tax` number, double: Tax amount
      - `fee` number, double: Fee amount
      - `penalty` number, double: Penalty amount
      - `total` number, double: Total amount
    - `total_expected_payment_amount` number, double: Total expected payment amount for the loan including principal, interest, fees, and penalty (if applied)
    - `transactions_ids` integer[]: List of transaction IDs

## Other responses

- `400`: Bad request.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/pismo/apis/lending.md) - [All operations](https://skmtc.dev/pismo/apis/lending/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/lending/revisions/a288022e3d8b?raw)