18.2 LOS calls and operations

This page enumerates every meaningful operation in the LOS with what it does, what it validates, what it depends on, what side effects it has. The goal: an engineer / auditor can trace any application’s lifecycle precisely.

Operations grouped by phase

Phase A — Lead and pre-application

Op 1: lead.create

• Input: { mobile, pan?, gstin?, channel, utm }
• Validations: mobile format; PAN format if present; channel exists.
• Side effects:
  • Dedup check on mobile / PAN.
  • Velocity check (channel / device).
  • Internal blacklist check.
  • Creates lead row.
  • Attribution recorded.
• Audit: lead.created event.
• Returns: lead_id.

Op 2: lead.qualify

• Input: { lead_id }
• Internal: sales / DSA / CA action.
• Side effects: lead.status = qualified.
• Returns: void.

Op 3: pre_eligibility.check

• Input: { pan, mobile, gstin, loan_amount_sought, channel, consent }
• Operations:
  • GSTIN status check (vendor call: Karza / Signzy / GSP).
  • NIC code lookup against negative list.
  • Geography check.
  • Internal blacklist + velocity check.
  • Soft bureau pull (vendor call) if consent + supported.
• Returns: { verdict, indicative_offer? }.
• Cost: ~₹10 – ₹25 per check.

Phase B — Application capture

Op 4: application.create

• Input: { borrower_id?, lead_id?, loan_product_id, loan_amount_sought, tenure_sought, purpose_code }
• Validations: product exists; amount within product min/max; tenure within product range.
• Side effects:
  • Creates application row in DRAFT.
  • Initialises BFF session.
• Returns: application_id.

Op 5: application.update_section

• Input: { application_id, section_name, data_json }
• Sections: business_profile, promoter_details, beneficial_owners, loan_requirement, existing_debt, bank_accounts, collateral, etc.
• Side effects:
  • Saves application_section_data.
  • Per-section validation (per-section schema).
• Returns: { saved_at, validation_errors? }.

Op 6: application.add_promoter

• Input: { application_id, promoter_data }
• Validations: PAN format; mobile unique among promoters (typically).
• Side effects: creates promoter row linked to business_entity.

Op 7: application.add_beneficial_owner

• Input: { application_id, bo_data, parent_bo_id? }
• Validations: ownership_pct sum check (across BOs).
• Side effects: creates beneficial_owner row; recurses for multi-tier.

Op 8: consent.capture

• Input: { borrower_id, purpose, data_categories, version_of_policy, vendor?, vendor_consent_ref? }
• Validations: purpose in allowed list.
• Side effects:
  • Creates consent row with timestamp, IP, device.
  • Audited.
• Returns: consent_id.

Op 9: document.upload

• Input: { application_id, type, file_multipart }
• Validations: file type allowed; file size within limit.
• Side effects:
  • Stores file in S3 with versioning.
  • Creates document row with hash + URI.
• Returns: document_id.

Op 10: application.submit

• Input: { application_id }
• Validations:
  • All required sections complete.
  • All required documents uploaded.
  • All required consents captured.
  • Loan amount within sanctioned product range.
• Side effects:
  • State → SUBMITTED.
  • Triggers KYC + ingestion orchestration.
• Returns: { status, expected_decision_at }.

Phase C — KYC and KYB

Op 11: kyc.individual.initiate

• Input: { promoter_id, method } (method: vcip / aadhaar_offline / digilocker)
• Operations:
  • Per method, invoke vendor adapter.
  • For V-CIP: schedule session, return session URL.
  • For Aadhaar offline: prompt borrower to upload zip + share-code.
• Returns: { session_id? }.

Op 12: pan.verify

• Input: { pan, name, dob }
• Vendor: NSDL / Karza / Signzy.
• Returns: { status, name_match_score }.

Op 13: aadhaar_offline.verify

• Input: { promoter_id, zip_url, share_code }
• Operations: verify signature; extract fields.
• Returns: { status, masked_aadhaar, fields }.

Op 14: vcip.complete (webhook from vendor)

• Input: vendor webhook payload.
• Side effects:
  • Update vcip_session row.
  • Trigger downstream kyc.individual.completed event.
• Returns: ack.

Op 15: sanctions.screen

• Input: { subject_type, subject_id, name, dob?, address? }
• Vendor: AML Watcher / World-Check.
• Returns: { screen_id, hits[] }.

Op 16: kyb.gstin.verify

• Input: { gstin }
• Vendor: Karza / Signzy / GSP.
• Returns: { status, legal_name, address, registration_date, taxpayer_type }.

Op 17: kyb.mca.fetch

• Input: { cin_or_llpin }
• Vendor: Karza / Probe42.
• Returns: { status, directors, last_filing_date, shareholding }.

Op 18: ckyc.search

• Input: { pan?, aadhaar?, mobile? }
• Vendor: Karza / Signzy CKYC connector.
• Returns: { kin? }.

