API Reference

Events

The table below contains the events that it is possible to subscribe to.

When creating a subscription, in your request JSON, use the event codes below. The notification you receive may not have all the information that is available regarding a particular status. The table below lists the related API where you can go to retrieve more detailed information.

Related APIEvent codeDescriptionFurther details
OnboardingONB10009Stage 1 submittedAll documents required for review by credit algorithms and underwriters have been submitted
OnboardingONB10010Stage 1 rejectedLead has been rejected prior to receiving an offer
OnboardingONB10011Offers providedDetailed offers have been produced for the lead (this does not include flex offers)
OnboardingONB10012Stage 2 rejectedThis event code has been deprecated
OnboardingONB10018Lead created via Organic journeyA new lead application has started
OnboardingONB10022Contract signedLead has signed the funding agreement (via DocuSign)
OnboardingONB10023Contract signedLead has signed the funding agreement (via 'click sign')
OnboardingONB10024Instant offers providedThe lead has been provided with instant offers
OnboardingONB10025Lead created via API journeyLead has been created via the Onboarding Api (create-a-lead-endpoint)
OnboardingONB10026Lead created via Broker journeyA new lead application has started via the partner dashboard
OnboardingONB10027Offers have expiredThe offers produced for the lead have now expired (threshold is 30 days)
LoansLOA10013Loan fundedLead has received funding
OnboardingONB10028Lead has been rejected with reasons providedThe lead has been rejected and the rejection reasons have been provided
OnboardingONB10029Lead requires further informationFurther information is required while processing the lead
OnboardingONB10030When a Broker has added 'additional info' to a lead application in the Broker journey in the Partner DashboardThe 'Additional Info' field has been populated for the lead in the Broker application journey on the Partner Dashboard
OnboardingONB10031A renewal lead has been createdA renewal lead has been created
LoansLOA10032Loan repaidThe merchant has repaid the full balance of the loan
LoansLOA10033Loan defaultedThe loan has defaulted due to repayment underperformance
LoansLOA10034Loan written-offThe loan has been written-off due to repayment underperformance
OnboardingONB10035Settlement account is readyA notification for when the Settlement/Repayment account details are ready to fetch from the AOL endpoint to begin the re-routing process
OnboardingONB10038Contract sent (via Docusign)The contract has been sent to the Merchant via Docusign
LoansLOA10036Loan funded (via manual process)Lead has received funding via a manual process (default in USA)
Instant SettlementINS10004The instant settlement is enabledThe instant settlement is enabled and is ready to receive and fund instant payout requests
Instant SettlementINS10005The instant settlement is disabledThe instant settlement is disabled and will not process any instant payout request
OnboardingONB10039The application has been made 'Ineligible' or has been 'Rescinded'The Lead has been made Ineligible and will not be processed further or the Merchant has Rescinded their application
LoansLOA10040Payment made to advanceA repayment has been applied
LoansLOA10041Reversal from advanceA previous payment has been reversed
LoansLOA10042Refund from advanceA refund has been applied
LoansLOA10043Refund reversal to advanceA previous refund has been reversed
LoansLOA10045Funding bounce-backThe payment for funding bounced back from the intended bank account
LoansLOA10046Loan discounted settlementA discounted repayment amount has been finalised for this loan
LoansLOA10047Loan in CollectionThe merchant has entered YouLend's Collections process
LoansLOA10048Loan out of CollectionThe merchant has been taken out of YouLend's Collections process
LoansONB10049Open banking link sentA broker has requested an email containing an open banking link to be sent to their merchant
OnboardingONB10050Pushback resolvedThe required information for a lead is resolved
OnboardingONB10051Stage 1 submitted via APIThe lead has been successfully submitted via API
LoansLOA10055Settlement processedA settlement from a partner has been processed - payments towards the loan have been initiated

👋

Please get in touch

If you would like any new events added, please get in touch at [email protected] with the required use case, and we will usually be able to add support for the new event.

All webhook events

Event data structure

All events share the following basic structure:

{
    "EventCode": "ONB10959",
    "Message": "Example message...",
    "EventProperties": {
    	"LeadId": "f3c23809-9850-4546-bd08-650068aa55f6"
     }
}

