API Reference

Introduction to Loans API

The Loans API allows partners to receive information about live and past merchant funding agreements with YouLend.

This API can send you a wide range of information, including how many agreements a merchant has, how fast a particular agreement is being repaid, and how much is outstanding.

Partners can use this in multiple ways, for example:

  • Surface in the partner's native application environment, creating a single view where merchants can manage their funding alongside other products
  • Integrate into the workflow for the partner's customer support team so they can better serve your merchants when they interact
  • This data can be used by the partner in their reporting

🚧

Be aware

Make sure to use the v2 of the Loans API. To ensure you get this version, provide the version number as api-version in the header of your request. For example:api-version: 2

Common endpoints

YouLend partners typically use the below endpoints when starting to interact with the Loans API.

1. List all loans (with optional filtering applied)

Fetch all of the advances available. This request has no body, instead send a GET call to the endpoint. The response will return loanIDs (id parameter).

Response example

[
    {
        "owner": null,
        "thirdPartyCustomerId": "89ab144",
        "additionalInfo": {
            "language": "en",
            "Lead source": "email",
            "youLendSales": "true"
        },
        "leadId": "a3f95fa5-bcf7-4e1c-a1c3-ad92f829e05a",
        "id": "3a149e37-4c12-4832-be03-af041a051bbc",
        "loanNumber": 60000272,
        "borrowerName": "Test Company Limited",
        "currentAmount": 21896.0,
        "loanType": "Initial",
        "status": "Funded (Multisell failed)",
        "maturityDate": "2025-07-10T00:00:00Z",
        "sweep": 20.0,
        "autoRepaymentSweep": true,
        "currencyISOCode": "GBP",
        "currentAmountAtRepay": 0.0,
        "currentAmountAtDelete": 0.0,
        "currentAmountAtWriteOff": 0,
        "merchantIds": [
            ""
        ],
        "creditRating": "E",
        "fundingDate": "2024-11-22T00:00:00Z",
        "fundedAmount": 16100.0,
        "originalAmount": 21896.0,
        "aheadBehindValue": 0,
        "aheadBehindPercentage": 0
    }
]

📘

Good to know

For larger portfolios, a partner can use filtering in the request to only return one cohort of advances at a time, this can be achieved using the loanState field. A partner can also filter by dates

2. Retrieve a loan by loan Id

Fetch data about an advance. This request has no body, instead send a GET call to the endpoint.

Response example

{
    "autoRepaymentSweep": true,
    "borrowerId": "6ecd7da8-914b-4d39-a013-111350844659",
    "borrowerName": "Test Company Limited",
    "currencyISOCode": "GBP",
    "currentAmount": 172360.0,
    "currentServiceChargeRate": 0.0,
    "defaultDetails": null,
    "discount": 19.354838709677423,
    "id": "cfc1147e-b69e-4262-a0ed-9785bc453dff",
    "approvalDate": "0001-01-01T00:00:00",
    "maturityDate": "2025-09-24T00:00:00Z",
    "originalAmount": 172360.0,
    "originalServiceChargeRate": 0.0,
    "projectedRepaymentDate": "2025-06-11T00:00:00Z",
    "securityAndGuarantees": false,
    "loanType": "Initial",
    "status": "Funded",
    "sweep": 23.0,
    "loanNumber": 60000239,
    "creditRating": "B-",
    "earlyRenewalDetails": {
        "oldLoanId": "00000000-0000-0000-0000-000000000000",
        "oldLoanNumber": 0,
        "isOldLoanRepaid": false,
        "newLoanId": "00000000-0000-0000-0000-000000000000",
        "newLoanNumber": 0
    },
    "fundingDetails": {
        "fundingAmount": 139000.0,
        "fundingDate": "2024-11-13T00:00:00Z",
        "fundingPayments": [
            {
                "paymentDate": "2024-11-13T00:00:00Z",
                "paymentAmount": 139000.0
            }
        ],
        "amountFunded": 139000.0
    },
    "writeOffDetails": null,
    "thirdPartyReferences": [],
    "documents": [
        {
            "document": {
                "documentId": "5bf20245-54b5-4cc6-9503-15b2626f4a23",
                "documentName": "Test Company Limited - YouLend Advance Loan Agreement.pdf",
                "documentType": "application/pdf",
                "dateUploaded": "2024-11-13T14:49:11.507Z"
            },
            "documentType": "Loan Agreement"
        }
    ]
}

3. List repayment information for a loan

This endpoint provides detailed repayment history for an advance. This request has no body, instead send a GET call to the endpoint.

Response example

[
    {
        "paymentDate": "2024-12-15T00:00:00Z",
        "totalCardTransactions": 0.0,
        "sweep": 0.0,
        "repaymentAmount": 0.0,
        "loanBalance": 38564.0,
        "payments": []
    },
    {
        "paymentDate": "2024-12-17T00:00:00Z",
        "totalCardTransactions": 0.0,
        "sweep": 0.0,
        "repaymentAmount": 800.00,
        "loanBalance": 37764.00,
        "payments": [
            800.00
        ]
    }
]

👍

Best practice

We would recommend viewing our Lead & Loan States guide to learn more about each state that a loan can transition through