Op 19: ckyc.upload

• Input: standardised CKYC payload.
• Side effects: uploads to CKYCR; updates kyc_record.
• Returns: { kin }.

Op 20: bank_account.penny_drop

• Input: { account_number, ifsc, claimed_name }
• Vendor: Razorpay / Cashfree / Setu.
• Returns: { verified, returned_name, name_match_score }.

Phase D — Data ingestion

Op 21: data.aa.consent_request

• Input: { borrower_id, purpose, fi_types, date_range, frequency, validity }
• Vendor: AA TSP (Setu / FinBox).
• Returns: { consent_handle, redirect_url }.

Op 22: data.aa.fetch

• Input: { consent_handle }
• Vendor: AA TSP.
• Operations: async fetch; data returned via webhook.
• Returns: { fetch_id, status: "in_progress" }.

Op 23: data.aa.webhook.received

• Input: vendor webhook with encrypted data.
• Operations: decrypt; normalise into bank_statement table.
• Side effects: emit data.bank_statement.parsed event.

Op 24: data.bank_statement.upload

• Input: PDF file + password.
• Vendor: Perfios / FinBox.
• Operations: async parse; emit event on completion.
• Returns: { pull_id, status }.

Op 25: data.gst.initiate

• Input: { gstin, periods }
• Vendor: GSP (Cygnet / Webtel).
• Operations: triggers OTP to borrower’s GST-registered mobile.
• Returns: { session_id, otp_required: true }.

Op 26: data.gst.otp_submit

• Input: { session_id, otp }
• Vendor: GSP.
• Operations: triggers actual fetch.
• Returns: { fetch_id, status }.

Op 27: data.gst.webhook.received

• Input: GSP returns parsed returns.
• Side effects: store in gst_report; emit event.

Op 28: data.bureau.pull

• Input: { subject_type, subject_id, cic, report_type }
• Vendor: CIC direct or aggregator.
• Returns: { bureau_report_id, score, parsed_uri }.

Op 29: data.mca.fetch

• Input: { cin_or_llpin }
• Vendor: Karza / Probe42.
• Returns: parsed MCA snapshot.

Op 30: data.tally.upload

• Input: Tally backup file.
• Vendor: Karza Tally connector.
• Operations: async parse.
• Returns: { pull_id, status }.

Phase E — Decisioning

Op 31: decision.engine.run

• Input: { application_id, policy_id? } (policy auto-selected if omitted)
• Operations:
  • Snapshot inputs (all ingested data).
  • Load policy version.
  • Execute rules in order.
  • Execute scorecards.
  • Apply segment overlay.
  • Compute recommendation.
• Returns: { decision_run_id, decision, grade, recommended }.
• Audit: full trace stored in decision_run.trace_uri.

Op 32: decision.refer

• Input: { decision_run_id, reasons }
• Side effects: case routed to manual review queue.

Op 33: case.assign

• Input: { case_id, analyst_id }
• Side effects: case assigned; analyst’s queue updated.

Op 34: case.query

• Input: { case_id, query_text, addressed_to }
• Side effects:
  • Query sent to borrower / DSA / RM via SMS / email.
  • Case marked awaiting_response.

Op 35: case.recommend

• Input: { case_id, recommendation, deviation_requested? }
• Side effects: analyst’s recommendation captured; routed to checker or deviation approver.

Op 36: deviation.request

• Input: { decision_run_id, reason, requested_overrides }
• Side effects: routes to approval queue per delegation matrix.

Op 37: deviation.approve

• Input: { deviation_id, approver_id, conditions? }
• Side effects: decision moves to APPROVED with deviation flag + conditions.

Phase F — Sanction and documentation

Op 38: offer.create

• Input: { decision_run_id, amount, tenure, rate, fees, conditions }
• Side effects: creates offer row with validity.
• Returns: offer_id.

Op 39: offer.accept

• Input: { offer_id }
• Validations: offer not expired.
• Side effects: offer status updated; triggers documentation.

Op 40: sanction.issue

• Input: { application_id, offer_id }
• Side effects: creates sanction row; triggers document generation.
• Returns: sanction_id.

Op 41: document.generate

• Input: { sanction_id, doc_type, language, template_version? }
• Operations: render template with sanction + borrower data; produce PDF.
• Side effects: stores in S3; creates issued_document row.
• Returns: { document_id, object_uri }.

Op 42: kfs.acknowledge

• Input: { kfs_document_id, evidence }
• Side effects: KFS marked acknowledged with timestamp + IP + device.
• Returns: { acknowledged_at }.

Op 43: esign.session.start

• Input: { document_id, signers[] }
• Vendor: Leegality / Digio.
• Returns: { session_id, signing_urls[] }.

Op 44: esign.session.complete (webhook)

• Input: vendor webhook.
• Side effects: per signer status updated; on all-complete, document marked executed.

