Collateral API¶

Manage collateral items, liens, and valuations associated with loans.

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

Collateral Items¶

Method	Path	Description	Permission
`GET`	`/collateral`	List collateral items	`IsViewerOrAbove`
`GET`	`/collateral/{id}`	Get collateral item	`IsViewerOrAbove`
`POST`	`/collateral`	Create collateral item	`IsLoanOfficerOrAbove`
`PUT`	`/collateral/{id}`	Update collateral item	`IsLoanOfficerOrAbove`
`DELETE`	`/collateral/{id}`	Archive collateral item	`IsLoanOfficerOrAbove`
`POST`	`/collateral/{id}/liquidate`	Liquidate collateral	`IsAdminOrAbove`
`GET`	`/loans/{id}/collateral`	List loan's collateral	`IsViewerOrAbove`

Create Collateral Item¶

POST /api/v1/collateral

{
  "loan_id": "550e8400-e29b-41d4-a716-446655440000",
  "collateral_type": "real_estate",
  "description": "Single-family residence at 123 Main St",
  "estimated_value": "250000.00",
  "metadata": {
    "property_type": "single_family",
    "year_built": 2005,
    "square_footage": 2100,
    "parcel_number": "APN-12345"
  }
}

Collateral Types¶

Type	Metadata Fields
`real_estate`	property_type, year_built, square_footage, parcel_number
`vehicle`	make, model, year, vin, mileage
`equipment`	manufacturer, model, serial_number, condition
`inventory`	category, quantity, unit_value
`accounts_receivable`	debtor_count, aging_summary
`securities`	security_type, ticker, shares, custodian
`other`	Freeform metadata

Liquidate Collateral¶

Process collateral liquidation and apply proceeds to the loan balance.

POST /api/v1/collateral/{id}/liquidate

{
  "sale_price": "230000.00",
  "sale_date": "2026-03-15",
  "sale_expenses": "12000.00",
  "notes": "Foreclosure sale completed"
}

Effects:

Calculates net proceeds (sale_price - sale_expenses)
Applies proceeds to outstanding loan balance
Posts GL entries (DR Cash, CR Loans Receivable)
Records deficiency balance if proceeds < outstanding
Releases associated liens

Liens¶

Method	Path	Description	Permission
`GET`	`/collateral/{id}/liens`	List liens on collateral	`IsViewerOrAbove`
`POST`	`/collateral/{id}/liens`	Create lien	`IsLoanOfficerOrAbove`
`POST`	`/liens/{id}/release`	Release lien	`IsLoanOfficerOrAbove`

Create Lien¶

POST /api/v1/collateral/{collateral_id}/liens

{
  "lien_type": "ucc1",
  "filing_number": "2026-001234",
  "filing_date": "2026-01-15",
  "expiration_date": "2031-01-15",
  "filing_jurisdiction": "Delaware",
  "lien_position": 1
}

Lien Types¶

Type	Description
`ucc1`	UCC-1 financing statement
`mortgage`	Real estate mortgage
`deed_of_trust`	Deed of trust
`security_agreement`	Security agreement
`other`	Other lien type

Note

A daily Celery task monitors lien expiration dates and generates alerts for liens expiring within 180 days.

Valuations¶

Method	Path	Description	Permission
`GET`	`/collateral/{id}/valuations`	List valuations	`IsViewerOrAbove`
`POST`	`/collateral/{id}/valuations`	Create valuation	`IsLoanOfficerOrAbove`

Create Valuation¶

POST /api/v1/collateral/{collateral_id}/valuations

{
  "valuation_type": "appraisal",
  "valuation_date": "2026-01-10",
  "appraised_value": "255000.00",
  "appraiser_name": "Smith Appraisals Inc.",
  "notes": "Annual property re-appraisal"
}

Valuation Types¶

Type	Description
`appraisal`	Professional appraisal
`bpo`	Broker price opinion
`avm`	Automated valuation model
`internal`	Internal estimate
`purchase_price`	Original purchase price