5.10 API catalogue

This page catalogues the most-touched APIs across the platform. The actual platform will expose 300+ endpoints once mature; the 40+ below are the ones that touch every loan and that engineers consult constantly.

Format conventions:

Endpoint path (with version /v1).
Auth (mTLS internal, OAuth2 external, bearer token).
Idempotency — Idempotency-Key header on all mutating calls.
Payload — abbreviated; full schemas in the OpenAPI spec at /openapi.yaml in each service repo.
Errors — common codes; full taxonomy in the service.

Borrower-facing APIs (external, via Borrower BFF)

`POST /v1/leads`

Create a new lead.

Auth: borrower mobile-OTP session.
Body: { mobile, pan?, gstin?, channel_ref, utm }.
Returns: 201 { lead_id }.
Errors: 422 (dedup) returns existing_lead_id.

`POST /v1/applications`

Create application from lead (or fresh).

Body: { lead_id?, loan_product_id, loan_amount_sought, tenure_sought, purpose_code }.
Returns: 201 { application_id, status: "draft" }.

`PUT /v1/applications/{id}`

Update an in-progress application section.

Body: section data (full or partial).
Returns: 200 { application_id, section_name, last_saved_at }.
Idempotency: optional; section-level overwrite.

`POST /v1/applications/{id}/sections/{name}`

Section-level save (preferred over PUT for granular updates).

Body: section JSON.
Returns: 200 { saved_at }.

`POST /v1/applications/{id}/consents`

Record a consent (bureau, AA, GST, DPDP).

Body: { purpose, data_categories, version_of_policy, vendor?, vendor_consent_ref? }.
Returns: 201 { consent_id, granted_at }.
Audit: every call audited with IP, device fingerprint.

`POST /v1/applications/{id}/documents`

Upload a document (multipart).

Body: multipart/form-data with file + type.
Returns: 201 { document_id, object_uri, verified: false }.

`POST /v1/applications/{id}/submit`

Finalise application; triggers underwriting.

Body: empty or final acknowledgements.
Returns: 202 { application_id, status: "under_review", expected_decision_at }.
Idempotency: required.

`POST /v1/applications/{id}/withdraw`

Borrower withdraws application.

Returns: 200 { application_id, status: "withdrawn" }.

`GET /v1/applications/{id}`

Read application + current status + offer if available.

Returns: full application state.

`POST /v1/offers/{id}/accept`

Borrower accepts the offer; triggers documentation generation.

Body: optional acknowledgements.
Returns: 200 { offer_id, accepted_at }.
Idempotency: required.

`POST /v1/documents/{id}/acknowledge-kfs`

Borrower acknowledges KFS (pre-disbursement gate).

Returns: 200 { kfs_id, acknowledged_at }.
Audit: timestamp, IP, device.

`POST /v1/esign/sessions/{id}/sign`

Borrower signs document via Aadhaar OTP.

Body: { aadhaar_otp_txn_ref }.
Returns: 200 { session_id, status }.

`GET /v1/loans/{id}/statement`

Retrieve loan statement.

Query: from, to.
Returns: statement JSON; PDF link.

`POST /v1/loans/{id}/repayments/initiate`

Borrower initiates ad-hoc repayment (payment link / UPI / QR).

Body: { amount }.
Returns: 201 { payment_link, expires_at }.

Internal service APIs

KYC service

`POST /v1/kyc/individual`

Initiate KYC for a promoter.

Auth: internal service token.
Body: { promoter_id, method }.
Returns: 201 { kyc_record_id, session }.

`POST /v1/kyc/vcip/schedule`

Schedule a V-CIP session.

Body: { kyc_record_id, preferred_time }.
Returns: 201 { session_id, vendor, session_url }.

`GET /v1/kyc/vcip/{id}`

Get V-CIP session result.

Returns: 200 { session, outcome, recording_uri }.

`POST /v1/ckyc/search`

Search CKYC by PAN / Aadhaar / mobile.

Body: { pan?, aadhaar_token?, mobile? }.
Returns: 200 { kin? }.

`POST /v1/ckyc/upload`

Upload new KYC record to CKYCR.

Body: standardised CKYC upload payload.
Returns: 201 { kin }.

