--- title: "Collateral Score" description: "Assess vehicle collateral by VIN with current values, depreciation forecasts, risk flags, an A–D risk tier, and suggested maximum LTV. Includes single and batch scoring." canonical_url: "https://docs.carsxe.com/docs/products/collateral-score" markdown_url: "https://docs.carsxe.com/docs/products/collateral-score.md" last_updated: "1980-01-01" x_farming_labs_generated_preamble: true agent: task: "Assess vehicle collateral using a VIN, mileage and US ZIP code, or re-score a portfolio asynchronously." outcome: "A successful score returns vehicle values, forecast provenance, risk flags, lending guidance and explicit data gaps." prerequisites: - "A CarsXE API key with Collateral Score enabled by sales." - "A 17-character VIN, integer mileage and five-digit US ZIP code." verification: - "POST the example VIN and confirm success is true; inspect data_gaps and confidence before using the recommendation." - "For a batch, poll with batch_id until completed and inspect each vehicle result." failureModes: - symptom: "The endpoint returns 404." resolution: "Read the message: ask sales to enable account access, or use a VIN with available market value data." - symptom: "A forecast or risk signal is null." resolution: "Treat it as unassessed, inspect data_gaps and provenance, and apply your own review policy." --- # Collateral Score URL: /docs/products/collateral-score LLM index: /llms.txt Description: Assess vehicle collateral by VIN with current values, depreciation forecasts, risk flags, an A–D risk tier, and suggested maximum LTV. Includes single and batch scoring. Related: /docs/products/market-value, /docs/products/vehicle-history, /docs/products/recalls ## Agent Contract Task: Assess vehicle collateral using a VIN, mileage and US ZIP code, or re-score a portfolio asynchronously. Outcome: A successful score returns vehicle values, forecast provenance, risk flags, lending guidance and explicit data gaps. ### Prerequisites - A CarsXE API key with Collateral Score enabled by sales. - A 17-character VIN, integer mileage and five-digit US ZIP code. ### Verification - POST the example VIN and confirm success is true; inspect data_gaps and confidence before using the recommendation. - For a batch, poll with batch_id until completed and inspect each vehicle result. ### Failure Modes - The endpoint returns 404. — Recovery: Read the message: ask sales to enable account access, or use a VIN with available market value data. - A forecast or risk signal is null. — Recovery: Treat it as unassessed, inspect data_gaps and provenance, and apply your own review policy. Task: Assess vehicle collateral by VIN or re-score a portfolio with Collateral Score. Related: /docs/products/collateral-score, /docs/products/market-value, /docs/products/vehicle-history # Collateral Score Combine mileage and region-adjusted market values, depreciation forecasts, title and recall signals, and an explainable collateral risk tier in one response. This is a vehicle assessment: borrower credit checks and loan approval remain in your system. Collateral Score is available on request. [Contact sales](https://carsxe.com/contact) to enable it for your account. A valid API key and account access are required, including for the free example VIN `3TMKB5FNXRM012539`. ## Who uses this API Lenders, credit unions, auto finance platforms and portfolio servicing teams use Collateral Score for origination reviews, collateral monitoring and loan-book re-scoring. ## Use cases - **Origination:** compare available collateral values and risk signals before funding. - **Loan-term review:** inspect projected retail value at maturity alongside your own lending policy. - **Portfolio monitoring:** re-score up to 500 vehicles per batch and route flagged results for review. ## Score one vehicle Send `POST /v1/vehicle/collateral-score` with your API key in the `key` query parameter and a JSON body. Open the same interactive playground used by the other product guides: ### Parameters | Parameter | Location | Required | Description | | ------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------- | | `key` | Query | Yes | Your CarsXE API key with Collateral Score enabled. | | `vin` | JSON body | Yes | A 17-character VIN. | | `mileage` | JSON body | Yes | Integer from `0` to `1000000`, in miles. | | `zip` | JSON body | Yes | Five-digit US ZIP as a string. Its state sets the regional value adjustment; preserve leading zeros. | | `loan_term_months` | JSON body | No | Integer from `1` to `96`. Adds `depreciation_forecast.at_loan_maturity` when supplied. | ```bash curl -X POST 'https://api.carsxe.com/v1/vehicle/collateral-score?key=YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"vin":"3TMKB5FNXRM012539","mileage":42000,"zip":"20878","loan_term_months":48}' ``` ```javascript const response = await fetch( `https://api.carsxe.com/v1/vehicle/collateral-score?key=${encodeURIComponent(process.env.CARSXE_API_KEY)}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ vin: "3TMKB5FNXRM012539", mileage: 42000, zip: "20878", loan_term_months: 48, }), }, ); const score = await response.json(); if (!response.ok) throw new Error(score.message); console.log(score.lending_recommendation, score.data_gaps); ``` Keep API keys in your server environment. The example VIN is free and never counted; other VINs use your account's Collateral Score allowance. ### Read the response | Field | Meaning | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `success`, `input`, `timestamp` | Success indicator, submitted inputs and response timestamp. | | `vin`, `vehicle` | VIN and available year, make, model and trim. | | `current_values` | Average-condition retail, wholesale and trade-in values, MSRP, publication date and valuation confidence. Mileage and regional adjustments are applied when available. | | `depreciation_forecast` | Retail-based projections at 12, 24, 36 and 48 months, plus maturity if requested. Includes curve source, key, minimum sample size and refresh date. | | `depreciation_velocity` | Annual depreciation and percentile versus the vehicle's segment, with segment labels, peer count and interpretation. Lower percentiles indicate slower depreciation. | | `risk_flags` | Salvage, flood, lemon/buyback and other title brands, odometer anomalies, total-loss reports and open high-severity recalls. `total_flags` counts known raised flags. | | `lending_recommendation` | A–D `risk_tier`, `suggested_max_ltv`, `manual_review_recommended`, reasons, rationale and recommendation confidence. | | `data_gaps` | Signals the assessment could not see. Read these before using the recommendation. | This illustrative response excerpt shows the shape, with synthetic values; it is not a live appraisal: ```json { "success": true, "vin": "3TMKB5FNXRM012539", "current_values": { "retail": 32000, "wholesale": 28500, "trade_in": 27000, "msrp": 35000, "confidence": "high", "publish_date": "2026-10-01" }, "lending_recommendation": { "risk_tier": "A", "suggested_max_ltv": 120, "manual_review_recommended": false, "reasons": [ "No risk flags raised.", "Depreciates slower than 75% of its segment." ], "rationale": "No risk flags raised. Depreciates slower than 75% of its segment. Not assessed: accident history.", "confidence": "high" }, "data_gaps": ["accident_history"] } ``` The [interactive API reference](/api-reference/collateral-score/collateral-score) contains the complete response schema, including nested forecasts and flags. ## Interpret risk and missing data The current rules return suggested maximum LTV in percentage points: `120` means 120%. Tiers are evaluated from most severe to least severe; reasons identify the rules that fired. | Tier | Suggested maximum LTV | Example triggers | | ---- | --------------------- | -------------------------------------------------------------------------------- | | A | 120% | No higher-tier rule fired on the available inputs. | | B | 110% | One risk flag or depreciation percentile from 50 through 75. | | C | 95% | Other title issues, two or more risk flags, or depreciation percentile above 75. | | D | 80% | Salvage, flood, lemon/buyback or odometer anomaly. Manual review is recommended. | These are collateral recommendations, not loan approvals. Apply your own policy and review the reasons, confidence and gaps together. - **Unknown is `null`, not `false`.** An unavailable signal cannot trigger its rule. A tier of A does not prove that all risks were assessed. - **Accident history is not currently available.** `risk_flags.accident_count` is `null` and `accident_history` is listed in `data_gaps`. Title-brand records do not provide accident history. - **Forecasts are bounded by the curve.** Projections beyond available data return `null`; the API never extrapolates. `curve_source` identifies a model curve or a segment fallback. The base is always current retail value. - **Confidence has separate meanings.** Valuation confidence reflects value completeness and mileage adjustment. Recommendation confidence reflects assessed data gaps. Accident-history and depreciation-curve gaps do not alone lower recommendation confidence, so always inspect `data_gaps` even when confidence is `high`. - **Partial coverage is explicit.** Gaps can include `vehicle_history`, `recalls`, `depreciation_curve` and `segment_percentile`. A recalls outage produces a gap instead of failing the whole score. ## Batch portfolio scoring Submit 1–500 vehicles to `POST /v1/vehicle/collateral-score/batch`. Each vehicle uses the same inputs as a single score. Only one batch can run per account at a time. ```bash curl -X POST 'https://api.carsxe.com/v1/vehicle/collateral-score/batch?key=YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"vehicles":[{"vin":"3TMKB5FNXRM012539","mileage":42000,"zip":"20878","loan_term_months":48}]}' ``` A successful submission returns `202` with `success`, `batch_id`, `status` and `total`. Save `batch_id` and poll using the same account's key: ```bash curl -G 'https://api.carsxe.com/v1/vehicle/collateral-score/batch' \ --data-urlencode 'key=YOUR_API_KEY' \ --data-urlencode 'batch_id=YOUR_BATCH_ID' ``` Poll until `status` is `completed`, then inspect `succeeded`, `failed` and the per-vehicle `results`. A completed batch can include failures; check each result rather than assuming all vehicles scored. ### Completion webhook Optionally include `webhook_url` in the submission JSON. It must be a public HTTPS URL; redirects are not followed. Completion sends event `collateral_score.batch.completed` with `batch_id`, `status`, `total`, `succeeded`, `failed` and `timestamp`. Retrieve the actual vehicle results with the authenticated batch-status request. Webhooks are sent once and are not retried. Keep polling as a fallback and use the authenticated status endpoint to verify completion. ### Batch billing The example VIN is free. Usage is checked up front for every other submitted vehicle. Plans that allow overage are billed one Collateral Score call per successfully scored vehicle when the batch completes. Hard-capped and prepaid plans are charged for every non-example vehicle at submission, before the `202` response. ## Errors | Status | Meaning and recovery | | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `400` | Invalid body, VIN, mileage, ZIP, loan term, batch vehicle list, webhook URL or batch ID. Correct the input. | | `401` | Missing or invalid API key. | | `404` | Account access is not enabled, no market value exists for the VIN, or a requested batch was not found. Inspect `message`. | | `409` | A batch is already processing for this account. Wait for it to finish before submitting another. | | `429` | Usage allowance is insufficient. For a batch, quota is checked against all non-example vehicles. | | `500` | Internal server error. | | `502` | Market value or title-history provider failure. Retry only when `retryable: true` is present, respecting `Retry-After`. | | `503` | Collateral Score is temporarily switched off. Nothing is charged; retry later. | | `504` | An upstream request timed out. Respect `Retry-After` before retrying. | See the [Errors guide](/docs/guides/errors) and the operation-specific [API reference](/api-reference/collateral-score/collateral-score) for response details. ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).