# List all loan snapshots

List and filter loan history snapshots associated with your account.

Endpoint: GET /loans
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Query parameters:

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `limit` (integer)
    Indicates how many results to return per page. By default we return 20 results
per page.


ℹ️ The minimum number of results returned per page is 1 and the maximum is 100.
If you enter a value greater than 100, our API will default to the maximum
value (100).
    Example: 15

  - `payment_method_id` (string)
    Filter by the payment method ID associated with the loan.
    Example: "43e5a5b1-b2c6-4f45-8c1f-f28fec707a4b"

  - `merchant_customer_id` (string)
    Filter by your merchant-assigned customer identifier.
    Example: "CUST-001234"

  - `customer_id` (string)
    The unique identifier created by Belvo used to reference the customer.
    Example: "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"

  - `default_date` (string)
    Filter by exact default date in YYYY-MM-DD format.
    Example: "2026-04-15"

  - `status` (string)
    Filter by loan status. Can be either active or inactive.
    Enum: "active", "inactive"

  - `start_date` (string)
    Return loans with a defaultDate greater than or equal to the specified date. The date must be in the format YYYY-MM-DD.
    Example: "2026-04-01"

  - `end_date` (string)
    Return loans with a defaultDate less than or equal to the specified date. The date must be in the format YYYY-MM-DD.
    Example: "2026-04-30"

  - `order` (string)
    Return results in either ascending (oldest to newest) or descending (newest to oldest) order, according to the createdDate.

Can be either:
  - asc for ascending order
  - desc for descending order
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `items` (array)
    An array of loan history snapshot objects.

  - `items.id` (string, required)
    The unique identifier created by Belvo used to reference this loan history snapshot.

  - `items.loanId` (string)
    The unique identifier created by Belvo used to reference the parent loan entity.

  - `items.customerId` (string, required)
    The unique identifier created by Belvo used to reference the customer.

  - `items.paymentMethodId` (string)
    The unique identifier created by Belvo used to reference the payment method associated with this loan.

  - `items.merchantCustomerId` (string, required)
    Your merchant-assigned customer identifier.

  - `items.status` (string, required)
    The loan status. Can be either:
  - active
    The loan is currently being tracked for collection.
  - inactive
    The loan is no longer active.
    Enum: same as `status` (2 values)

  - `items.principalAmount` (string, required)
    The principal amount.

  - `items.totalBalance` (string, required)
    The total outstanding balance.

  - `items.targetCollectionDate` (string, required)
    The date Belvo will attempt to collect payment, in YYYY-MM-DD format. This date is set as either the day that the request was initially made or for the next business day.

  - `items.defaultDate` (string, required)
    The date that the customer defaulted on the loan, in YYYY-MM-DD format.

  - `items.daysOverdue` (integer)
    The number of days the loan is overdue.

  - `items.issueDate` (string)
    The original issue date, in YYYY-MM-DD format.

  - `items.loanAmount` (string)
    The original loan amount.

  - `items.interestAmount` (string)
    The accumulated interest amount.

  - `items.feesAmount` (string)
    The fees associated with the loan.

  - `items.latePaymentInterestAmount` (string)
    The interest accrued due to late payments.

  - `items.openingCommissionAmount` (string)
    The opening commission charged for the loan.

  - `items.yearlyOrdinalInterestRate` (string)
    The yearly interest rate, with up to 4 decimal places.

  - `items.customerSalary` (string)
    The customer's salary.

  - `items.customerAddress` (string)
    The customer's address.

  - `items.creditStatus` (string)
    The credit status of the loan. Can be either:
  - past_due
    Payment is past the due date.
  - restructured
    The loan has been restructured.
  - canceled
    The loan has been canceled.
  - in_arrears
    The loan is in arrears.
    Enum: "past_due", "restructured", "canceled", "in_arrears"

  - `items.paidInstallments` (integer)
    The number of installments already paid.

  - `items.paidAmount` (string)
    The total amount already paid.

  - `items.lastPaymentDate` (string)
    The date of the last payment.

  - `items.lastPaymentAmount` (string)
    The amount of the last payment.

  - `items.mainPhoneNumber` (string)
    The customer's main phone number.

  - `items.reference` (string)
    Your reference for the loan.

  - `items.createdDate` (string, required)
    The ISO-8601 timestamp when the loan snapshot was created in Belvo's database.

  - `items.lastUpdatedDate` (string, required)
    The ISO-8601 timestamp when the loan snapshot was last updated in Belvo's database.

  - `meta` (object)
    Additional metadata regarding the paginated result set.

  - `meta.totalItems` (integer)
    The total number of items in the paginated result set.
    Example: 100

  - `meta.itemCount` (integer)
    The number of items in the current page.
    Example: 10

  - `meta.itemsPerPage` (integer)
    The number of items requested per page.
    Example: 10

  - `meta.totalPages` (integer)
    The total number of pages in the paginated result set.
    Example: 10

  - `meta.currentPage` (integer)
    The current page number.
    Example: 1

  - `links` (object)
    Links to navigate the paginated result set.

  - `links.first` (string)
    The URL to the first page of the paginated result set.
    Example: "/{resource}?limit=20"

  - `links.last` (string)
    The URL to the last page of the paginated result set.
    Example: "/{resource}?page=4&limit=20"

  - `links.next` (string)
    The URL to the next page of the paginated result set.
    Example: "/{resource}?page=3&limit=20"

  - `links.previous` (string)
    The URL to the previous page of the paginated result set.
    Example: "/{resource}?page=2&limit=20"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 400

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Bad Request"

  - `message` (any)
    A short description of the error, indicating what is wrong with the request.
> Note: We return either a string or an array of strings, depending on the validation error(s). 

The description can be (among others):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 401

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Unauthorized"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
In the case of a 401 Unauthorized error, the message is:

  - Unauthorized credentials
    Example: "Unauthorized credentials"