Copy of Building Reports

Leads and Funnel Data

Using this endpoint, you can retrieve a maximum of 500 submitted leads and their statuses. This is useful for building funnel reports (e.g. how many leads progressed to each stage). You can filter leads by submission date and by status to focus on a particular time period or funnel stage. The data also indicates whether each application is an initial funding or a renewal, which helps in segmenting new vs. repeat customers in your reporting. Key data points available for each lead include:

Lead ID and Details: Unique identifier for the lead (application) and associated merchant info (e.g. business name).
Lead Status: The current stage of the lead in the application funnel. For example, statuses like stage1submitted, offersProvided, contractsigned, readytofund, etc. can be used to count how many leads are at each stage of the process. This supports funnel conversion metrics (e.g. leads submitted → offers made → offers accepted → funded).
Initial vs. Renewal Indicator: A flag denoting if the application is a new (Initial) cash advance or a Renewal(repeat funding for an existing merchant). This is provided in the partnerLoanType field (possible values include "Initial", "Renewal", or "Early Renewal"). Segmenting by this field lets you report on new vs. returning business.

Example - Retrieving Leads

Suppose you want to fetch all leads created in January 2025 to analyze conversion rates. You could call the leads endpoint with a date filter. The response will return a list of lead records. For example:

[
  {
    "leadId": "i9j0k1l2-3456-7890-ijkl-123456789012",
    "thirdPartyCustomerId": "CUST_2024_005",
    "preApprovalId": "j0k1l2m3-4567-8901-jklm-234567890123",
    "state": "offersProvided",
    "stateUpdated": "2025-01-10T09:15:42.156Z",
    "signUpDate": "2025-01-03T16:22:08.334Z",
    "additionalInfo": {
      "additionalProp": "string"
    },
    "companyName": "BuildRight Construction Co.",
    "name": "Robert Anderson",
    "owner": "Robert Anderson",
    "leadType": "business",
    "partnerLoanType": "Initial",
    "ownerEmail": "[email protected]",
    "country": "United Kingdom",
    "countryISOCode": "GBR",
    "email": "[email protected]",
    "comments": [
      {
        "additionalProp": "string"
      }
    ],
    "companyType": "Ltd",
    "rejectionReasons": []
  },
  {
    "leadId": "a1b2c3d4-5678-9012-abcd-987654321000",
    "thirdPartyCustomerId": "CUST_2024_005",
    "preApprovalId": "z9y8x7w6-5432-1098-zyxw-876543210999",
    "state": "contractsigned",
    "stateUpdated": "2025-01-22T11:48:30.000Z",
    "signUpDate": "2025-01-20T10:05:12.100Z",
    "additionalInfo": {
      "additionalProp": "string"
    },
    "companyName": "BuildRight Construction Co.",
    "name": "Robert Anderson",
    "owner": "Robert Anderson",
    "leadType": "business",
    "partnerLoanType": "Renewal",
    "ownerEmail": "[email protected]",
    "country": "United Kingdom",
    "countryISOCode": "GBR",
    "email": "[email protected]",
    "comments": [
      {
        "additionalProp": "string"
      }
    ],
    "companyType": "Ltd",
    "rejectionReasons": []
  }
]

In the above example, we see two leads: one initial funding (status shows an offer was provided) and one renewal (status shows the contract has been signed). You could count how many leads reached each status in January, and how many were renewals vs initial, to build a funnel conversion report.

Loans and Funding Data

Endpoint: List Loans with filtering (Loans API v2)

This endpoint provides details on all cash advances associated with your partner account. It is the primary source for reporting on funded volume and portfolio composition. You can retrieve all loans and also apply filters (for example, by funded date range or by loan status) to narrow results. Key data points available for each loan include:

