CreateSelfServiceLoanRequestCommand

Overview

Submits a fully-formed loan application on behalf of an authenticated self-service customer (or by a back-office administrator on behalf of a non-onboarded customer). This command creates the LoanQuote record, optionally records guarantor information, and fires the origination workflow events that kick off the approval chain.

Unlike CreateSelfServiceLoanQuoteCommand (used for quick, unauthenticated quote calculations), this command is the definitive loan application submission and requires a valid product configuration.

Command Structure

{
  "cmd": "CreateSelfServiceLoanRequestCommand",
  "data": {
    "productCode": "PAYROLL-01",
    "loanAmount": 500000,
    "loanPurpose": "Business expansion",
    "loanTenor": 12,
    "loanTenorType": 2,
    "referredByType": 1,
    "referralCode": "E59K6H",
    "guarantors": [
      {
        "name": "Jane Doe",
        "emailAddress": "jane.doe@example.com",
        "mobileNumber": "08012345678",
        "relationship": "Spouse",
        "address": "12 Lekki Phase 1, Lagos"
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Description
productCode	string	Yes	YAML loan product code (e.g. "PAYROLL-01"). Must match a configured product.
loanAmount	decimal	Yes	Requested loan amount.
loanPurpose	string	Yes	Purpose of the loan. Persisted on [BPMLoanSelfService].[LoanQuote].[LoanPurpose] and reused by workflow and offer-letter contexts.
loanTenor	int	Yes	Loan duration as a number (interpreted according to loanTenorType).
loanTenorType	int	Yes	Unit for loanTenor. 0 = Days, 1 = Weeks, 2 = Months, 3 = Years.
referredByType	int	No	How the customer was referred. 0 = None (default), 1 = Staff, 2 = Friend, 3 = Advert.
referralCode	string	Conditional	Staff referral code. Required when referredByType = 1. Must match an active employee record.
quoteUserId	long	Conditional	Required only for back-office creation on behalf of an unauthenticated/non-onboarded customer (when no bearer token is present).
guarantors	array	No	List of guarantor objects (see Guarantor Object below).

Guarantor Object

Field	Type	Required	Description
name	string	Yes	Full name of the guarantor.
emailAddress	string	No	Guarantor's email address.
mobileNumber	string	Yes	Guarantor's mobile number.
relationship	string	Yes	Relationship to the applicant (e.g. "Spouse", "Parent").
address	string	Yes	Guarantor's residential address.

Branch Assignment

The branch assigned to the loan quote is resolved in the following priority order:

1. Staff referral — if referredByType = 1 and the referral code maps to a valid active employee, the quote is assigned to that employee's branch.
2. User's branch association — the customer's own branch assignment (SelfServiceUserBranchAssociation).
3. System default branch — the branch flagged as IsDefaultBranch = true.

If none of the above resolves, the request is rejected with an error.

Referral Code Validation

When referredByType = 1 (Staff):

• referralCode must be provided.
• The code must match an enabled (IsEnabled = true) employee record.
• The matched employee must have a numeric branch ID set in their Branch field.
• An EmployeeReferral tracking record is created for the matched employee.

Response Structure

Success Response

{
  "ok": true,
  "statusCode": "00",
  "message": "Your loan application has been received and is currently under review.",
  "outData": {
    "loanQuoteId": 245,
    "loanAmount": 500000,
    "loanPurpose": "Business expansion",
    "quoteId": "A3F8C2D1-...",
    "productCode": "PAYROLL-01",
    "requestId": "00245PAYROLL-01157",
    "loanAmountRecommended": null
  }
}

Field	Type	Description
loanQuoteId	long	Database ID of the created loan quote. Use this for all subsequent operations.
loanAmount	decimal	Approved loan amount.
loanPurpose	string	Purpose persisted with the loan quote.
quoteId	string	Unique string reference for the quote.
productCode	string	The product code used.
requestId	string	Short, unique tracking reference in the form {productCode}-{loanQuoteId}, for example PR-2-101. Existing references are not changed.
loanAmountRecommended	decimal?	Recommended amount set by a loan officer (null at creation).

Error Responses

Scenario	statusCode	message
Product not found	08	"The selected product has not been configured"
Branch not assigned and no default	08	"You have not been assigned to a branch. Please contact your administrator"
Staff referral — missing code	08	"Referral code is required when referred by type is Staff"
Staff referral — code not found	08	"No active employee found with referral code '{code}'. Please verify the code and try again."
Staff referral — employee has no branch	08	"The referring employee (code: {code}) does not have a branch assigned. Please contact your administrator."
Quote user not found (back-office mode)	08	"The quote user does not exist..."

Notes

• The command dispatches two background workflow events on success:
  • OnChannelLoanRequestCreated — triggers the branch approval workflow. Payload includes branchId, branchCode, and organisationCode for branch-scoped routing.
  • OnLoanOriginationRequestCreated — triggers the origination/onboarding process. Payload includes branchId, branchCode, and organisationCode.
• Interest and repayment amounts are calculated server-side from the product's configured rate; the frontend does not need to supply them.
• Once created, additional KYC data (identity documents, address, credit bureau, employment info) is attached via separate commands referencing the returned loanQuoteId.