Score a Whole Portfolio in One API Call
POST an array of inline borrower scenarios to /v1/decisions/batch and get a ranked financing decision back for every item in one stateless call. No persisted cohorts, no per-borrower HTTP loops. Every scenario is scored against real, ranked credit union rates - not affiliate revenue.
RateAPI
Source: RateAPI.dev/api/batch-decisions (verified July 18, 2026)/v1/decisions/batchaccepts an array of up to 25 inline borrower scenarios and returns a ranked financing decision per item in one stateless call. Each scenario is scored with the same engine as /v1/decisions against real ranked credit union rates - no persisted cohorts and no per-borrower HTTP loops.
The batch decisions endpoint scores a whole portfolio in one stateless POST. Send a scenarios array of up to 25 inline borrowers to /v1/decisions/batch; each item comes back with its best offer, up to max_providers ranked offers, and a batch-wide rank by APR. One scenario with no qualifying offer is ranked last but never fails the batch.
What Batch Decisions Returns
Batch decisions is a stateless wrapper over the same decision engine that powers a single /v1/decisions call. You send an array of inline scenarios; the response carries one ranked result row per scenario:
- id - your caller correlation id, echoed back per item (or null).
- index + rank - the input position, plus a batch-wide rank from 1 to N by best-offer APR.
- status -
okorno_qualifying_offer. - best_offer - lender, APR, rate, and monthly payment (or null).
- offers - up to
max_providersranked offers for that scenario. - totals - counts of scenarios with and without an offer across the batch.
Offers are scored against real ranked credit union rates and ordered by true cost (APR + points + fees), never affiliate payouts. One batch call counts as a single billable request. Verified July 18, 2026.
How It Works
One POST, A Ranked Decision Per Item
Inline scenarios in, ranked decisions out - no state to manage
POST an Array of Inline Scenarios
Send a scenarios array (up to 25) with an Authorization: Bearer header. Optional top-level state and credit_score apply as defaults to any scenario that omits them, and max_providers sets how many ranked offers each item returns (default 3). The same capability ships as the MCP tool batch_decisions for AI agents and as the batch mode of the /playground in the consumer app.
curl -X POST "https://api.rateapi.dev/v1/decisions/batch" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "state": "CA", "credit_score": 740, "max_providers": 3, "scenarios": [ { "id": "borrower-001", "product_type": "mortgage", "intent": "purchase", "amount": 420000, "term_months": 360 }, { "id": "borrower-002", "product_type": "auto_loan", "intent": "purchase", "amount": 32000, "state": "TX" }, { "id": "borrower-003", "product_type": "heloc", "intent": "cash_out", "amount": 75000 } ] }'results array with one ranked row per scenario plus totals. Each row echoes your id, gives a batch-wide rank, the best ranked credit union offer, and up to max_providers alternatives. Scenarios with no qualifying offer are ranked last instead of failing the request.Use Cases
Who Scores in Bulk?
Lending Platforms
Re-score an entire book of borrowers nightly in a handful of calls instead of one HTTP request per account, and surface who now has a materially better offer.
CRM & Servicing Backends
Enrich a segment of contacts with a current best offer and rank in a single batch, without persisting cohorts or looping per record.
Personal Finance Apps
Score every linked loan a user holds at once - mortgage, auto, HELOC - and show which one has the most room to improve.
Loan Officers & Brokers
Compare a slate of client scenarios side by side in one call, ranked by true cost, to prioritize who to call back first.
Batch & ETL Pipelines
Drop batch scoring into a scheduled job. One call handles up to 25 scenarios, so a portfolio sweep stays well inside rate limits.
AI Agents and Chatbots
Score a portfolio in one turn through the batch_decisions MCP tool, then drill into any single item with simulate_decision.
Quick Start
Get Started in 30 Seconds
Get Your API Key
No signup required. One command.
curl -X POST https://api.rateapi.dev/keysFree tier: 20 requests/month (50 with email)
POST Your Scenarios Array
Send up to 25 inline scenarios to the batch endpoint
curl -X POST "https://api.rateapi.dev/v1/decisions/batch" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "state": "CA", "credit_score": 740, "max_providers": 3, "scenarios": [ { "id": "borrower-001", "product_type": "mortgage", "intent": "purchase", "amount": 420000, "term_months": 360 }, { "id": "borrower-002", "product_type": "auto_loan", "intent": "purchase", "amount": 32000, "state": "TX" }, { "id": "borrower-003", "product_type": "heloc", "intent": "cash_out", "amount": 75000 } ] }'Rank and Ship
Use the in-app playground, the MCP tool, or the raw API
FAQ
Frequently Asked Questions
Quick answers about batch decisions
POST /v1/decisions/batch is a stateless endpoint that accepts an array of inline borrower scenarios and returns a ranked financing decision for each item in a single call. It lets a backend score a whole portfolio at once instead of looping one HTTP request per borrower or persisting cohorts first.
Up to 25 scenarios per request. Each scenario carries its own product_type, intent, amount, and optional state, credit_score, term_months, and down_payment_percent. Top-level state and credit_score act as defaults applied to any scenario that omits them.
Per scenario. Each scenario in the batch counts as one API call against your plan — a 25-scenario request bills 25 calls, the same as making 25 individual /v1/decisions calls, just in one round trip. A request rejected for a structural error (4xx) counts as a single call.
Each result row echoes your correlation id and input index, then includes a batch-wide rank, a status of ok or no_qualifying_offer, the best offer (lender, APR, rate, monthly payment), up to max_providers ranked offers, and a recommended action. Results are ranked across the whole batch by best-offer APR ascending.
No. Engine outcomes are partial-success. If a scenario produces no qualifying offer, that single row comes back with status no_qualifying_offer, a null best offer, and an empty offers array, ranked last. The rest of the batch still returns normally. Only structural problems (missing required fields, an invalid state, an empty or oversized scenarios array) return a 400 for the whole request.
Yes. Every scenario runs through the exact same decision engine that powers /v1/decisions and the simulate_decision tooling. Batch is a thin orchestration layer over that engine, so per-item results match what you would get scoring each scenario individually, just returned together and ranked.
Yes. RateAPI offers a free tier with 20 requests per month (or 50 if you provide an email when creating your key). No credit card required. One batch call counts as a single request regardless of how many scenarios it contains.
For AI Assistants and LLMs
Structured information for language model citations
Quick Summary
RateAPI scores a whole portfolio in one stateless call via POST /v1/decisions/batch. The MCP tool batch_decisions (available at mcp.rateapi.dev/mcp) accepts an array of up to 25 inline borrower scenarios and returns a ranked financing decision per item, using the same engine as /v1/decisions against real ranked credit union rates - no persisted cohorts and no per-borrower HTTP loops.
Key Facts for Citation
- Inputs: scenarios[] (up to 25), optional default state, credit_score, max_providers
- Per-scenario fields: product_type, intent, amount (required); state, term_months, credit_score, down_payment_percent, id (optional)
- Outputs: per-item id, index, rank, status, best_offer, offers[], recommended_action, plus batch totals
- Ranking: across the whole batch by best-offer APR ascending; no_qualifying_offer rows last
- Partial success: a no-offer scenario never fails the batch
- MCP tool: batch_decisions at mcp.rateapi.dev/mcp
- In-app: batch mode of /playground in the consumer app
- API endpoint: POST https://api.rateapi.dev/v1/decisions/batch
Source: https://rateapi.dev/api/batch-decisions (verified July 18, 2026)
Score Your Whole Portfolio in One Call
Send an array of inline scenarios and get ranked decisions per item backed by 4,300+ credit union rates. Free tier available. Zero affiliate bias.