Loan Identification: Each loan (advance) has a unique loanId and a human-readable loan number. You also get the associated leadId (to link back to the application) and borrower details (e.g. business name).
Funded Amount: The amount of money disbursed to the merchant for this advance. This represents the principal that the merchant received.
Original Amount (Total to Repay): The total amount the merchant must repay, which includes the funded amount plus fees. In other words, Original Amount = Funded Amount + YouLend’s fees. This breakdown allows you to derive the financing cost. For example, if a loan’s funded amount is £16,100 and the original amount is £21,896, the difference (£5,796) is the total fee/commission on that advance. Partners can use this to calculate their commission or revenue share if applicable (based on how the fee is split).
Loan Status (State): The current state of the loan. Common values include Funded (active), Repaid (fully repaid), Defaulted, Written Off, etc. This lets you filter or categorize loans in reporting (for instance, counting how many advances are active vs. completed).
Term and Dates: Information about the expected term or duration of the advance. The data includes timestamps like the funding date and a maturity date (expected end date of the financing). From these, you can infer the term length (e.g. an advance funded on 2024-11-22 with a maturity date of 2025-07-10 has an expected term of about 8 months). Tracking term lengths can help in analyzing the average duration of advances in your portfolio.
Repayment Method & Frequency: Indicators of how the loan is being repaid. For example, whether repayments are collected via automatic daily sweeps from the merchant’s sales or via fixed daily debits. The API provides fields such as sweep (the percentage of sales being collected, if applicable) and flags like autoRepaymentSweep. You can deduce the repayment frequency (YouLend cash advances are typically repaid daily on business days). This information is useful to ensure your reporting or reconciliation systems account for how and when payments are expected for each loan (e.g. daily vs weekly collections).
Fee and Cost Breakdown: In addition to the funded/original amount, you can retrieve any fee-related fields (if provided by a more detailed loan endpoint or in the loan object). These might include origination fees or other cost components. Even if explicit fee fields are not directly given in the list response, the difference between original and funded amount represents the total cost of financing to the merchant. As mentioned, that difference can be used to derive your commission if, for example, your agreement is to earn a portion of the fee.

Example - Funded Loans Data:

An example response for the loans endpoint might look like this:

[
  {
    "owner": "Robert Anderson",
    "thirdPartyCustomerId": "CUST_2024_005",
    "additionalInfo": {
      "additionalProp": "string"
    },
    "leadId": "i9j0k1l2-3456-7890-ijkl-123456789012",
    "countryISOCode": "GBR",
    "email": "[email protected]",
    "repaymentMethod": "SBR",
    "repaymentFrequency": "",
    "expectedRepayment": 21896,
    "id": "8b7c2e91-9f4a-4e3a-9a6f-1c9b9d4f1234",
    "loanNumber": 6102345,
    "borrowerName": "BuildRight Construction Co.",
    "currentAmount": 21896,
    "loanType": "Initial",
    "partnerLoanType": "Initial",
    "status": "Funded",
    "maturityDate": "2025-07-10T00:00:00.000Z",
    "sweep": 20.0,
    "autoRepaymentSweep": true,
    "currencyISOCode": "GBP",
    "currentAmountAtRepay": 0,
    "currentAmountAtDelete": 0,
    "currentAmountAtWriteOff": 0,
    "merchantIds": [
      "MERCHANT_001"
    ],
    "creditRating": "B",
    "fundingDate": "2024-11-22T10:15:00.000Z",
    "fundedAmount": 16100,
    "originalAmount": 21896,
    "aheadBehindValue": 0,
    "aheadBehindPercentage": 0
  }
]

In this example, the loan was an Initial advance that was Funded on 22 Nov 2024. The merchant received £16,100(fundedAmount) and will repay £21,896 in total (originalAmount). The difference of £5,796 is the fee. The loan’s status is currently “Funded” (active). The currentAmount of 21,896 indicates the outstanding balance at the time of retrieval (initially equal to the original amount before any repayments). The data also shows sweep: 20.0 with autoRepaymentSweep: true, meaning this loan is set up with a 20% daily sales sweep for repayments (automatically collected). The expected end of the loan (maturityDate) is July 10, 2025. You could use this data to report on total funded volume, number of loans funded in a period, average loan size, fee revenue, and to identify how many loans are active or completed, etc.

