Building Reports

Leads and Funnel Data

Endpoint: List Leads with Filtering

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.

Repayment Tracking via Webhooks

For tracking repayments, we recommend using webhooks rather than polling the API. Webhooks provide real-time notifications when repayment events occur, giving your finance and reconciliation teams immediate visibility into payment activity across your portfolio.

Subscribe to repayment webhooks to receive updates on:

• Daily repayment amounts — Get notified each time a payment is collected from a merchant
• Loan fully repaid — Receive confirmation when a merchant has completed all repayments (event code LOA10032)
• Missed or delayed payments — Get alerted when expected payments are not received

This approach eliminates the need for batch polling and ensures your reporting dashboards and reconciliation systems stay up to date in real time.

📘

Good To Know

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.