---
title: "Batch Decisions API - Score a Whole Portfolio in One Call"
description: "POST an array of inline borrower scenarios and get ranked financing decisions per item in one stateless API call. No persisted cohorts, no per-borrower HTTP loops. Powered by real, ranked credit union rates."
canonical: "https://rateapi.dev/api/batch-decisions"
last-updated: "2026-09-27"
source: "https://rateapi.dev/llms.txt"
---

# 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.

[Open the calculator in the dashboard →](https://app.rateapi.dev/playground) Get a Free API Key

Up to 25 Scenarios per Call Ranked by True Cost Zero Affiliate Bias

Last updated: September 26, 2026

[Home](https://rateapi.dev/) / Batch Decisions API

RateAPI `/v1/decisions/batch` accepts 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.

> Source: [RateAPI.dev/api/batch-decisions](https://rateapi.dev/api/batch-decisions) (verified September 26, 2026)

Quick Answer

**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** - `ok` or `no_qualifying_offer` .
- **best_offer** - lender, APR, rate, and monthly payment (or null).
- **offers** - up to `max_providers` ranked 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 September 26, 2026.

1 Call

Whole Portfolio

25

Scenarios per Request

3,700+

Lenders Ranked

5

Product Types

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 batch portfolio scoring

Copy

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 }

]

} '

