Auto Loan Decisions

Score a direct or indirect auto loan in real time. Combines cash-flow underwriting with LTV-aware risk grading and vehicle valuation. Returns a TILA-compliant approval, a counter-offer, or a decline with ECOA reason codes.

Create a decision

POST/v1/decisions/auto-loan

Request body

Field	Type	Description
`consumer`Required	`object`	Identifies the consumer. See Consumer object below. Either consumer_id (for returning customers) OR full PII fields (for new consumers).
`loan`Required	`object`	The loan terms requested. See Loan object below.
`vehicle`Required	`object`	The vehicle being financed. Used for LTV and valuation. See Vehicle object below.
`dealer`	`object`	For indirect (dealer-originated) loans only. Supplies markup and fee for TILA calculation. Omit for direct loans.

Consumer object

Field	Type	Description
`consumer_id`	`uuid`	UUID of an existing consumer in your tenant. Skip the rest of the consumer fields if provided.
`first_name`	`string`	Required for new consumers.
`last_name`	`string`	Required for new consumers.
`email`	`string`	Required for new consumers. Used for verification flows.
`phone`	`string`	E.164 format. Used for SMS verification when KYC tier is enhanced/hard.
`dob`	`string`	ISO 8601 date (YYYY-MM-DD). Required for new consumers.
`ssn_last4`	`string`	Last 4 digits of SSN. Required for enhanced/hard KYC. Encrypted at rest.
`address`	`object`	Mailing address. line1, city, state, zip required for new consumers.

Loan object

Field	Type	Description
`amount`Required	`decimal`	Requested loan amount. Use a string to avoid floating-point issues.
`currency`Required	`string`	ISO 4217 currency code. Currently only USD is supported.
`term_months`Required	`integer`	Requested loan term. Auto loans support 24 to 84 months. May be capped by risk grade.
`loan_purpose`	`string`	vehicle_purchase or refinance. Defaults to vehicle_purchase.

Vehicle object

Field	Type	Description
`vin`	`string`	17-character VIN. Enables precise valuation when supplied.
`year`Required	`integer`	Model year.
`make`Required	`string`	Vehicle make (e.g., Toyota).
`model`Required	`string`	Vehicle model (e.g., RAV4).
`mileage`Required	`integer`	Odometer reading. Affects valuation and depreciation.
`condition`Required	`string`	new or used.
`sale_price`Required	`decimal`	Agreed sale price of the vehicle. Used for LTV calculation.

Dealer object (indirect loans)

Field	Type	Description
`dealer_id`	`string`	Your identifier for the originating dealer. Used for reporting and dealer network reconciliation.
`markup_pct`	`decimal`	Dealer rate markup as a percentage. Added to the base APR and reflected in the TILA disclosure.
`flat_fee_usd`	`decimal`	Flat dealer fee in USD, if any. Included in the finance charge.

Example request

Request body

{
  "consumer": {
    "first_name": "Diane",
    "last_name": "Okafor",
    "email": "diane@example.com",
    "phone": "+15559876543",
    "dob": "1985-03-22",
    "ssn_last4": "8842",
    "address": {
      "line1": "44 Lakeshore Dr",
      "city": "Chicago",
      "state": "IL",
      "zip": "60601"
    }
  },
  "loan": {
    "amount": 28000.00,
    "currency": "USD",
    "term_months": 60,
    "loan_purpose": "vehicle_purchase"
  },
  "vehicle": {
    "vin": "1HGCM82633A004352",
    "year": 2022,
    "make": "Toyota",
    "model": "RAV4",
    "mileage": 24500,
    "condition": "used",
    "sale_price": 29500.00
  },
  "dealer": {
    "dealer_id": "dlr_8842",
    "markup_pct": 1.5,
    "flat_fee_usd": 299.00
  }
}

Vehicle valuation is advisory

AltFiScore looks up an independent vehicle valuation to inform the LTV gate. This valuation never persists to the consumer's feature set and never affects the underlying credit score — it only bounds the approvable amount. See the auto loan product page for details.

Response

The response status depends on the KYC tier AltFiScore assigns. Auto loans typically trigger enhanced KYC given the larger amounts. Enhanced and hard-tier decisions return needs_consumer_action with a URL the consumer must visit to complete verification.

Approved

Status complete with outcome approved. The response includes the ltv_pct, an independent vehicle_valuation block, and a full tila_disclosure.

200 OK · approved

