2) API Sketch (Order Intake & Matching Receipt)
Base URL (example): https://api.appraisal-clearinghouse.state.us/v1
Authentication
- OAuth2 client credentials (lenders/AMCs).
- mTLS for server-to-server integrations.
- All endpoints JSON over HTTPS.
2.1 Submit Order
POST /orders
Request (example)
POST /orders
{
"client_order_id": "ABC-2025-000123",
"lender_id": "LEND-4412",
"loan_purpose": "purchase",
"geography": {
"county_fips": "06081",
"subject_address_hash": "a6c5... (sha256)"
},
"product": {
"form": "1004",
"inspection": "full",
"program": ["FANNIE_MAE"]
},
"property": {
"type": "SFR",
"living_area_sqft": 2100,
"acreage": 0.15,
"features": ["ADU:false", "waterfront:false"]
},
"complexity_tier": "standard",
"approvals_required": ["FHA:false", "VA:false"],
"sla": { "target_days": 7, "latest_delivery_utc": "2025-10-15T00:00:00Z" },
"constraints": { "borrower_language": "en", "availability_window_days": 3 },
"filters": {
"geo_radius_miles": 25,
"min_experience_hours": 2000,
"licenses_required": ["CA_CERTIFIED_RESIDENTIAL"]
},
"attachments": {
"loan_number_hash": "b9e1...",
"prior_appraisal_hash": null
},
"notes": "Condo-like amenities; new subdivision nearby; avoid weekdays 12–2pm for access."
}
Response (Accepted)
{
"order_id": "ORD-9c2e7a8c",
"status": "intake_pending",
"intake_timestamp": "2025-09-30T14:12:03Z",
"next": { "poll_after_seconds": 5, "href": "/orders/ORD-9c2e7a8c" }
}
2.2 Get Order Status / Matching Receipt
GET /orders/{order_id}
Response (Matched)
{
"order_id": "ORD-9c2e7a8c",
"status": "matched",
"match": {
"appraiser_id": "APR-CA-002913",
"tentative": true,
"expires_utc": "2025-09-30T14:27:03Z",
"contact_channel": "clearinghouse_messaging",
"handoff_href": "/assignments/ASN-7a31f1b9"
},
"decision_card": {
"filters": {
"geo_radius_miles": 25,
"licenses_required": ["CA_CERTIFIED_RESIDENTIAL"],
"min_experience_hours": 2000,
"form": "1004",
"inspection": "full"
},
"eligible_pool_size": 37,
"scoring_inputs": [
{ "appraiser_id": "APR-CA-002913", "recent_share_90d": 0.021, "competency_depth": 0.81, "quality_index": 0.94, "sla_penalty": 0.00, "score": 1.83 }
],
"selection_rule": "rotation_with_capped_quality_adjustments_v1",
"conflict_checks": { "prior_service_12m": false, "relationship_flags": [] },
"audit_hash": "7f1a... (sha256 over request+filters+eligible_set+scores)"
}
}
2.3 Decline/Accept by Appraiser
POST /assignments/{assignment_id}/decision
{ "decision": "accept", "message": "Can inspect within 48 hours." }
(or)
{ "decision": "decline", "reason_code": "capacity", "message": "Booked through Friday." }
2.4 Reconsideration of Value (ROV) Intake
POST /assignments/{assignment_id}/rov
{
"submitted_by": "lender",
"evidence": [
{ "type": "sale", "address_hash": "913f...", "close_date": "2025-07-15", "price": 1125000, "notes": "Similar condition per photos" }
],
"claim": "omitted_comparable",
"explanation": "Two sales within 0.3 mi not analyzed; request review."
}
2.5 Transparency (Aggregate)
GET /analytics/distribution?county_fips=06081&period=2025Q3
{
"orders": 1832,
"eligible_pool_mean": 42.7,
"distribution_gini": 0.19,
"median_turn_days": 6.3,
"rov_rate": 0.041
}