Op 45: estamp.issue

• Input: { document_id, state, denomination }
• Vendor: SHCIL via partner.
• Returns: { estamp_session_id, certificate_uri }.

Op 46: mandate.create

• Input: { application_id, account_token, ifsc, type, max_debit, valid_from, valid_to }
• Vendor: Digio / Razorpay / Cashfree / Setu.
• Returns: { mandate_id, status: "pending" }.

Op 47: mandate.status_check

• Input: { mandate_id }
• Operations: polls vendor / sponsor bank.
• Returns: { status }.

Phase G — Pre-disbursement

Op 48: disbursement.create_instruction

• Input: { sanction_id, amount, to_account_token, purpose, splits? }
• Validations:
  • Sanction valid + within validity.
  • Amount <= sanctioned + remaining limit.
  • Bank account verified.
  • All pre-conditions on sanction met.
• Side effects: creates disbursement_instruction row in PENDING_APPROVAL.
• Returns: disbursement_id.

Op 49: disbursement.pre_check

• Input: { disbursement_id }
• Operations: runs the pre-disbursement checklist:
  • KYC valid + not expired.
  • KYB complete.
  • Sanction within validity.
  • All borrower documents executed.
  • KFS acknowledged.
  • NACH mandate active.
  • Bank account verified (penny drop within tolerance).
  • Sanctions screen clean.
  • Decision still valid (no new data invalidates).
  • Exposure caps unbreached.
  • Co-lender approval (if applicable).
  • DLG instrument confirmed (if applicable).
  • Cooling-off opted-in (where applicable).
• Returns: { all_pass: bool, failures[] }.

Op 50: disbursement.approve

• Input: { disbursement_id, approver_id }
• Validations: approver has delegated authority for this amount.
• Side effects: status → APPROVED.

Phase H — Disbursement and handoff

Op 51: disbursement.execute

• Input: { disbursement_id } with X-Idempotency-Key
• Operations:
  • For co-lending: trigger partner-funds-release into escrow.
  • Call payout adapter (sponsor bank API or RazorpayX / Cashfree).
  • Capture UTR.
• Side effects: status → EXECUTING → COMPLETED on success.
• Returns: { status, utr? }.

Op 52: disbursement.utr_captured

• Input: vendor webhook with UTR.
• Side effects:
  • Status → COMPLETED.
  • Triggers borrower notification.
  • Triggers loan activation in LMS.

Op 53: disbursement.returned

• Input: returned-funds notification.
• Side effects:
  • Reverses loan booking.
  • Notifies ops.
  • Re-attempt workflow.

Op 54: loan.activate (handoff to LMS)

• Input: { sanction_id, disbursement_id, product_terms }
• Side effects:
  • Creates loan_account row.
  • Generates schedule.
  • Starts daily accrual.
  • Triggers co-lending allocation if applicable.
  • Emits loan.activated event.
• Returns: loan_account_id.

Op 55: loan.notify_borrower

• Input: { loan_id }
• Operations: SMS + WhatsApp + email with loan number + UTR + first due date + statement link.

Op 56: loan.notify_partner (for co-lent)

• Input: { loan_id, partner_id }
• Operations: API / webhook + daily MIS entry.

Phase I — Channel ops

Op 57: dsa.payout.compute

• Input: { loan_id, channel_id }
• Operations: compute DSA fee per channel agreement.
• Side effects: creates dsa_payout row.

Op 58: dsa.payout.execute

• Input: { payout_id, approver_id }
• Operations: execute payout to DSA.

Cross-cutting operations

Op 59: application.withdraw

• Input: { application_id, reason }
• Side effects: state → WITHDRAWN. Refund any received fees.

Op 60: application.expire

• Trigger: scheduler for offer / sanction validity.
• Side effects: state → EXPIRED.

Op 61: audit.event (every state change)

Already covered in 5.13.

Vendor cost reference (per application, illustrative)

Operation category	Typical cost per application
Pre-eligibility	₹10 – ₹25
KYC suite	₹50 – ₹200 (depends on vendor mix)
V-CIP	₹40 – ₹150 per session
AA fetch	₹15 – ₹50
BSA parse	₹15 – ₹50
GST pull	₹20 – ₹80
Bureau (4 CICs)	₹100 – ₹500
MCA fetch	₹5 – ₹20
eSign + eStamp	₹30 – ₹150
Mandate activation	₹15 – ₹50
Payout fee	₹2 – ₹10
Total per disbursed loan	₹300 – ₹1,500 (vendor cost)

What the platform must enforce

• Every operation idempotency-keyed.
• Every operation audited.
• Every operation rate-limited per vendor.
• Every operation has clear failure path.
• Every operation has SLA tracked.

Related

• 18.1 LOS state machine.
• 3.B through 3.I product modules for context.
• 5.10 API catalogue.
• 4. Integrations for vendor details.