Loans API¶

Manage loan records, lifecycle transitions, and nested resources. The loans API is the largest in the system with extensive business action endpoints.

Base permission: IsViewerOrAbove (read), IsLoanOfficerOrAbove (write)

Endpoints¶

Core CRUD¶

Method	Path	Description	Permission
`GET`	`/loans`	List loans	`IsViewerOrAbove`
`GET`	`/loans/{id}`	Get loan by ID	`IsViewerOrAbove`
`POST`	`/loans`	Create loan	`IsLoanOfficerOrAbove`
`PUT`	`/loans/{id}`	Update loan	`IsLoanOfficerOrAbove`
`DELETE`	`/loans/{id}`	Archive loan	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/unarchive`	Unarchive loan	`IsLoanOfficerOrAbove`
`GET`	`/loans/{id}/history`	Get audit history	`IsViewerOrAbove`

Create Loan¶

POST /api/v1/loans

{
  "borrower_id": "550e8400-e29b-41d4-a716-446655440000",
  "program_id": "661f9511-f3ac-52e5-b827-557766551111",
  "product_id": "772a0622-a4bd-63f6-c938-668877662222",
  "principal_amount": "10000.00",
  "interest_rate": "0.085",
  "term_months": 36,
  "payment_day": 15,
  "external_id": "LN-EXT-001"
}

Response (201): Full loan object with auto-generated loan_number, status set to pending.

Lifecycle Actions¶

These endpoints transition the loan through its status state machine.

Method	Path	Description	Permission
`POST`	`/loans/{id}/approve`	Approve a pending loan	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/deny`	Deny a pending loan	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/disburse`	Mark loan as disbursed	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/cancel`	Cancel a loan	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/charge-off`	Charge off a defaulted loan	`IsAdminOrAbove`
`POST`	`/loans/{id}/pay-off`	Mark loan as paid off	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/non-accrual`	Toggle non-accrual status	`IsAdminOrAbove`

Approve¶

Runs compliance checks (if configured) and moves the loan from pending to approved.

POST /api/v1/loans/{id}/approve

{
  "notes": "Credit check passed, DTI within limits."
}

Preconditions: Loan must be in pending status. Compliance checks must pass (if hard enforcement is enabled).

Response (200): Updated loan with status: "approved".

Response (409): Compliance check failed or invalid status transition.

Disburse¶

Triggers loan activation: generates amortization schedule, posts GL entries, assesses origination fees.

POST /api/v1/loans/{id}/disburse

{
  "disbursement_date": "2026-01-15"
}

Management Actions¶

Method	Path	Description	Permission
`POST`	`/loans/{id}/assign-officer`	Assign loan officer	`IsAdminOrAbove`
`POST`	`/loans/{id}/reschedule`	Reschedule payment dates	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/change-due-date`	Change payment due day	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/freeze`	Freeze loan (stop accrual)	`IsAdminOrAbove`
`POST`	`/loans/{id}/unfreeze`	Unfreeze loan	`IsAdminOrAbove`
`POST`	`/loans/{id}/accelerate`	Accelerate full balance	`IsAdminOrAbove`
`POST`	`/loans/{id}/reverse-acceleration`	Reverse acceleration	`IsAdminOrAbove`
`POST`	`/loans/{id}/add-labels`	Add labels to loan	`IsLoanOfficerOrAbove`
`POST`	`/loans/{id}/remove-labels`	Remove labels from loan	`IsLoanOfficerOrAbove`

Balance Queries¶

Get Balances¶

Returns a detailed balance breakdown for the loan.

GET /api/v1/loans/{id}/get-balances

Response:

{
  "principal_balance": "8500.00",
  "accrued_interest": "45.23",
  "outstanding_fees": "25.00",
  "total_balance": "8570.23",
  "next_payment_amount": "312.50",
  "next_payment_date": "2026-02-15",
  "payoff_amount": "8572.50"
}

Future Balance Projection¶