{
  "decision_id": "b21c9f04-7a3e-4d19-9c88-2f4e6a1b7c33",
  "application_id": "b21c9f04-7a3e-4d19-9c88-2f4e6a1b7c33",
  "status": "complete",
  "kyc_tier": "enhanced",
  "kyc_status": "matched",
  "outcome": "approved",
  "score": 728,
  "risk_grade": "B",
  "approved_amount": "28000.00",
  "currency": "USD",
  "apr": "8.75",
  "term_months": 60,
  "monthly_payment": "578.43",
  "ltv_pct": "94.9",
  "vehicle_valuation": {
    "source": "vehicle_databases",
    "retail_value": "29800.00",
    "loan_value": "27200.00"
  },
  "tila_disclosure": {
    "amount_financed": "28000.00",
    "finance_charge": "6705.80",
    "total_of_payments": "34705.80",
    "apr": "8.75",
    "payment_frequency": "monthly"
  },
  "decline_reasons": [],
  "expires_at": "2026-05-15T20:30:20.566665Z"
}

Counter-offer (referred)

When the requested amount or term exceeds the limits for the assigned risk grade, AltFiScore returns outcome referred with a counter_offer. Present the counter-offer to the consumer; they can accept the adjusted amount, APR, and term.

200 OK · counter-offer

{
  "decision_id": "c33d0a15-...",
  "application_id": "c33d0a15-...",
  "status": "complete",
  "outcome": "referred",
  "score": 662,
  "risk_grade": "C",
  "counter_offer": {
    "is_viable": true,
    "offered_amount": "24000.00",
    "offered_apr_pct": "12.50",
    "offered_term_months": 48,
    "monthly_payment": "640.11",
    "reason": "Your requested amount of $28,000 exceeds the maximum LTV for Grade C borrowers on this vehicle (max $24,000)."
  },
  "decline_reasons": []
}

Declined

Status complete with outcome declined. The decline_reasons array contains ECOA-compliant codes. See compliance for guidance on adverse action handling.

200 OK · declined

{
  "decision_id": "d44e1b26-...",
  "application_id": "d44e1b26-...",
  "status": "complete",
  "outcome": "declined",
  "score": 588,
  "risk_grade": "D",
  "decline_reasons": [
    { "code": "AA-01", "reason": "Insufficient cash flow stability over the last 90 days." },
    { "code": "AA-14", "reason": "Loan-to-value ratio exceeds program limits for this credit tier." }
  ]
}

A decline is still a 200

The HTTP status indicates whether the API call succeeded, not whether the consumer was approved. A successfully-evaluated decline is HTTP 200 with outcome: "declined". See the errors page for genuine error cases.

Response fields

Field	Type	Description
`decision_id`	`uuid`	Unique identifier for this decision. Store for reconciliation and later lookup.
`application_id`	`uuid`	Identifier for the underlying application. Typically equals decision_id for first-time decisions.
`status`	`string`	complete or needs_consumer_action.
`kyc_tier`	`string`	soft, enhanced, or hard. Indicates the verification depth applied.
`kyc_status`	`string`	matched, pending, or skipped.
`outcome`	`string`	approved, declined, or referred. null when status is needs_consumer_action.
`score`	`integer`	AltFiScore from 300 to 1000.
`risk_grade`	`string`	Letter grade A+ through D derived from the score.
`approved_amount`	`decimal`	String. The amount AltFiScore approved. May be less than requested for risk-based offers.
`apr`	`decimal`	String. Annual percentage rate as a percentage, inclusive of any dealer markup.
`term_months`	`integer`	Approved term in months. May be shorter than requested.
`monthly_payment`	`decimal`	String. Calculated monthly installment.
`ltv_pct`	`decimal`	String. Loan-to-value ratio as a percentage.
`vehicle_valuation`	`object`	Independent valuation: { source, retail_value, loan_value }. Advisory only.
`tila_disclosure`	`object`	TILA Reg Z disclosure block ready to display to the consumer.
`counter_offer`	`object`	Present when outcome is referred. Contains adjusted amount, APR, term, and reason.
`decline_reasons`	`array`	Array of { code, reason } objects. Populated when outcome is declined or referred.
`expires_at`	`timestamp`	ISO 8601 timestamp. The offer expires at this time.

Poll a decision

GET/v1/decisions/auto-loan/{decision_id}

Returns the current state of a previously-created decision. Idempotent and safe to call repeatedly. Recommended polling interval: 2–3 seconds.

Poll a pending decision

curl 'https://api.altfiscore.com/v1/decisions/auto-loan/b21c9f04-7a3e-4d19-9c88-2f4e6a1b7c33' \
  -H 'Authorization: Bearer altfi_test_YOUR_KEY'

Use idempotency

Both POST and GET endpoints are safe to retry. The POST endpoint with the same Idempotency-Key returns the cached decision. The GET endpoint is naturally idempotent.

Errors

Returns standard HTTP error codes. The full catalog is in the errors reference. Most common errors for this endpoint:

400 invalid_request — required field missing (e.g., vehicle.sale_price)
401 invalid_api_key — bad or missing API key
409 idempotency_conflict — same idempotency key with a different body
422 unprocessable_entity — request is well-formed but fails business rules (e.g., term exceeds 84 months)

Next steps

Review the auto loan product page for rate bands and LTV caps
Set up idempotent retries
Handle declines with the compliance guide