`POST /v1/sanctions/screen`

Screen subject against sanctions / PEP / adverse media.

Body: { subject_type, subject_id, name, dob?, address? }.
Returns: 200 { screen_id, hits: [] }.

Ingestion service

`POST /v1/data/aa/consent-request`

Initiate AA consent request.

Body: { borrower_id, purpose, fi_types, date_range, frequency }.
Returns: 201 { consent_handle, redirect_url }.

`POST /v1/data/aa/fetch`

Fetch AA data given a consent handle.

Body: { consent_handle }.
Returns: 202 { fetch_id, status: "in_progress" }.

`POST /v1/data/bank-statement/upload`

Upload a bank statement PDF for parsing.

Body: multipart with file.
Returns: 202 { pull_id, status: "in_progress" }.

`POST /v1/data/gst/pull`

Pull GST returns given borrower consent.

Body: { borrower_id, gstin, periods }.
Returns: 202 { pull_id, status }.

`POST /v1/data/bureau/pull`

Pull bureau report.

Body: { subject_type, subject_id, cic, report_type }.
Returns: 200 { bureau_report_id, parsed_uri } (sync) or 202 (async via vendor).

`GET /v1/borrowers/{id}/data-room`

Aggregated view of all data pulled for a borrower.

Returns: catalogue of pulls with status and metric summaries.

Decisioning service

`POST /v1/decisions/run`

Execute decision engine against an application.

Auth: internal.
Body: { application_id, policy_id? } (policy_id auto-selected if omitted).
Returns: 200 { decision_run_id, decision, grade, recommended } (sync) or 202 (async for complex models).

`GET /v1/decisions/{id}`

Retrieve decision with full trace.

Returns: full trace JSON including every rule fired.

`POST /v1/decisions/{id}/deviation`

Request deviation approval.

Body: { reason, requested_overrides_json }.
Returns: 201 { deviation_id, status: "pending" }.

`POST /v1/policies`

Create new policy version.

Body: rule set + metadata.
Returns: 201 { policy_id, version, effective_from }.

`POST /v1/policies/{id}/sandbox-test`

Test new policy against historical applications.

Body: { test_set_id }.
Returns: 202 { test_run_id } then results via webhook / poll.

Documentation service

`POST /v1/documents/{type}/generate`

Generate a document (KFS, agreement, DPN, PG).

Body: { sanction_id, language, template_version? }.
Returns: 201 { document_id, object_uri }.

`POST /v1/esign/sessions`

Start eSign multi-signer flow.

Body: { document_id, signers: [{ promoter_id, mobile, email }] }.
Returns: 201 { session_id, signing_url[] }.

`POST /v1/estamp/sessions`

Issue eStamp certificate.

Body: { document_id, state, denomination }.
Returns: 201 { estamp_session_id, certificate_uri }.

`POST /v1/mandates/create`

Create NACH / eNACH / UPI AutoPay mandate.

Body: { application_id, account_token, ifsc, type, max_debit_amount, valid_from, valid_to }.
Returns: 201 { mandate_id, status: "pending" }.

`GET /v1/mandates/{id}/status`

Get mandate activation status.

Returns: 200 { mandate_id, status, npci_ref? }.

Disbursement service

`POST /v1/disbursements`

Create disbursement instruction.

Auth: internal + delegated authority check.
Body: { loan_account_id, amount, to_account, purpose, splits[]? }.
Returns: 201 { disbursement_id, status: "pending_approval" }.
Idempotency: required.

`POST /v1/disbursements/{id}/approve`

Maker-checker approval.

Body: { approver_id }.
Returns: 200 { disbursement_id, status: "approved" }.

`POST /v1/disbursements/{id}/execute`

Fire to payout rail.

Returns: 202 { disbursement_id, status: "executing" }.

`GET /v1/disbursements/{id}/status`

Returns: 200 { disbursement_id, status, utr? }.

LMS service

`POST /v1/loans`

Create loan on disbursement completion (internal).

Body: { sanction_id, disbursement_id, product_terms }.
Returns: 201 { loan_account_id, activated_at }.

`GET /v1/loans/{id}`

Returns: current state + summary.

`GET /v1/loans/{id}/schedule`

