Servicing API¶

Loan servicing operations: modifications, forbearance, deferments, payment plans, promises to pay, payoff quotes, suspense management, and service credits.

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

Modifications¶

Loan modifications change the terms of an active loan (rate, term, payment amount, principal).

Method	Path	Description	Permission
`GET`	`/modifications`	List all modifications	`IsViewerOrAbove`
`GET`	`/modifications/{id}`	Get modification	`IsViewerOrAbove`
`GET`	`/loans/{id}/modifications`	List loan's modifications	`IsViewerOrAbove`
`POST`	`/loans/{id}/modifications`	Create modification	`IsLoanOfficerOrAbove`
`PUT`	`/modifications/{id}`	Update modification	`IsLoanOfficerOrAbove`
`POST`	`/modifications/{id}/approve`	Approve modification	`IsAdminOrAbove`
`POST`	`/modifications/{id}/reject`	Reject modification	`IsAdminOrAbove`
`POST`	`/modifications/{id}/apply`	Apply modification	`IsLoanOfficerOrAbove`

Create Modification¶

POST /api/v1/loans/{loan_id}/modifications

{
  "modification_type": "rate_change",
  "new_interest_rate": "0.065",
  "effective_date": "2026-02-01",
  "reason": "Hardship rate reduction"
}

Modification Types¶

Type	Description
`rate_change`	Change interest rate
`term_extension`	Extend loan term
`payment_change`	Change payment amount
`principal_forgiveness`	Forgive portion of principal (triggers 1099-C if >= $600)
`capitalization`	Roll accrued interest/fees into principal balance

Workflow¶

pending → approved → applied
         ↘ rejected

Apply triggers:

Stores before/after terms snapshot
Regenerates amortization schedule
Posts GL entries (for forgiveness/capitalization)
Assesses modification fee (if configured)

Forbearance¶

Temporarily pause or reduce payment requirements.

Method	Path	Description	Permission
`GET`	`/forbearances`	List all forbearances	`IsViewerOrAbove`
`GET`	`/forbearances/{id}`	Get forbearance	`IsViewerOrAbove`
`GET`	`/loans/{id}/forbearances`	List loan's forbearances	`IsViewerOrAbove`
`POST`	`/loans/{id}/forbearances`	Create forbearance	`IsLoanOfficerOrAbove`
`PUT`	`/forbearances/{id}`	Update forbearance	`IsLoanOfficerOrAbove`
`POST`	`/forbearances/{id}/complete`	Complete forbearance	`IsLoanOfficerOrAbove`
`POST`	`/forbearances/{id}/cancel`	Cancel forbearance	`IsLoanOfficerOrAbove`

Create Forbearance¶

POST /api/v1/loans/{loan_id}/forbearances

{
  "forbearance_type": "full",
  "start_date": "2026-02-01",
  "end_date": "2026-05-01",
  "reason": "Borrower hardship - job loss",
  "interest_accrual": true,
  "post_forbearance_action": "capitalize"
}

Forbearance Types¶

Type	Description
`full`	No payments required
`partial`	Reduced payments
`interest_only`	Interest-only payments

Deferments¶

Defer scheduled payments to the end of the loan term.

Method	Path	Description	Permission
`GET`	`/deferments`	List all deferments	`IsViewerOrAbove`
`GET`	`/deferments/{id}`	Get deferment	`IsViewerOrAbove`
`GET`	`/loans/{id}/deferments`	List loan's deferments	`IsViewerOrAbove`
`POST`	`/loans/{id}/deferments`	Create deferment	`IsLoanOfficerOrAbove`
`PUT`	`/deferments/{id}`	Update deferment	`IsLoanOfficerOrAbove`
`POST`	`/deferments/{id}/complete`	Complete deferment	`IsLoanOfficerOrAbove`
`POST`	`/deferments/{id}/cancel`	Cancel deferment	`IsLoanOfficerOrAbove`

Create Deferment¶

POST /api/v1/loans/{loan_id}/deferments

{
  "periods_deferred": 3,
  "interest_treatment": "accrue",
  "reason": "Natural disaster forbearance extension"
}

Interest Treatment Options¶

Option	Description
`accrue`	Interest continues to accrue
`waive`	Interest waived during deferment
`capitalize`	Accrued interest added to principal