GET /api/v1/loans/{id}/get-future-balance-projection?as_of_date=2026-06-15

Promotional Programs¶

Method	Path	Description
`POST`	`/loans/{id}/activate-promo`	Activate promotional program
`GET`	`/loans/{id}/list-promo-statuses`	List active promotions

Loan Boarding¶

Import an existing loan with historical state.

POST /api/v1/loans/board

{
  "borrower_id": "...",
  "program_id": "...",
  "product_id": "...",
  "loan_number": "LN-LEGACY-001",
  "principal_amount": "25000.00",
  "current_principal_balance": "18000.00",
  "interest_rate": "0.065",
  "term_months": 60,
  "origination_date": "2024-06-01",
  "first_payment_date": "2024-07-01",
  "status": "active"
}

Nested Resources¶

Payments¶

Method	Path	Description
`GET`	`/loans/{id}/payments`	List loan's payments
`POST`	`/loans/{id}/payments`	Record payment
`POST`	`/loans/{id}/payments/preview`	Preview payment allocation
`POST`	`/loans/{id}/payments/reimbursement`	Record reimbursement

Modifications¶

Method	Path	Description
`GET`	`/loans/{id}/modifications`	List modifications
`POST`	`/loans/{id}/modifications`	Create modification

Forbearances¶

Method	Path	Description
`GET`	`/loans/{id}/forbearances`	List forbearances
`POST`	`/loans/{id}/forbearances`	Create forbearance

Deferments¶

Method	Path	Description
`GET`	`/loans/{id}/deferments`	List deferments
`POST`	`/loans/{id}/deferments`	Create deferment

Payment Plans¶

Method	Path	Description
`GET`	`/loans/{id}/payment-plans`	List payment plans
`POST`	`/loans/{id}/payment-plans`	Create payment plan

Promises to Pay¶

Method	Path	Description
`GET`	`/loans/{id}/promises-to-pay`	List promises to pay
`POST`	`/loans/{id}/promises-to-pay`	Create promise to pay

Payoff Quotes¶

Method	Path	Description
`GET`	`/loans/{id}/payoff-quotes`	List payoff quotes
`POST`	`/loans/{id}/payoff-quotes`	Generate payoff quote

Suspense¶

Method	Path	Description
`GET`	`/loans/{id}/suspense`	List suspense entries

Service Credits¶

Method	Path	Description
`GET`	`/loans/{id}/service-credits`	List service credits
`POST`	`/loans/{id}/service-credits`	Create service credit

Fee Assessments¶

Method	Path	Description
`GET`	`/loans/{id}/fees`	List assessed fees

Disbursements¶

Method	Path	Description
`GET`	`/loans/{id}/disbursements`	List disbursements
`POST`	`/loans/{id}/disbursements`	Create disbursement

Collateral¶

Method	Path	Description
`GET`	`/loans/{id}/collateral`	List collateral items

Draws (Line of Credit)¶

Method	Path	Description
`GET`	`/loans/{id}/draws`	List draws
`POST`	`/loans/{id}/draws`	Create draw

Compliance¶

Method	Path	Description
`POST`	`/loans/{id}/run-compliance-checks`	Run compliance checks
`GET`	`/loans/{id}/credit-reporting`	List credit reporting records
`GET`	`/loans/{id}/credit-disputes`	List credit disputes

1099-C Forms¶

Method	Path	Description
`GET`	`/loans/{id}/1099c`	List 1099-C forms
`POST`	`/loans/{id}/1099c`	Generate 1099-C form

Filtering¶

Parameter	Description
`q`	Search by loan number
`status`	Filter by loan status
`borrower_id`	Filter by borrower
`program_id`	Filter by lending program
`product_id`	Filter by loan product
`loan_officer_id`	Filter by assigned officer
`external_id`	Lookup by external ID
`is_frozen`	Filter by frozen flag
`is_accelerated`	Filter by accelerated flag
`delinquency_bucket`	Filter by delinquency bucket