Returns: schedule lines with paid/unpaid status.

`POST /v1/loans/{id}/repayments`

Record a repayment (internal; called by NACH adapter or PG webhook).

Body: { amount, source, source_ref, received_at }.
Returns: 201 { repayment_id, allocation }.
Idempotency: required.

`POST /v1/loans/{id}/charges`

Apply a charge.

Body: { type, amount, reason }.
Returns: 201 { charge_id }.

`POST /v1/loans/{id}/prepay`

Borrower prepayment (partial or full).

Body: { amount, type }.
Returns: 200 { allocation, new_outstanding }.

`POST /v1/loans/{id}/foreclose`

Foreclose loan.

Body: { effective_date }.
Returns: 200 { closed_at, noc_uri }.

`POST /v1/loans/{id}/restructure`

Initiate restructuring workflow.

Body: { reason, proposed_terms }.
Returns: 202 { workflow_id } — long-running via workflow engine.

`POST /v1/loans/{id}/writeoff`

Approve write-off (with approval matrix).

Body: { approved_by, reason }.
Returns: 200 { writeoff_id }.

`GET /v1/loans/{id}/classification`

Current classification.

Returns: 200 { class, dpd_days, snapshot_date }.

Co-lending service

`POST /v1/colending/partners/{id}/loans/submit`

Submit loan to partner for approval.

Body: per 7.3 Co-lending APIs.
Returns: 202 { submission_id, expected_decision_by }.

`POST /v1/colending/partners/{id}/loans/{loan_id}/sanction`

Notify partner of acceptance + sanction.

`POST /v1/colending/partners/{id}/loans/{loan_id}/disbursed`

Notify partner of disbursement.

`GET /v1/colending/partners/{id}/mis`

Pull periodic MIS for partner.

`POST /v1/colending/settlements/{id}/execute`

Run a settlement batch.

Common headers and patterns

Required headers (all internal calls)

Authorization: Bearer {service_token} — short-lived JWT.
X-Service-Id: {caller} — for tracing.
X-Request-Id: {uuid} — distributed tracing ID.
X-Idempotency-Key: {uuid} — for mutating calls.

Required headers (external calls, partner-facing)

Authorization: Bearer {oauth_token} — partner-authenticated.
X-Signature: HMAC-SHA256(...) — for webhook callbacks.
X-Timestamp: {epoch_ms} — for replay protection.

Common response envelope

{
  "data": { ... },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2026-05-22T10:15:30Z"
  }
}

Common error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field X is required",
    "details": { "field": "X", "constraint": "non_empty" }
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2026-05-22T10:15:30Z"
  }
}

Common error codes

UNAUTHORIZED (401) — missing or invalid auth.
FORBIDDEN (403) — auth ok but insufficient permission.
NOT_FOUND (404) — resource missing.
VALIDATION_ERROR (422) — body validation failed.
IDEMPOTENCY_MISMATCH (409) — same key, different body.
RATE_LIMITED (429) — backoff and retry.
VENDOR_ERROR (502) — downstream vendor failure.
INTERNAL_ERROR (500) — bug; logged with request_id for triage.

Pagination

Cursor-based:

GET /v1/loans?cursor=eyJ...&limit=50

Response: { data: [...], meta: { next_cursor: "eyJ..." } }

Versioning

Version in URL: /v1/....
Backward-incompatible changes spawn /v2/....
v1 supported for 12 months minimum after v2 launch.
Sunset announced via Deprecation and Sunset headers per RFC 8594.

OpenAPI specifications

Each service exposes its full OpenAPI spec at /openapi.yaml. The CI pipeline:

Generates spec from code annotations (springdoc).
Validates that all endpoints have descriptions.
Runs schemas through compatibility checker against previous version.
Publishes spec artifacts to an internal docs portal.

What this catalogue is and isn’t

It is the 30-second reference an engineer consults before building.
It is not the full spec — for that, see the live OpenAPI at each service.
It assumes the modular monolith pattern; in a fully decomposed microservices setup, service prefixes (kyc., lms., etc.) would also appear in paths.
Co-lending APIs are spec’d in deeper detail at 7.3 including webhook contracts and partner-side variants.