Skip to content

Getting Loan Data

This guide will demonstrate the process for retrieving a list of loans, and then how to retrieve an individual loan’s data, including its active metadata and all the events associated with it, using the Exchange API.

Prerequisites

Section titled “Prerequisites”

Before you begin, ensure you have the following:

  • Your API key
  • Your Partner ID

If you don’t have an API key or Partner ID, please refer to the Getting Started guide.

Retrieve a List of Loans

Section titled “Retrieve a List of Loans”
GET https://qa.exchange.crfusa.com/api/loans
?partnerId={{partnerId}}
&maxResults=100&viewType=SellerOwned
x-api-key: {{key}}

This request returns a paged list of loans associated with your Partner ID. The response includes a cursor value that you can use to retrieve subsequent pages of results. We will learn more about the cursor in the Polling for Changes guide.

Request Querystring Parameters

Section titled “Request Querystring Parameters”
  • partnerId (required): Your Partner ID.
  • maxResults (optional): The maximum number of loans to return in a single response. Default is 100, maximum is 500.
  • viewType (optional): Specifies the type of loans to retrieve. Possible values are:
    • Listings: Loans that are currently listed for sale.
    • BuyerOwned: Loans where your Partner ID is the buyer.
    • SellerOwned: Loans where your Partner ID is the seller.
    • BuyerPending: Loans which are pending sale
  • cursor: (optional): A cursor value from a previous response to retrieve the next page of results, or to continue from the last time you processed results.

Example response payload

Section titled “Example response payload”
{
  // This is the list of loans returned in this page
  "loans": [
    // Each loan object contains basic information about the loan
    {
      "id": "e7a132bc-58eb-4041-8338-d64fb90d3dc3|SL-1001", // The unique identifier for the loan
      "sellerPartnerId": "e7a132bc-58eb-4041-8338-d64fb90d3dc3", // The Partner ID of the loan's seller
      "sellerPartnerName": "Demo Seller", // The name of the loan's seller
      "sellerLoanId": "SL-1001", // The seller's internal identifier for the loan


      // Dates associated with the loan
      "dateListed": "2022-12-01T15:45:28.3857824+00:00",
      "dateInDefault": null,
      "dateSold": "2022-12-01T06:00:00+00:00",
      "dateLastPaid": "2022-11-30T18:00:00+00:00",
      "dateFunded": "2022-10-31T19:00:00+00:00",
      "dateReviewStarted": "2022-12-01T15:45:39.6854572+00:00",
      "dateBuyerPreApproved": null,
      "dateCreated": "2022-12-01T15:39:05.2475327+00:00",
      "dateLastEvent": "2022-12-01T15:50:34.3149257+00:00",


      // The overall status of the loan
      "status": "InServicing",
      "terminalStatus": null,
      "isForSale": false,


      // The listing metadata - a combination of standard and custom metadata fields
      // many of these fields will vary depending on the program (or "listingTag") associated.
      // Note that listing metadata is meant to never include any PII or sensitive information.
      "listingMetadata": {
        "loanAmount": 239818,
        "percent": 0.8,
        "multiplier": 1,
        "dateFunded": "2022-10-31T19:00:00+00:00",
        "listingTag": "ssbci-mn", // The listing tag, also known as the PROGRAM
        "interestRate": 0.0725,
        "termMonths": 60,
        "interestOnlyPaymentAmount": 1448.90041666667,
        "principalAndInterestPaymentAmount": 17651.6224370318,
        "dateFirstPayment": "2022-11-30T18:00:00+00:00",
        "datePaymentTypeConversion": "2023-11-30T18:00:00+00:00",
        "isRefinance": false,
        "serviceFee": {
          "type": "PercentWithFloor",
          "percentAnnual": 0.0125,
          "floorFeeMonthly": 40
        },
        "businessType": "SoleProprietorship",
        "businessAddressState": "Minnesota",
        "businessAddressCity": "Waconia",
        "businessEmployeeCount": 1,
        "businessIndustry": "51321",
        "OriginationFee": 8393.63,
        "BusinessYearIncorporated": 2001,
        "JobsAdded": 0,
        "PriorBankruptcy": "None",
        "BorrowerAssessedOriginationFee": "150",
        "JobsRetained": "0",
        "UseofProceeds": "LND, BLD",
        "OwnersResidentInCDFIInvestmentArea": "No",
        "OperatingInCDFIInvestmentArea": "Yes",
        "ExpansionIntoCDFIInvestmentArea": "No",
        "IsSEDIBusiness": "No",
        "BIPOCOwnershipMajority": "Yes",
        "WomenOwnershipMajority": "No",
        "VeteranOwnershipMajority": "No",
        "PrincipalOwnerDemographics": "PNR",
        "LastCalendarYearRevenue": "403758",
        "LastCalendarYearProfitLoss": "141315.3",
        "IsBusinessClimateAligned": "No",
        "AffectedByClimateChange": "No"
      },


      // Private metadata associated with the loan, this is where PII or sensitive information can be stored.
      // This object also contains any custom metadata fields that are not part of the listing metadata.
      "privateMetadata": {
        "c2CLeadId": null,
        "businessName": "John's Tacos",
        "businessAddress": {
          "line1": "1252 Crosswinds Way",
          "line2": null,
          "city": "Waconia",
          "state": "Minnesota",
          "postalCode": "55387"
        },
        "OwnerCreditScore": 392
      },


      // Buyer metadata - This data essentially the buyers notes about the loan, this is only available if you are the buyer of the loan
      "buyerMetadata": {},


      // Loan documents
      "loanDocuments": [
        {
          "documentName": "Promissory Note.pdf",
          "documentId": "9bddef60-30b7-43e1-beaa-50cfe65f64a9",
          "tags": [
            "PromissoryNote"
          ],
          "dateUploaded": "2022-12-01T15:40:10.1234567+00:00"
        }
      ],


      // Sale object
      "sale": {
        "saleId": "ffb7cd7f-f179-48a2-a91a-4e6db44a4d22",
        "buyerPartnerId": "dbfb3202-02ba-4a1e-858e-9a4dd04084ba",
        "buyerPartnerName": "Less Super Buyer",
        "status": "Sold", // Indicates the status of the sale
        "percent": 0.8, // The percent of the loan sold
        "multiplier": 1,


        // Indicates the service fee structure
        "serviceFee": {
          "type": "PercentWithFloor",
          "percentAnnual": 0.0125,
          "floorFeeMonthly": 40
        },


        // Dates associated with the sale
        "dateLastUpdated": "2022-12-01T15:49:08.7349133+00:00",
        "dateRecommendedSaleClosed": null
      },


      // The array of events - See the article on 'event types' for more information
      "events": [
        // ...
      ]


    }
  ],
  "cursor": "ijR0fy4e3ggA", // Indicates how to pick up the remaining results
  "hasMoreResults": false // Indicates if there are more results to fetch
}