Payment Plans¶

Structured payment arrangements for delinquent borrowers.

Method	Path	Description	Permission
`GET`	`/payment-plans`	List all payment plans	`IsViewerOrAbove`
`GET`	`/payment-plans/{id}`	Get payment plan	`IsViewerOrAbove`
`GET`	`/loans/{id}/payment-plans`	List loan's plans	`IsViewerOrAbove`
`POST`	`/loans/{id}/payment-plans`	Create payment plan	`IsCollectorOrAbove`
`PUT`	`/payment-plans/{id}`	Update payment plan	`IsCollectorOrAbove`
`POST`	`/payment-plans/{id}/activate`	Activate plan	`IsCollectorOrAbove`
`POST`	`/payment-plans/{id}/complete`	Complete plan	`IsCollectorOrAbove`
`POST`	`/payment-plans/{id}/break`	Mark plan as broken	`IsCollectorOrAbove`
`POST`	`/payment-plans/{id}/cancel`	Cancel plan	`IsCollectorOrAbove`

Payment Plan Types¶

Type	Description
`catch_up`	Catch up on missed payments (regular + arrears)
`settlement`	Settle debt for less than owed

Promises to Pay¶

Track borrower commitments to make payments by a specific date.

Method	Path	Description	Permission
`GET`	`/promises-to-pay`	List all promises	`IsViewerOrAbove`
`GET`	`/promises-to-pay/{id}`	Get promise	`IsViewerOrAbove`
`GET`	`/loans/{id}/promises-to-pay`	List loan's promises	`IsViewerOrAbove`
`POST`	`/loans/{id}/promises-to-pay`	Create promise	`IsCollectorOrAbove`

Create Promise to Pay¶

POST /api/v1/loans/{loan_id}/promises-to-pay

{
  "promised_amount": "500.00",
  "promised_date": "2026-01-25",
  "notes": "Borrower committed during phone call"
}

Broken promises are detected by a daily Celery task.

Payoff Quotes¶

Generate payoff quotes with good-through dates.

Method	Path	Description	Permission
`GET`	`/payoff-quotes`	List all quotes	`IsViewerOrAbove`
`GET`	`/payoff-quotes/{id}`	Get quote	`IsViewerOrAbove`
`GET`	`/loans/{id}/payoff-quotes`	List loan's quotes	`IsViewerOrAbove`
`POST`	`/loans/{id}/payoff-quotes`	Generate quote	`IsLoanOfficerOrAbove`
`POST`	`/payoff-quotes/{id}/expire`	Expire a quote	`IsLoanOfficerOrAbove`

Generate Payoff Quote¶

POST /api/v1/loans/{loan_id}/payoff-quotes

{
  "good_through_date": "2026-02-15"
}

Response:

{
  "id": "...",
  "principal_balance": "8500.00",
  "accrued_interest": "45.23",
  "outstanding_fees": "25.00",
  "per_diem_interest": "1.96",
  "prepayment_penalty": "0.00",
  "total_payoff_amount": "8570.23",
  "good_through_date": "2026-02-15",
  "status": "active"
}

Suspense¶

Manage unapplied funds held in suspense.

Method	Path	Description	Permission
`GET`	`/suspense`	List all suspense entries	`IsViewerOrAbove`
`GET`	`/suspense/{id}`	Get suspense entry	`IsViewerOrAbove`
`GET`	`/loans/{id}/suspense`	List loan's suspense	`IsViewerOrAbove`
`POST`	`/suspense/{id}/apply`	Apply suspense to loan	`IsLoanOfficerOrAbove`
`POST`	`/suspense/{id}/refund`	Refund suspense to borrower	`IsLoanOfficerOrAbove`

Service Credits¶

One-time credits applied to a borrower's loan.

Method	Path	Description	Permission
`GET`	`/service-credits`	List all service credits	`IsViewerOrAbove`
`GET`	`/service-credits/{id}`	Get service credit	`IsViewerOrAbove`
`GET`	`/loans/{id}/service-credits`	List loan's credits	`IsViewerOrAbove`
`POST`	`/loans/{id}/service-credits`	Create service credit	`IsAdminOrAbove`