---
title: "PMI-removal / equity-timeline projection"
method: POST
path: "/v1/pmi-removal"
tags: ["Data & Analytics"]
---

# PMI-removal / equity-timeline projection

`POST /v1/pmi-removal`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/pmi-removal`
- Auth: API key in header `X-API-Key`

For low-down-payment borrowers (starting LTV > 80%): projects the month/date PMI can be cancelled (80% LTV) and is auto-terminated (78% LTV) on the original amortization schedule, the total PMI paid until then, and the extra monthly principal needed to reach 80% LTV sooner. Reuses the same amortization + PMI logic as /v1/monthly-cost. When no rate is supplied, the current best market rate for the state is resolved via the decision engine. LTV is based strictly on the original purchase price (no appreciation in v1).

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `home_price` number: Purchase/appraised price in dollars. Required unless loan_amount is given.
  - `down_payment` number: Cash down payment in dollars. Default 0.
  - `loan_amount` number: Optional explicit loan amount; overrides home_price - down_payment.
  - `rate` number: Annual interest rate (percent). If omitted, best market rate for the state is used.
  - `term_months` integer: Loan term in months. Default 360.
  - `state` string: 2-letter US state code for the market-rate lookup. Default CA.
  - `pmi_rate` number: Annual PMI as % of loan balance. Default 0.5.
  - `credit_score` integer: Optional borrower credit score used for the market-rate lookup.
  - `extra_monthly_payment` number: Optional extra monthly principal to model faster PMI cancellation. Default 0.

## Response `200`

PMI-removal timeline, total PMI paid, and acceleration scenarios.

- object
  - `home_price` string: Purchase price the schedule was computed from, formatted as a US dollar string.
  - `loan_amount` string: Loan amount in US dollars.
  - `down_payment` string: Down payment in US dollars.
  - `starting_ltv` string: Loan-to-value ratio at origination, formatted as a percentage string.
  - `rate_used` string: The rate the calculation was run at, as an annual percentage.
  - `rate_source` 'provided' | 'market' | 'fallback': Where the rate used in this calculation came from: `provided` if the caller supplied it, `market` if it was taken from live offers, `fallback` if neither was available and a default was used.
  - `monthly_pi` string: Monthly principal and interest, formatted as a US dollar string.
  - `monthly_pmi_initial` string: Monthly private mortgage insurance at the start, formatted as a US dollar string.
  - `pmi_applies` boolean: True when the loan-to-value ratio is high enough to require private mortgage insurance. When false the rest of the response is empty.
  - `pmi_drop` object: When PMI comes off: the month the borrower may request cancellation at 80% loan-to-value, and the month the servicer must terminate it automatically at 78%.
  - `total_pmi_paid` string: Everything paid in PMI before it comes off, formatted as a US dollar string.
  - `with_extra_payment` object, nullable: How much sooner PMI comes off if the borrower pays extra principal, or null when no extra payment was supplied.
  - `extra_needed` object[]: How much extra monthly principal it would take to reach 80% loan-to-value within 12 and within 24 months.
  - `assumed_defaults` object: Values filled in where the caller supplied none, so the result is reproducible.
  - `next_actions` object[]: Other endpoints or tools that are the natural next step from this result.
  - `disclosures` string[]: Statements that must be shown to a consumer alongside this result.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)