Returns a `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

1

### Get Your API Key

No signup required. One command.

cURL terminal

Copy

RATEAPI_ENROLLMENT_ID = "${RATEAPI_ENROLLMENT_ID:-$(node -e 'console.log(crypto.randomUUID())')}" ; curl - X POST https://api.rateapi.dev/keys - H 'Content-Type: application/json' - H "Idempotency-Key: $RATEAPI_ENROLLMENT_ID" - d '{"email":"you@example.com","source":"curl-batch-decisions"}'

Free tier: 20 requests/month (email required)

2

### POST Your Scenarios Array

Send up to 25 inline scenarios to the batch endpoint

cURL terminal

Copy

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 }

]

} '

3

### Rank and Ship

Use the in-app playground, the MCP tool, or the raw API

[Open the calculator in the dashboard →](https://app.rateapi.dev/playground) [View API Docs](https://api.rateapi.dev/)

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.

What is the batch decisions endpoint?

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. Fixed-rate mortgages (product_type mortgage, with term_months selecting 15- or 30-year) and adjustable-rate mortgages (product_type mortgage_arm) are scored as separate markets. Top-level state and credit_score act as defaults applied to any scenario that omits them.

How many scenarios can I send in one call?

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.

How is the batch endpoint billed?

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.

What does it return per scenario?

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.

Does one bad scenario fail the whole batch?

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.

Is the math the same as the single decisions endpoint?

Yes. RateAPI offers a free tier with 20 requests per month. No credit card required. One batch call counts as a single request regardless of how many scenarios it contains.

Is there a free tier?

## 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)
- **product_type values:** mortgage (fixed-rate), mortgage_arm (adjustable-rate), auto_loan, heloc, personal_loan, student_loan, credit_card, equipment_loan. Fixed and adjustable mortgages are ranked as separate markets — an ARM intro rate sits below a comparable fixed rate, so one blended list would put every ARM on top and call it cheaper
- **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](https://rateapi.dev/api/batch-decisions) (verified September 26, 2026)

## Score Your Whole Portfolio in One Call

Send an array of inline scenarios and get ranked decisions per item backed by 3,700+ credit union rates. Free tier available. Zero affiliate bias.

[Open the calculator in the dashboard →](https://app.rateapi.dev/playground) Get a Free API Key

RateAPI

RateAPI Routes turns confirmed customer facts into source-backed shortlists of published products from 3,700+ tracked US credit unions. Every promoted route keeps its membership and price evidence.

[Get API key →](https://rateapi.dev/api-key) [Sign in](https://app.rateapi.dev)

### Build

- [RateAPI Routes →](https://rateapi.dev/routes)
- [Product Matching API](https://rateapi.dev/financial-product-eligibility-api)
- [Membership Eligibility API](https://rateapi.dev/api/eligibility)
- [Rate Query API](https://rateapi.dev/rates-api)
- [Decision API](https://rateapi.dev/api/reference)
- [Batch Decisions API](https://rateapi.dev/api/batch-decisions)

### Deliver

- [Developer Portal →](https://rateapi.dev/developers)
- [Create a free API key](https://rateapi.dev/api-key)
- [REST API docs](https://api.rateapi.dev/)
- [OpenAPI spec](https://api.rateapi.dev/openapi.json)
- [MCP Server](https://rateapi.dev/mcp)
- [Widget builder](https://rateapi.dev/widget-builder)
- [RateAPI Routes widget](https://rateapi.dev/widget-docs/routes)
- [Market Rates widget](https://rateapi.dev/widget-docs/rates)
- [Webhooks](https://api.rateapi.dev/webhooks)
- [Versioning & deprecation](https://rateapi.dev/deprecation-policy)
- [GitHub](https://github.com/rate-api)

### Solutions

- [Personal finance apps](https://rateapi.dev/use-cases/personal-finance-apps)
- [AI purchase advisors](https://rateapi.dev/use-cases/ai-purchasing-tools)
- [AI agents](https://rateapi.dev/use-cases/ai-agents)
- [Car buying platforms](https://rateapi.dev/use-cases/car-buying-platforms)
- [Credit unions](https://rateapi.dev/for-credit-unions)
- [Loan officers](https://rateapi.dev/use-cases/loan-officers)
- [Rate data for ALM](https://rateapi.dev/alm-rate-data)

### Trust

- [Data coverage](https://rateapi.dev/data-coverage)
- [Rate methodology](https://rateapi.dev/methodology)
- [Eligibility methodology](https://rateapi.dev/eligibility-methodology)
- [Transparency](https://rateapi.dev/transparency)
- [Independence](https://rateapi.dev/independence)
- [Corrections](https://rateapi.dev/corrections)
- [Pricing](https://rateapi.dev/pricing)
- [About](https://rateapi.dev/about)
- [Contact](https://rateapi.dev/contact)
- Talk to a human

### Inspect the data behind the API

Public data explorer

- [Current mortgage rates](https://rateapi.dev/current-mortgage-rates)
- [Current auto rates](https://rateapi.dev/current-auto-loan-rates)
- [Current CD rates](https://rateapi.dev/current-cd-rates)
- [Current HELOC rates](https://rateapi.dev/current-heloc-rates)
- [Current personal loan rates](https://rateapi.dev/current-personal-loan-rates)
- [Mortgage rates](https://rateapi.dev/mortgage-rates)
- [Refinance rates](https://rateapi.dev/refinance-rates)
- [Auto loan rates](https://rateapi.dev/auto-loan-rates)
- [RV loan rates](https://rateapi.dev/rv-loan-rates)
- [Boat rates](https://rateapi.dev/boat-loan-rates)
- [Motorcycle rates](https://rateapi.dev/motorcycle-loan-rates)
- [HELOC rates](https://rateapi.dev/heloc-rates)
- [Personal loan rates](https://rateapi.dev/personal-loan-rates)
- [Credit card rates](https://rateapi.dev/credit-card-rates)
- [Deposit rates](https://rateapi.dev/deposit-rates)
- [CD rates](https://rateapi.dev/cd-rates)
- [Savings rates](https://rateapi.dev/savings-rates)
- [Money market rates](https://rateapi.dev/money-market-rates)
- [Credit union directory](https://rateapi.dev/credit-unions)
- [Who can join](https://rateapi.dev/who-can-join)
- [Mortgage benchmark](https://rateapi.dev/mortgage-rate-benchmark)
- [Auto benchmark](https://rateapi.dev/auto-loan-rate-benchmark)
- [HELOC benchmark](https://rateapi.dev/heloc-rate-benchmark)
- [Personal loan benchmark](https://rateapi.dev/personal-loan-rate-benchmark)
- [CD benchmark](https://rateapi.dev/cd-rate-benchmark)
- [Credit union rate index](https://rateapi.dev/credit-union-rate-index)
- [Deposit beta](https://rateapi.dev/deposit-beta)
- [Credit unions vs banks: mortgage](https://rateapi.dev/compare/credit-union-vs-bank-rates)
- [Credit unions vs banks: auto](https://rateapi.dev/compare/credit-union-vs-bank-auto-loan-rates)
- [Credit unions vs banks: HELOC](https://rateapi.dev/compare/credit-union-vs-bank-heloc-rates)
- [Credit unions vs banks: CD](https://rateapi.dev/compare/credit-union-vs-bank-cd-rates)
- [Mortgage rate API comparison](https://rateapi.dev/compare/mortgage-rate-apis)
- [Rate datasets](https://rateapi.dev/credit-union-rate-dataset)

© 2026 RateAPI · US credit unions only · Published pricing is not approval.

[Privacy](https://rateapi.dev/privacy) [Terms](https://rateapi.dev/terms) [llms.txt](https://rateapi.dev/llms.txt)

---

Source: https://rateapi.dev/api/batch-decisions
Rate data API: https://api.rateapi.dev · OpenAPI: https://api.rateapi.dev/openapi.json · MCP: https://mcp.rateapi.dev/mcp