# Get a home's deed and mortgage history

Source: https://help.ruuster.com/api/public-records-history

```http
GET https://api.ruuster.com/v1/public-records/{recordId}/history
```

Every recorded transfer and mortgage on one US home, newest first, with each mortgage marked open, released or paid off. Buyer, seller and borrower names with include=owner. A lookup call, one home at a time.

- Authentication: `x-api-key` and `x-email` headers of an owner or admin
- Rate limit: *lookup* call, 20 per minute per key, within the 120 per minute
- Counts toward your brokerage's daily public record allowance (500 by default)

Returns the full recorded history of one home from the county public records: every deed and every mortgage, not just the last sale and the loans still open. Get the `recordId` from [Look up a public record](https://help.ruuster.com/api/public-records-lookup).

This is a *lookup* call (20 per minute) and counts toward your brokerage's daily public record allowance (500 per day by default, shared with the lookup). One home per call.

Counties often never record a loan's release, so each mortgage's `status` is Ruuster's reading of the record: `released` when a release was recorded, `paid_off` when the home later sold (the seller's loans are paid at closing) or a later refinance replaced it, and `open` otherwise. `closedBy` and `closedOn` say which. Treat it as an estimate: this isn't a title, vesting or encumbrance report. Records run about two months behind recording; `asOf` is the date of the county load.

## Path parameters

| Name | Type | Description |
|---|---|---|
| `recordId` | string | The county record's id (digits), `record.recordId` from [Look up a public record](https://help.ruuster.com/api/public-records-lookup) |

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `include` | string | | `owner` adds the buyers and sellers on each transfer (names, buyer vesting, mailing addresses) and the borrowers on each mortgage |

## Response

| Field | Description |
|---|---|
| `recordId`, `asOf` | The home, and when its county record was loaded |
| `transfers[]` | `recordingDate`, `contractDate`, `documentType`, `price` (null when the county doesn't disclose prices), `pricePerSqft`, `cashPurchase`, `intraFamily`, `distressed`, `reo`, `titleCompany`, `documentNumber`; with `include=owner` also `buyers` (`names`, `vesting`, `mailingAddress`) and `sellers` (`names`, `mailingAddress`) |
| `mortgages[]` | `recordingDate`, `amount`, `purpose`, `type`, `rate`, `termMonths`, `dueDate`, `heloc`, `purchaseMoney`, `lender`, `lenderType`, `titleCompany`, `documentNumber`, `status` (`open`, `released`, `paid_off`), `closedBy` (`release`, `sale`, `refinance` or null), `closedOn`; with `include=owner` also `borrowers` |

An unknown `recordId` returns `404 not_found`, and a home outside the states your MLSs cover returns `400 mls_not_in_scope`. A home with no recorded transfers or mortgages returns empty lists.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/public-records/400000123456/history" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"
```

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/public-records/400000123456/history", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/public-records/400000123456/history",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])
```

## Example response

```json
{
  "ok": true,
  "data": {
    "recordId": "400000123456",
    "asOf": "2026-10-03",
    "transfers": [
      {
        "recordingDate": "2019-06-14",
        "contractDate": "2019-05-30",
        "documentType": "Warranty Deed",
        "price": 389000,
        "pricePerSqft": 156.48,
        "cashPurchase": false,
        "intraFamily": false,
        "distressed": false,
        "reo": null,
        "titleCompany": "SAGUARO TITLE AGENCY",
        "documentNumber": "2019-0418823"
      },
      {
        "recordingDate": "2004-11-02",
        "contractDate": null,
        "documentType": "Warranty Deed",
        "price": 286500,
        "pricePerSqft": 115.25,
        "cashPurchase": false,
        "intraFamily": false,
        "distressed": false,
        "reo": null,
        "titleCompany": null,
        "documentNumber": "2004-0921177"
      }
    ],
    "mortgages": [
      {
        "recordingDate": "2021-02-03",
        "amount": 310000,
        "purpose": "Refinance 1st",
        "type": "Conventional",
        "rate": 2.875,
        "termMonths": 360,
        "dueDate": "2051-03-01",
        "heloc": false,
        "purchaseMoney": false,
        "lender": "DESERT PEAK BANK",
        "lenderType": "Bank",
        "titleCompany": null,
        "documentNumber": "2021-0094412",
        "status": "open",
        "closedBy": null,
        "closedOn": null
      },
      {
        "recordingDate": "2019-06-14",
        "amount": 311200,
        "purpose": "Purchase",
        "type": "Conventional",
        "rate": 4.125,
        "termMonths": 360,
        "dueDate": "2049-07-01",
        "heloc": false,
        "purchaseMoney": true,
        "lender": "SONORAN HOME LOANS",
        "lenderType": "Mortgage Company",
        "titleCompany": "SAGUARO TITLE AGENCY",
        "documentNumber": "2019-0418824",
        "status": "paid_off",
        "closedBy": "refinance",
        "closedOn": "2021-02-03"
      }
    ]
  },
  "meta": {
    "brokerageId": "4f6c2a9e-8d31-4b57-9a0e-2c7d5e1b8f43",
    "ms": 188,
    "notice": "From county public records, which run about two months behind recording. Not a title, vesting or encumbrance report; mortgage status is estimated from recorded releases, later sales and refinances. Owner details may not be used to contact anyone who has asked not to be solicited."
  }
}
```