API reference

The LeaseWorth API

A self-serve API for the two things no lease competitor exposes: the deterministic effective-cost compute and normalized government incentive data. It does not resell scraped OEM lease offers.

Base URL · https://api.leaseworth.app

Authentication

All requests use an API key as a bearer token. Keys are issued per account; only a SHA-256 hash is stored server-side. Send the key in the Authorization header:

Authorization: Bearer lw_live_YOUR_KEY

A bad key returns 403; exceeding your monthly quota returns 429 with X-RateLimit-* headers; an expired subscription downgrades to the Free tier.

Endpoints

Method	Path	Description	Params
GET	/v1/incentives	Normalized incentive list. Filter by zip, state, technology, type, recency.	zip, state, technology, type, recent, limit
GET	/v1/incentives/{id}	A single incentive, full normalized detail.	—
GET	/v1/incentives/categories	Category / type enum (mirrors AFDC category-list).	—
POST	/v1/effective-cost	The proprietary compute: returns true effective monthly cost + lease ratio for one structure.	JSON body (see below)
POST	/v1/effective-cost/compare	Rank an array of structures by effective monthly cost — the honest $0-down vs high-down comparison as a service.	JSON array body
GET	/v1/vehicle-energy	Optional enrichment: MPGe / annual fuel cost / CO2 (pending EPA license verification).	year, make, model

`POST /v1/effective-cost`

Compute the true effective monthly cost of a single lease structure. Supply moneyFactor or apr, and residualPct or residualValue.

Request — copy & paste

curl -X POST https://api.leaseworth.app/v1/effective-cost \
  -H "Authorization: Bearer lw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msrp": 40000,
    "sellingPrice": 37000,
    "feesCap": 650,
    "residualPct": 0.60,
    "moneyFactor": 0.00125,
    "term": 36,
    "downPayment": 0,
    "taxMode": "none"
  }'

Response

{
  "apr": 3.00,
  "basePayment": 456.23,
  "effectiveMonthly": 456.23,
  "leaseRatio": 1.14,
  "dueAtSigning": 456.23,
  "totalCost": 16424.25,
  "breakdown": [
    { "label": "Adjusted cap cost", "amount": 37650.00 },
    { "label": "Residual value",    "amount": 24000.00 },
    { "label": "Depreciation / mo", "amount": 379.17 },
    { "label": "Rent charge / mo",  "amount": 77.06 },
    { "label": "Base payment / mo", "amount": 456.23 }
  ]
}

(Worked Example 1 from our published methodology — the same fixtures the compute engine is unit-tested against.)

Tiers & pricing

Tier	Price	Quota	Scope
Free	$0	200 / mo	AFDC incentives + effective-cost compute. Attribution required, rate-limited.
Starter	$19 / mo	5,000 / mo	+ compare endpoint, higher rate limit.
Pro	$79 / mo	50,000 / mo	+ enrichment, priority, historical snapshots.
Business	$249 / mo	500,000 / mo	+ SLA, bulk export, support.

Billed via Stripe on our own site. Quotas are metered per key per calendar month.

Errors & rate limits

200	Success.
400	Invalid body (e.g. missing term, or neither money factor nor APR).
403	Missing or invalid API key.
429	Monthly quota exceeded. See `X-RateLimit-Reset`.

Data licensing & attribution

AFDC (U.S. DOE Alternative Fuels Data Center) is unrestricted — it powers the commercial core of every paid tier.
DSIRE records are licensed CC BY-SA 4.0. They appear on the Free tier only, always with the required attribution, and are kept out of the proprietary paid dataset. The “DSIRE®” mark is not used.
The effective-cost compute has no external data dependency — it is the deterministic, fully unit-tested engine described in our public methodology.

Data freshness is published per response and on each incentive page.