Skip to main content
This page defines the replacement API design. The current API returns separate risk snapshots, attributes and decisions; follow current evidence traceability for those resources. The proposed RiskPackage is not yet a live endpoint.

​
What the institution receives

A risk package is the completed assessment of a borrower in a specific lending context. It is not just a score, a provider response dump or an executed lending decision. Every meaningful conclusion must lead back to evidence. Preserve measured values and definitions separately from narrative interpretation. A fluent explanation is not a substitute for a calculable metric or licensed provider result.

​
Assessment dimensions

These are assessment categories, not a promise that every integration supplies every field. Use the existing 56 derived-attribute definitions where applicable. Any new metric needs an approved formula, units, eligible population, minimum coverage, evidence inputs and calculation version before implementation. There is no universal score, threshold or minimum ratio suitable for all products and markets.

​
Availability is part of the answer

A dimension is available, partial, unavailable or not_applicable. Individual proposed scalar metrics are available, unavailable or not_applicable; a usable metric has a decimal-string value and an explicit unit/window. Unavailable metrics have a null value and a reason. Coverage limitations belong alongside the result, not only in a log. Do not substitute zero for missing revenue, debt, DSCR, DTI, a credit score or probability of default. Do not manufacture a PD or provider score where the model is not validated, licensed and entitled. Actual cash-flow DSCR and EBITDA-based proxies must have different definitions. Do not combine currencies, legal entities or non-comparable periods without an explicit approved transformation. Policy results use unavailable when inputs are missing. The overall recommendation must not become within_policy while a required rule remains unavailable. Institutions review the reasons and make their own final decision.

​
Evidence and documents

  1. Read the package’s immutable evidence_set.id.
  2. List evidence with that set ID and an optional normalized resource_type filter.
  3. Retrieve a record using its evidence ID. The response contains the frozen normalized version, provenance and any document reference.
  4. Request a controlled download for an authorized original file or provider report. Verify the returned digest against the downloaded bytes.
  5. Use an asynchronous export for large normalized datasets or a complete risk-package report.
This preserves bank transactions, accounting records, payments, commerce, inventory, lender-supplied exposures, KYB/KYC results, liens, reconciliations and retained documents without one collection endpoint per table. Exact records may be restricted by source licensing, consent or retention. Return explicit unavailability; never silently substitute today’s record for the one used in the assessment. A content hash establishes byte consistency, not source authenticity or legal sufficiency. The package and evidence-set digest rules must reuse the canonical manifest serialization in evidence traceability, and the implementation must verify member hashes before publishing an export.

​
Historical integrity

Completed packages cannot be edited. A corrected source or changed policy produces a new package linked to its predecessor. Monitoring keeps the original baseline and each subsequent assessment. The prior facts, missing-data state, policy version and reasons remain auditable until the configured retention boundary. The synthetic package example illustrates a case requiring review because repayment evidence is missing. Its values and hashes are illustrative and are not model-performance or verification claims.