Retrieving an individual Loan’s Data

Section titled “Retrieving an individual Loan’s Data”

An individual loan can be re-retrieved by its unique loan ID using the following request:

GET https://qa.exchange.crfusa.com/api/loan
?partnerId={{partnerId}}
&loanId={{sellerLoanId}}
x-api-key: {{key}}

This yields back a very similar result as the above, but only for the specified loan ID, and excludes any pagination or event data.

Request Querystring Parameters

Section titled “Request Querystring Parameters”
  • partnerId (required): Your Partner ID.
  • loanId (required): The unique ID of the loan you want to retrieve.

Example response payload

Section titled “Example response payload”
{
  "id": "de4c6b6d-5a3d-4619-b0f2-fa92710c8f57|1440",
  "sellerPartnerId": "de4c6b6d-5a3d-4619-b0f2-fa92710c8f57",
  "sellerPartnerName": "Justin's CDFI",
  "sellerLoanId": "1440",
  "dateListed": "2022-12-01T15:45:28.3857824+00:00",
  "dateInDefault": null,
  "dateSold": "2022-12-01T06:00:00+00:00",
  "dateLastPaid": "2022-11-30T18:00:00+00:00",
  "dateFunded": "2022-10-31T19:00:00+00:00",
  "dateReviewStarted": "2022-12-01T15:45:39.6854572+00:00",
  "dateBuyerPreApproved": null,
  "dateCreated": "2022-12-01T15:39:05.2475327+00:00",
  "dateLastEvent": "2022-12-01T15:50:34.3149257+00:00",
  "status": "InServicing",
  "terminalStatus": null,
  "isForSale": false,
  "sale": {
    "saleId": "ffb7cd7f-f179-48a2-a91a-4e6db44a4d22",
    "buyerPartnerId": "dbfb3202-02ba-4a1e-858e-9a4dd04084ba",
    "buyerPartnerName": "Less Super Buyer",
    "status": "Sold",
    "percent": 0.8,
    "multiplier": 1,
    "serviceFee": {
      "type": "PercentWithFloor",
      "percentAnnual": 0.0125,
      "floorFeeMonthly": 40
    },
    "dateLastUpdated": "2022-12-01T15:49:08.7349133+00:00",
    "dateRecommendedSaleClosed": null
  },
  "listingMetadata": {
    "loanAmount": 239818,
    "percent": 0.8,
    "multiplier": 1,
    "dateFunded": "2022-10-31T19:00:00+00:00",
    "listingTag": "ssbci-mn",
    "interestRate": 0.0725,
    "termMonths": 60,
    "interestOnlyPaymentAmount": 1448.90041666667,
    "principalAndInterestPaymentAmount": 17651.6224370318,
    "dateFirstPayment": "2022-11-30T18:00:00+00:00",
    "datePaymentTypeConversion": "2023-11-30T18:00:00+00:00",
    "isRefinance": false,
    "serviceFee": {
      "type": "PercentWithFloor",
      "percentAnnual": 0.0125,
      "floorFeeMonthly": 40
    },
    "businessType": "SoleProprietorship",
    "businessAddressState": "Minnesota",
    "businessAddressCity": "Waconia",
    "businessEmployeeCount": 1,
    "businessIndustry": "51321",
    "OriginationFee": 8393.63,
    "BusinessYearIncorporated": 2001,
    "JobsAdded": 0,
    "PriorBankruptcy": "None",
    "BorrowerAssessedOriginationFee": "150",
    "JobsRetained": "0",
    "UseofProceeds": "LND, BLD",
    "OwnersResidentInCDFIInvestmentArea": "No",
    "OperatingInCDFIInvestmentArea": "Yes",
    "ExpansionIntoCDFIInvestmentArea": "No",
    "IsSEDIBusiness": "No",
    "BIPOCOwnershipMajority": "Yes",
    "WomenOwnershipMajority": "No",
    "VeteranOwnershipMajority": "No",
    "PrincipalOwnerDemographics": "PNR",
    "LastCalendarYearRevenue": "403758",
    "LastCalendarYearProfitLoss": "141315.3",
    "IsBusinessClimateAligned": "No",
    "AffectedByClimateChange": "No"
  },
  "privateMetadata": {
    "c2CLeadId": null,
    "businessName": "John's Tacos",
    "businessAddress": {
      "line1": "1252 Crosswinds Way",
      "line2": null,
      "city": "Waconia",
      "state": "Minnesota",
      "postalCode": "55387"
    },
    "OwnerCreditScore": 392
  },
  "buyerMetadata": null,
  "loanDocuments": []
}