Lead submitted

{
  "LeadId": "233860ba-1d2a-4689-8234-a4af8bae877d",
  "ThirdPartyCustomerId": "tpci1234"
}

📘

Good to know

Some events - e.g. 'Offers provided' and 'Loan funded' - have additional EventProperties as shown in the two examples below.

Offers provided

{
    "EventCode": "ONB10011",
    "Message": "Offers Provided",
    "EventProperties": {
  "LeadId": "a668561b-4998-4240-a647-a35df722ca42",
  "ThirdPartyCustomerId": "rndtkezrrxq",
  "MaxFundingAmount": 38900,
  "MinFundingAmount": 7710,
  "Offers": [
    {
      "OfferId": "f29d76d6-2cda-431e-bde9-a231260a1899",
      "YouWillGet": "30800",
      "YouWillRepay": "36960",
      "CurrencyISOCode": "GBP",
      "Sweep": "20",
      "DaysUntilRepayment": 207
    },
    {
      "OfferId": "23b182e4-6039-4117-b715-28b60b30154b",
      "YouWillGet": "34800",
      "YouWillRepay": "42456",
      "CurrencyISOCode": "GBP",
      "Sweep": "21",
      "DaysUntilRepayment": 227
    },
    {
      "OfferId": "c477dddd-8acc-4757-ac5f-aeca15606862",
      "YouWillGet": "38900",
      "YouWillRepay": "48236",
      "CurrencyISOCode": "GBP",
      "Sweep": "22",
      "DaysUntilRepayment": 246
    }
  ]
}

Offers expired

{
    "EventCode": "ONB10027",
    "Message": "Offers have expired",
    "EventProperties": {
  			"LeadId": "24df18ae-6462-4671-b72a-1d90fa195ac2",
  			"ThirdPartyCustomerId": "TPM102175"
     }
}

Contract signed (ONB10022 AND ONB10023)

{
  "EventCode": "ONB10022",
  "Message": "Contract Signed",
  "EventProperties": {
    "LeadId": "f4bddb67-b259-438e-9ab4-ad35cf6a1b29",
    "DocumentSigningId": "234b619b-1d48-47b1-ab7c-4b3b25881f99",
    "ThirdPartyCustomerId": "89ab144",
    "SignedDocuments": [
      {
        "DocumentId": "49a47f74-e884-4a96-80d4-5593f57cff1e",
        "DocumentType": "application/pdf"
      },
      {
        "DocumentId": "4ccc4e8e-608e-447b-a4d9-f534b39cbd63",
        "DocumentType": "application/pdf"
      }
    ]
  }
}

Loan funded (LOA10013 and LOA10036)

📘

Good to know

LOA10036 is primarily used in the USA to indicate that the loan has been manually marked as funded

{
  "EventCode": "LOA10013",
  "Message": "Lead has received funding",
  "EventProperties": {
    "ThirdPartyCustomerId": "89ab144",
    "Amount": "38800.00",
    "LeadId": "f4bddb67-b259-438e-9ab4-ad35cf6a1b29",
    "DateFunded": "2024-12-03T00:00:00Z",
    "OriginalAmount": "51992.0",
    "LoanId": "2d3b03ed-24bc-4228-adc8-eeb14883ef24",
    "Sweep": "20.0",
    "LoanNumber": 60000280,
    "FastTrackLeadId": "00000000-0000-0000-0000-000000000000"
  }
}

Lead created via API journey

The EventProperties object has the same structure for the events with code ONB10018, ONB10025 and ONB10026

{
    "EventCode": "ONB10025",
    "Message": "Lead created via API journey",
    "EventProperties": {
        "LeadId": "f926dfc2-30b6-4721-89c7-2a3f21dda380",
        "OrganisationSignUpData": {
            "CompanyName": "Test Lead",
            "AdditionalInfo": {
                "additionalProp1": "test",
                "additionalProp2": "test1",
                "additionalProp3": "test2"
            },
            "ThirdPartyCustomerId": "testTPCI"
        }
    }
}

Lead has been rejected with reasons provided

{
    "EventCode": "ONB10028",
    "Message": "Lead has been rejected with reasons provided",
    "EventProperties": {
  "LeadId": "11b5da66-7eaa-4bed-ba2c-dad05d5602a0",
  "ThirdPartyCustomerId": "acct_1JIWqFFcrksnBl3t",
  "CreditRiskCheckRejectedPartnerReasons": [
    {
      "Reason": "CCJs/Defaults found during Credit check",
      "ReasonCode": "RJ005"
    },
    {
      "Reason": "Credit check criteria not met",
      "ReasonCode": "RJ007"
    }
  ]
}
}

Lead requires further information

{
    "EventCode": "ONB10029",
    "Message": "Lead requires further information",
    "EventProperties": {
        "LeadId": "39735dbf-9a0e-4d3c-81ad-248f14abf7f8",
        "ThirdPartyCustomerId": "testTPCI",
        "CreditRiskCheckPendingReasons": [
            {
                "Reason": "Proof of ID",
                "AdditionalInfo": "some more details here",
                "ReasonCode": "PB001"
            },
            {
                "Reason": "Provide clarification of fluctuations in transaction data",
                "AdditionalInfo": "some more info here",
                "ReasonCode": "PB004"
            }
        ]
    }
}

A renewal lead has been created

{
    "EventCode": "ONB10031",
    "Message": "A renewal lead has been created",
    "EventProperties": {
        "LeadId": "f926dfc2-30b6-4721-89c7-2a3f21dda380",
        "IsRenewal": true,
        "ThirdPartyCustomerId": "testTPCI"
    }
}

When the merchant has repaid the full balance of the loan

{
    "EventCode": "LOA10032",
    "Message": "The merchant has repaid the loan",
    "EventProperties": {
        "LoanId": "f926rfc2-30b6-4821-89c7-2a3f11dda380",
        "LeadId": "f926dgc2-30r6-4721-89c7-2a3f21dfa380"
    }
}

The loan has defaulted due to repayment underperformance

{
    "EventCode": "LOA10033",
    "Message": "The loan has defaulted and is now in our recoveries process",
    "EventProperties": {
        "LoanId": "f926rfc2-30b6-4821-89c7-2a3f11dda380",
        "LeadId": "f926dgc2-30r6-4721-89c7-2a3f21dfa380"
    }
}

The loan has been written-off due to repayment underperformance

{
    "EventCode": "LOA10034",
    "Message": "The loan has been written-off",
    "EventProperties": {
        "LoanId": "f926rfc2-30b6-4821-89c7-2a3f11dda380",
        "LeadId": "f926dgc2-30r6-4721-89c7-2a3f21dfa380"
    }
}

The Settlement/Repayment account details are ready to fetch from the AOL endpoint to begin the re-routing process

{
    "EventCode": "ONB10035",
    "Message": "The Settlement/Repayment account details are ready to fetch from the AOL endpoint to begin the re-routing process",
    "EventProperties": {
        "LeadId": "f926dgc2-30r6-4721-89c7-2a3f21dfa380"
    }
}

The instant settlement is disabled

{
    "EventCode": "INS10005",
    "Message": "Instant Settlement has been disabled",
    "EventProperties": {
        "InstantSettlementNumber": 30000000
    }
}

The instant settlement is enabled

{
    "EventCode": "INS10004",
    "Message": "Instant Settlement has been enabled",
    "EventProperties": {
        "InstantSettlementNumber": 30000000
    }
}

Contract sent

{
   "EventCode": "ONB10038",
   "EventProperties": {
       "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04",
   },
   "Message": "Contract has been sent to Merchant via Docusign"
}

The application has been made 'Ineligible' or has been 'Rescinded'

{
  "EventCode": "ONB10039",
  "Message": "The application has been made 'Ineligible' or 'Rescinded' (see properties for more detail)",
  "EventProperties": {
    "ThirdPartyCustomerId": "89ab144",
    "LeadState": "ineligible",
    "LeadId": "08a826ae-8065-4f2d-97b2-455cf65505ef",
    "LeadStateReasons": [
      {
        "Reason": "Insufficient days of PD provided",
        "AdditionalInfo": "The customer only provided 1 week of data",
        "ReasonCode": "EL009",
        "PartnerReason": "The customer has not provided enough payment data (minimum 3 months)"
      }
    ]
  }
}

Payment made to advance

{
    "EventCode": "LOA10040",
    "EventProperties": {
        "LeadId": "113222a1-1a89-4ef0-bda3-bad07224fe11",
        "LoanId": "d90c9fc1-cdd0-4dfc-810a-e2bab1f76199",
        "PaymentAmount": "10.00",
        "PaymentDate": "2023-10-20T00:00:00Z",
        "PrincipalRemaining": "9880.40"
    },
    "Message": "A repayment was made towards the loan"
}

Reversal from advance

{
    "EventCode": "LOA10041",
    "EventProperties": {
        "Amount": "10.00",
        "LeadId": "113222a1-1a89-4ef0-bda3-bad07224fe11",
        "LoanId": "d90c9fc1-cdd0-4dfc-810a-e2bab1f76199",
        "PaymentDate": "2023-10-20T00:00:00Z",
        "PrinciplaRemaining": "9890.40"
    },
    "Message": "A previously made payment towards a loan was reversed "
}

Refund from advance

	{
	    "EventCode": "LOA10042",
	    "EventProperties": {
	        "Amount": "10.00",
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04",
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0"
	    },
	    "Message": "A Refund was triggered for this loan"
}

Refund reversal for advance

	{
	    "EventCode": "LOA10043",
	    "EventProperties": {
	        "Amount": "10.00",
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04",
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0"
	    },
	    "Message": "A Refund was reversed for this loan"
}

Funding bounce-back

	{
	    "EventCode": "LOA10045",
	    "EventProperties": {
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04",
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0"
	    },
	    "Message": "The payment for funding bounced back from the intended bank account"
}

Loan discounted settlement

	{
	    "EventCode": "LOA10046",
	    "EventProperties": {
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0",
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04"
	    },
	    "Message": "The merchant has entered YouLend's Collections process"
}

Loan in Collections

	{
	    "EventCode": "LOA10047",
	    "EventProperties": {
	        "ThirdPartyCustomerId": "testTPCI",
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0",
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04"
	    },
	    "Message": "The merchant has entered YouLend's Collections process"
}

Loan out of Collections

	{
	    "EventCode": "LOA10048",
	    "EventProperties": {
	        "ThirdPartyCustomerId": "testTPCI",
	        "LoanId": "ca49c513-5d42-48bb-a043-c4e1885bf6f0",
	        "LeadId": "2bee7a34-6308-4ad3-b133-c70444415a04"
	    },
	    "Message": "The merchant has been taken out of YouLend's Collections process "
}

Pushback Resolved

	{
	    "EventCode": "ONB10050",
	    "EventProperties": {
				  "LeadId": "32961911-43e7-4bf2-94e0-0bd49adc0fe4",
				  "CreditRiskCheckReasonExtended": {
  					  "AdditionalInfo": "",
  					  "ReasonCode": "PB001",
  					  "IsResolved": true}
				}
  	}

Stage 1 submitted via API

{
  "EventCode": "ONB10051",
  "Message": "The lead has been successfully submitted via API",
  "EventProperties": {
    "ThirdPartyCustomerId": "89ab144",
    "LeadId": "874b3183-640a-4fa5-bf49-2e2f063f5ec8"
  }
}

Settlement Processed

{
	    "EventCode": "LOA10055",
	    "EventProperties": {
			"EventId": "84e40730-eb8f-4da9-be3f-c17085769273", 
	    "LoanId": "d90c9fc1-cdd0-4dfc-810a-e2bab1f76199",
	    "TotalSettlementAmount" : 300, // amount received in YouLend virtual account
			"SettlementReference": "payment reference",
			"PaymentsToLenders" : [  // list of payments YouLend will send to relevant lenders for the loan
              {
                  "Amount" : 200,
                  "PaymentCorrelationId" : "69dd8b8e-8c20-482f-9e53-050d0106794f"
              },
              {
                  "Amount" : 100,
                  "PaymentCorrelationId" : "2d059058-f549-4d93-b7fd-322ddc6300cb"
              } 
             ]
	    },
	    "Message": "A settlement from a partner has been processed - payments towards the loan have been initiated"
}