Primary - Decisions
[RECOMMENDED] Get financing decision recommendations
This is the primary endpoint for production use. Analyzes borrower context, product requirements, and current market offers to return ranked action recommendations with explanations. Transforms rate data into actionable decisions by comparing market rates, evaluating savings opportunities, and providing confidence scores.
Supported Products:
- Mortgages: 15-year and 30-year fixed-rate mortgages with property-specific details
- Auto Loans: New and used vehicle financing with common terms (36, 48, 60, 72, 84 months)
Why use this endpoint:
- Personalized: Considers borrower credit score, income, DTI, and product-specific details
- Intelligent: Ranks offers by suitability with confidence scores
- Actionable: Returns next steps and decision rationale
- Comprehensive: Includes savings calculations and comparison analysis
Use Cases:
- Home purchase: Compare credit union rates for new mortgage applications
- Refinance: Evaluate if refinancing makes financial sense given current offers
- Auto loan shopping: Find the best auto loan rates from credit unions for new or used vehicles
- Rate shopping: Get personalized recommendations based on borrower profile
Authentication required: Pass your API key in the X-API-Key header.
post/v1/decisions
Request
- Base URL: https://api.rateapi.dev
- URL: https://api.rateapi.dev/v1/decisions
- Auth: API key in header X-API-Key
Headers
Idempotency-Keystring
Optional request identifier that makes this POST safe to retry. The first successful (2xx) response for a given identifier + request body is stored for 24 hours; a retry with the SAME identifier and SAME body replays that stored response and includes an Idempotent-Replayed: true response header (the handler does not run again). Reusing the same identifier with a DIFFERENT request body returns 422. Authenticated writes are scoped per API key. Use a UUID per logical operation.
Request body
Example request
{
"decision_type": "financing",
"context": {
"schema_version": "1.0",
"request_id": "req_abc123xyz",
"user_id": "usr_xyz789",
"as_of": "2024-01-15T12:00:00Z",
"geo": {
"state": "CA",
"zip": "94102",
"county": "Norfolk"
}
},
"borrower": {
"credit_score": 750,
"income_annual": 120000,
"employment": "employed",
"dti": 0.35,
"first_time_buyer": true,
"employer": "Boeing",
"military_status": "veteran",
"school": "UNC Charlotte",
"school_relationship": "student",
"worship": "Temple"
},
"product_request": {
"product_type": "mortgage",
"intent": "purchase",
"amount": 500000,
"term_months": 360,
"rate_type": "fixed",
"details": {
"property_type": "single_family",
"occupancy": "primary",
"down_payment_percent": 20,
"ltv": 80,
"vehicle_condition": "new",
"vehicle_year": 2024,
"vehicle_type": "car"
}
},
"current_offer": {
"provider_name": "Current Bank",
"amount": 300000,
"term_months": 360,
"rate": 6.75,
"apr": 6.85,
"fees": 2500
},
"preferences": {
"max_providers": 5,
"prefer_credit_unions": true,
"min_savings_monthly": 100,
"closing_timeline_days": 45,
"max_fees": 5000,
"include_institution_context": true,
"include_out_of_state": true
}
}Response
Decision recommendations with ranked actions
Example response
{
"request_id": "req_abc123xyz",
"decision_type": "financing",
"as_of": "2024-01-15T12:00:00.000Z",
"summary": {
"recommended_action": "shop_providers",
"confidence": 0.85,
"estimated_savings": {
"monthly": 245,
"total": 88200
},
"resolved_county": {
"county": "Norfolk",
"fips": "25021"
}
},
"actions": [
{
"type": "shop_providers",
"priority": 1,
"score": 95,
"why": [
"Found 5 credit unions with published APRs 0.5-0.75 percentage points below the credit-union median",
"A supplied credit score supports an estimated tier adjustment; final pricing and approval remain with the institution"
],
"tradeoffs": [
"Credit union membership may be required",
"Application process may take 30-45 days"
],
"expected_outcome": {
"rate_range": {
"min": 6.125,
"max": 6.375
},
"monthly_payment": 3025,
"monthly_payment_delta": -245,
"total_savings": 88200,
"break_even_months": 18
},
"offers": [
{
"rank": 1,
"credit_union_id": "schools-first-fcu",
"credit_union_name": "SchoolsFirst Federal Credit Union",
"credit_union_url": "https://www.schoolsfirstfcu.org",
"rateapi_url": "https://rateapi.dev/credit-unions/ca/schoolsfirst-federal-credit-union",
"state": "CA",
"product_type": "30-Year Fixed",
"product_name": "30-Year Fixed Rate Mortgage",
"display_name": "30-Year Fixed Mortgage",
"loan_program": "conventional",
"rate": 6.125,
"apr": 6.245,
"points": 0.5,
"monthly_payment": 3025,
"verification_confidence": 0.95,
"as_of": "2024-01-15T10:00:00.000Z",
"last_updated": "2024-01-15T10:00:00.000Z",
"estimated_monthly_savings": 245,
"estimated_total_savings": 88200,
"eligibility": {
"status": "likely_eligible",
"join_path": "Join the American Consumer Council (one-time $8 donation) during application",
"eligibility_type": "community",
"confidence": 0.9,
"matched_rule": {
"type": "county",
"detail": "Sacramento"
}
},
"institution_context": {
"source": "NCUA quarterly call report",
"cycle_date": "2026-03-31",
"members": 82000,
"locations": 8,
"total_assets": 1200000000,
"year_opened": 1935
}
}
],
"explanations": {
"method_version": "v1.0",
"signals": [
{
"name": "rate_differential",
"weight": 0.4,
"contribution": 38
}
]
}
}
],
"disclosures": [
"Rates shown are estimates based on publicly available data and may not reflect your actual approved rate",
"Monthly payment estimates do not include property taxes, insurance, or HOA fees"
]
}Changes
No recorded changes to this operation across all 1 revision of this API.