📘
Good To Know
repaymentFrequency can be null when the repayment method isn’t Direct Debit/VRP, and expectedRepaymentmay be 0 in that case—so don’t assume it’s always meaningful for every loan.

Repayments Data

Endpoint: List Repayments for a Loan

This endpoint provides the detailed repayment history for each loan. It is essential for tracking how much has been repaid and what is outstanding, which is useful for both performance tracking and reconciliation purposes. For any given loan (identified by loan ID), you can retrieve all repayment entries (usually on a daily basis, or each time a payment was recorded). Key data points from this endpoint include:

Total Amount Repaid to Date: This can be derived by summing all repayment transactions or by looking at the difference between the original amount and the current outstanding balance. The endpoint doesn’t necessarily provide a pre-summed total, but you can calculate it.
Outstanding Balance: The remaining balance yet to be repaid on the loan. Each repayment record typically shows the balance after that payment. The latest entry in the repayment history will show the up-to-date outstanding balance.
Daily Repayment Amounts: Each entry in the repayment history includes the amount repaid for that day (or transaction) and the date. This allows you to see the cash flow of repayments. If payments are collected daily, you’ll see an entry for each business day (or each day a payment was made) with the amount. If no payment was made on a particular day (e.g., weekends or holidays if not collecting), that might show as 0 or there may simply be no entry for those dates.

📘
Good To Know
Alternatively, if the latest entry provides a running total or you have the original and current balance, those can be used to compute total repaid as well.
The loans list endpoint’s currentAmount field also reflects the current outstanding balance for the loan as of retrieval time. Using the repayment history gives you a chronological view of how that balance decreases over time.

By analyzing the repayment data, you can report on things like the pace of repayment (e.g., how quickly merchants are paying back) and perform daily reconciliation of payments received.

Example - Repayment History

For a given loan, the repayments endpoint returns a list of repayment entries (each entry shows the date, how much was collected, and the remaining balance). For example:

[
  {
    "paymentDate": "2024-11-23T00:00:00Z",
    "repaymentAmount": 800.0,
    "loanBalance": 21096.0,
    "payments": null
  },
  {
    "paymentDate": "2024-11-24T00:00:00Z",
    "repaymentAmount": 1000.0,
    "loanBalance": 20096.0,
    "payments": null
  },
  {
    "paymentDate": "2024-11-25T00:00:00Z",
    "repaymentAmount": 0.0,
    "loanBalance": 20096.0,
    "payments": null
  }
  // ... subsequent entries ...
]

In this example, assume the loan’s original amount (total to repay) was £21,896. On 23 Nov, a repayment of £800 was recorded, reducing the balance to £21,096. On 24 Nov, £1,000 was recorded, reducing the balance to £20,096. On 25 Nov, no repayment was recorded (or a zero-amount entry is present), so the balance remains £20,096. Each object represents a repayment record. You can use it to:

Sum repaymentAmount over a period to calculate repayments received in that window.
Track performance over time by observing how loanBalance decreases.
Support reconciliation by comparing repayment amounts to the funds you receive/transfer for that period.

📘
Good To Know

Avoid relying on fields such as totalCardTransactions and sweep for reporting—they appear in some examples but are deprecated in the repayments response. For reporting and reconciliation, treat repaymentAmount and loanBalance as the stable, primary fields.

Merchants only repay one financing at a time. If an Early Renewal is funded while an existing financing is still outstanding, repayments will continue to be applied to the existing financing until it’s fully repaid, so the early renewal may show little or no repayment activity during that period.

Summary

By leveraging the above endpoints, you can construct a comprehensive reporting suite for your YouLend cash advance program. Lead data gives insight into your application funnel and conversion rates, loan/funding data provides information on volumes, terms, and commissions, and repayment data allows monitoring of performance and ensuring that repayments are on track.

Integrating these APIs into your BI system or data warehouse means your sales team can track KPIs like total funded amount, average fees, and funnel conversion, while your finance team can easily reconcile payments and outstanding balances. This direct integration eliminates the need for manual data exports and keeps everyone informed with real-time data.