> ## Documentation Index > Fetch the complete documentation index at: https://developers.investorlift.com/llms.txt > Use this file to discover all available pages before exploring further. # The Lender object > One lender of record: every spelling under one id, its loans counted once across open liens and recorded history, and a profile per market. Early access: while the developer tier is in beta, the API serves this route to Investorlift's team and trusted partners. Investorlift will restrict the route further before it opens to every key. A lender is the lender of record on a recorded mortgage. Its id is `len_` plus 12 hex characters. The lender has the same id on every instrument and in every market, whatever spelling the document used. KIAVI FUNDING INC, KIAVI FUNDING LLC and LENDINGHOME FUNDING CORP are one lender under one id. `names[]` lists every spelling the recorded instruments use. Store the id, and keep the name for display. After a registry run, an old id goes one of two ways. Either it **redirects**: you get the current profile, and `meta.resolved_from` names the id you asked for. Or the run **retired** it: you get `410 gone` with `superseded_by: null`. Then search by name again, as [Retired ids](#retired-ids) explains. Every value is a snapshot at `as_of`, the financing slice date in `meta.coverage[].lenders.as_of`. Every response that carries one says so in `meta.dated[]`. See [dated data](/guides/concepts/dated-data). ## How a lender is identified `identity_basis` says how the registry tied a spelling to its lender: | `identity_basis` | Means | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NAME_FOLD` | The folded name alone. The fold removes case, punctuation and entity suffixes, and spells out abbreviations. So WELLS FARGO BANK NA and WELLS FARGO BANK N.A. are one. | | `TRUNCATED_PREFIX` | A name the file cut short, joined to the one longer name it is a prefix of. | | `ALIAS_DICTIONARY` | A hand-kept row joined it: a recorded rename (QUICKEN LOANS to ROCKET MORTGAGE), a trade name, a spelling the same instrument carries both ways. `former_names[]` lists the spellings a rename retired. | The registry never merges acquisitions. A lender that bought another's book keeps its own id, and so does the lender it bought. [Successor](#successor) says which is which. The id is a function of the folded name, not of the market or of a data refresh. So the id is the identity to store. `name` can change under it when one spelling overtakes another. A hand-decided merge joins two spellings by a dictionary row and retires the smaller id. The retired id still answers. See [Retired ids](#retired-ids). ## Class and the hard-money flag `lender_class` is a reading of the name, never a legal status. It is the same reading the parcel's [financing block](/api-reference/objects/financing) carries. The five classes: * `BANK` * `NONBANK` * `PRIVATE`: a trust, a seller carry-back or another private party * `INDIVIDUAL`: a person's name * `GOVERNMENT`: HUD, the VA, a housing authority Since 0.17.0 the registry reads the class on the folded name. So punctuation, initials and a missing space cannot defeat a rule. KS STATEBANK and MANUFACTURERS & TRADERS TR CO read `BANK`. A person whose surname is Banks does not. A securitisation trust, or a trust with lender words in its name, reads `NONBANK`, not `PRIVATE`. A housing authority, a city or a county reads `GOVERNMENT` unless it is a credit union. `PRIVATE` is not the hard-money sense of "private lender". For that sense, read `is_hard_money`. It is true when the name carries hard-money vocabulary or is a known brand (`hard_money_basis: NAME`). Since 0.16.0 it is also true when the book behaves like a hard-money book, that is when three things hold: * the lender has 20 or more loans since 2015 * a quarter or more of them have a recording date within 45 days of a registered investor's purchase * the lender is not a bank The basis is then `BEHAVIOUR`, or `BOTH` when the name says so too. The second rule catches a lender that lends hard money under a plain name, once the deed link of its market exists. A market without a deed link has the name rule alone. `investor_lending.is_investor_lender` is the neighbouring flag: half or more of the window's loans went to registered investors, whatever the name. ### Class basis `class_basis` (since 0.17.0) says why the class reads as it does: | `class_basis` | Means | | ------------- | --------------------------------------------------------------------------------------------------------------------------- | | `NAME` | The name rules alone, evaluated on the folded name. Nearly every lender. | | `DICTIONARY` | A hand-kept row overrides what the name says, for example BBVA USA read as a `BANK` although the name carries no bank word. | A class is a reading, never a verification: a name that reads `BANK` is a name with a bank word in it. When a registry run reads a lender's name as a person's where it did not before, the lender falls under the [person gate](#the-person-gate). If it loses its id, the run retires the id with an alias row, and the id answers `410 gone`. So the change is never silent. ## Successor `successor` (since 0.17.0) is the lender this one is now part of, on a market profile. The link is an `ACQUISITION`, where the acquirer bought the lender or its book, or a `SUBSIDIARY`, where the parent owns it. The block carries the successor's `id`, `name`, `lender_class` and `is_hard_money`. The registry never merges the books: BANK ONE's loans stay BANK ONE's, and WELLS FARGO BANK NORTHWEST NA keeps its own profile. The profile of each points at the lender it is now part of instead. It is null when the registry holds no link, and null when the linked lender has no profile in the market. Investorlift keeps the links by hand. So `successor` is present on a few dozen lenders, not on every lender an acquirer ever bought. ## NMLS id `nmls` (since 0.17.0) is the lender's NMLS id and the NMLS Consumer Access page it opens (`id`, `url`). Investorlift curates it by hand for the largest lenders, and starts from the most active in the last 24 months. It is null for every lender no one curated yet, which is most of the registry. A null is "not looked up", never "no NMLS registration". The id is the lender's, so it is the same on every market profile and on the union object too. ## Retired ids Ids are a pure function of the folded name, so a registry rebuild re-issues the same id for the same name. A run retires an id only in three cases. The run decides that two ids were one lender: a spelling pair or a truncated spelling joined by a dictionary row, `reason: MERGED` or `MERGED_PARTIAL`. The run splits an id (`NEW_SPLIT`). Or a lender's rows leave the registry altogether (`RETIRED`). The registry keeps every retired id since the first run, in every market that served the lender: * **On [`GET /v1/lenders/{id}`](/api-reference/endpoints/lenders-get), [`/loans`](/api-reference/endpoints/lenders-loans) and [`/borrowers`](/api-reference/endpoints/lenders-borrowers)** a merged or split id answers 200 with the current lender in `data`. `meta.resolved_from` lists the ids the API followed, oldest first. Store the current `id`. * **A `RETIRED` id** answers [`410 gone`](/guides/concepts/errors#gone) with `superseded_by: null`, the reason and the registry run that retired it. Search by name with [`GET /v1/lenders/search`](/api-reference/endpoints/lenders-search). * **An id that no run ever issued** answers 404, and so does a chain that no longer leads to a lender. * **`id_history[]`** on a market profile is the other direction: every id retired into this lender, oldest run first. Each carries its `reason` and the `lender_run` that retired it. It is empty on nearly every lender. The `financed_by` and `filters.financing.lender_id` filters follow an old id the same way and stamp `meta.resolved_from` on the list. A registry built before 0.17.0 has no alias table: an old id answers 404 there, and `meta.resolved_from` is absent. ## What the counts are Two tables feed the registry. The first is the open lien positions at the slice date, up to 4 per parcel. Each comes with the balance, rate, term and maturity the open-lien table carries. The second is the recorded mortgage history: the 5 most recent mortgages per parcel. The history captures about one open loan in five (`coverage.history_capture_share`), and a paid-off loan is in neither table. The consequences: * **`n_loans`, `n_loans_12m` and `n_loans_24m` count instruments once across both tables.** The same parcel, date and amount is one instrument. They are the origination counts, and the lender list ranks by `n_loans_24m`. * **`n_in_history` and its windows are what the history holds**, duplicated slots included. They are a floor, never an activity measure. * **A bridge lender's book is the most undercounted.** The registry counts a short-term loan only while it is open, and the lender's paid-off loans are in neither table. Compare hard-money lenders with each other, not with a bank. * **Every `by_year` row before `history_floor_year` is a floor**: the history keeps 5 slots per parcel. On a parcel with all five slots filled, the older mortgages fell out. * **Volumes leave out amounts above \$5,000,000.** The file records a commercial facility's whole amount on every parcel it covers, so one facility can add billions to a bank's window volume. `volume_24m`, every volume in `by_year`, `by_month` and `geography`, and the `terms.amount` quartiles leave those instruments out. `n_amount_excluded_24m` counts them, and the loan row keeps its amount with `amount_outlier` set. A blanket loan, one loan recorded on 5 or more parcels, counts once in the same sums, and `n_blanket_positions_24m` counts its positions. Loan counts and the ranks by loans never change. * **Null means not measured, and zero means measured and none.** `n_open_maturing_12m_from_as_of` is null when fewer than half of the open positions carry a maturity date (`share_due_known`). `n_purchase` and `n_investor` on a year, and every purchase, borrower, investor and flip figure below, are null without the market's deed link or borrower match. `purchase_measured`, `investor_lending_measured`, `flips_measured` and `borrowers_measured` on the market profile say which of these the market measures. `takebacks` is null as a whole while `takebacks_measured` is false, and `n_counties_ranked_first_24m` is null while `counties_measured` is false (since 0.19.0). A margin is null under 20 resold flips with both prices, and a quartile under 3 values. `n_loans_24m` counts every instrument of any kind, purchase money, refinance, HELOC and construction alike. For a `GOVERNMENT` lender it counts the insurance claims and partial-claim seconds recorded under the agency's name, not originations. ## One profile per market The object carries the union totals: `n_loans_24m`, `volume_24m`, `n_open_liens` and `open_balance`, summed over `markets[]`. It also carries one market profile per loaded market where the lender has loans, most loans first. Each market profile carries these blocks: * `rankings`: the rank and share over the 24 months that end on `as_of`, overall, within its class and among hard-money lenders. The registry computes them over every lender of the market, the ones the default list hides included. So a profile's rank can be absent from a default page of the list, which numbers its own rows. * `coverage`: the counties the registry covers, the parcels left out, the slice date, `recordings_through` and the capture share. * the `by_year` and `by_month` series against the market * the product, term, label and property-type mix * `terms`: the amount, rate and term quartiles, each with how much of the book carries it * `geography` * a `summary` written from the served numbers at build time `recordings_through` is fourteen days before `as_of`. The two weeks between are unmeasured, not empty. The registry measures every recency on a lender against `recordings_through`, not against the slice date. ## Who borrows, what was financed and how it ended Since 0.16.0 the registry joins the recorded deeds to the loans. Three blocks and some counts read the join. The registry writes all of them into the profile at build time, and never computes them on read. Each is null as a whole where the market lacks its input. * **Purchase money.** The deeds decide `purpose` on every loan row, never the file's label. It is `PURCHASE` when a priced deed on the parcel is dated in the 45 days up to and including the recording date. It is `NOT_PURCHASE` when the deed registry covers those days and none falls in them, and `UNKNOWN` when it does not. * **Purchase money on the profile.** `by_purpose_24m` splits the window, and [`sort=purchase_desc`](/api-reference/endpoints/lenders-list) orders by `n_purchase_money_24m`. `rankings.rank_purchase_24m` places the lender by it. `terms.loan_to_price` is the loan against the deed price on the window's purchase loans. A value above 1 is a rehab holdback on top of the price, not an error. `purchase_measured` says if the market serves any of it. * **`borrowers`.** Who borrows. The block counts the borrowers, all time and in the window, and how many resolve to a registered investor. `borrower_measured_share` is the share of the book with any borrower source at all. Not every loan has one: the recorded history names borrowers, and the open-lien table does not. The block also carries repeats, newcomers, churn, the ten largest borrowers and the ten lenders that share the most borrowers with this one. * **A borrower is a key**, 12 hex characters hashed from the folded name, the same key on every lender's rows. The profile serves a company's name beside it. A person's name is never on the profile, and `person_names_redacted` says when the registry dropped one. * **`n_churned_12m`** counts the borrowers whose last loan here is 12 to 36 months old and who took a later loan elsewhere. It counts them only when no open lien of this lender follows that later loan. On a feed that sees one loan in five, that count is a lower bound of leaving. It is not an upper bound of anything. `churn_measured` is false where the registry cannot read churn at all. [`GET /v1/lenders/{id}/borrowers`](/api-reference/endpoints/lenders-borrowers) lists every borrower. * **`investor_lending`.** How much of the book funds registered investors. The block carries the investor loans and their share of the window, and the investors and their kinds. It carries the deals whose purchase loan is this lender's, by what occurred on them, and the auction and wholesale purchases among them. It also carries the ten largest investors and `is_investor_lender`. The purchase loan of a deal is a loan recorded in the 45 days from the purchase, the largest when several. * **`by_outcome_24m`** and `median_months_to_payoff` beside it say what became of the captured loans. The registry reads them from the later deeds and mortgages. The outcomes are `RESOLVED_BY_RESALE`, `REFINANCED`, `OPEN`, `UNKNOWN` and, since 0.19.0, `FORECLOSED`. The last one is a take-back deed on the parcel before any resale or later mortgage. They are a performance proxy and never a payment history. * **`flips_financed`.** The flips bought in the 36 months to 45 days before `recordings_through` whose purchase loan was this lender's. The block counts them, and it also carries the lender's share of every flip the slice can attribute. `capture_share` measures them against the flips by investors who borrow from this lender elsewhere, whose own purchase loan the slice did not see. Where 20 or more flips resold with both prices, the block carries the resale margins: `median_gross_profit` with its quartiles, `median_spread_ratio`, `median_hold_days` and `median_loan_to_price`. Under that the margins are null, and a gross profit is never net of rehab or costs. The capture behind all three is partial. The open-lien table sees about one purchase loan in five on holdings, and one in fifteen on flips. So every count is a floor, and a `NONE_CAPTURED` purchase on a deal is not a cash purchase. The `summary` paragraph never quotes a margin. ## Take-backs `takebacks` (since 0.19.0) is what the lender took back at foreclosure. The registry reads it from the county's recorded deeds since 2016 and never from a delinquency or default feed. A **take-back deed** is a trustee's deed, a sheriff's deed or a deed in lieu of foreclosure whose grantee is this lender. The registry matches the grantee under any of the lender's spellings, through the same fold that gives the lender its id. The grantee on such a deed is usually the trustee or the servicer. So the originator of a securitised loan is invisible here, and a bank that services a large book reads large. The block does not measure delinquency, only the deed that ended it. * `n_takebacks` counts the lender's take-back deeds since 2016 and `n_takebacks_24m` those in the 24 months to `as_of`. `by_instrument[]` splits them into `TRUSTEES_DEED`, `SHERIFFS_DEED` and `DEED_IN_LIEU`, each with its share. * `n_loans_foreclosed` is the take-backs on a parcel that carries a loan row of this lender recorded before the deed. `n_takebacks_unlinked` is the rest, for one of three reasons. The loan predates the five slots the history keeps. It sits in neither table. Or another lender made the loan, and this one is that lender's trustee or servicer. * `foreclosure_share` is the share of the lender's captured loans whose `outcome` is `FORECLOSED`. A captured loan is one tied to an investor deal. The share is null under 20 captured loans. `median_days_takeback_to_resale` is the median days from the take-back deed to the next priced sale of the parcel. It is null under 3. * `is_auction_lender` is true when the lender took property back at a trustee's sale by credit bid or by deed in lieu, whatever the name says. The flag reads the deeds the auction registry classifies, and those deeds alone, never the class. A bank with no take-back reads false. The block is null as a whole while `takebacks_measured` is false on the market profile. Every count leaves out every take-back deed of a bulk judgment sale held for review. `foreclosed` on [the loan row](/api-reference/objects/lender-loan#foreclosed) is the per-loan side of the same deeds. ## Rankings by place Since 0.19.0 `rankings` also carries `share_by_volume_24m`: the lender's window volume over the market's, under the \$5,000,000 rule. It also carries three counts of the places the lender leads, by ZIP, city and county: `n_zips_ranked_first_24m`, `n_cities_ranked_first_24m` and `n_counties_ranked_first_24m`. These count the places where the lender recorded 10 or more loans in the 24 months to `as_of` and ranks first by that count. The rank is among every lender of the market there, persons and government included. The county count is null while `counties_measured` is false, as it is with one loaded county. [`GET /v1/lenders/{id}/rankings`](/api-reference/endpoints/lenders-rankings) gives the places themselves, with the lender's rank and share in each, over any window and at the hex-cell grain too. [`GET /v1/lenders/{id}/cells`](/api-reference/endpoints/lenders-cells) gives its loans per cell. The `summary` paragraph says how many ZIP codes the lender ranks first in when that count is 1 or more. On a registry built before the place rankings, the four fields are null. ## The person gate A lender whose name reads `INDIVIDUAL` or `PRIVATE` gets an id and a profile only when it passes a gate (`profile_gate: SERVED`). The gate is 10 or more loans on 5 or more parcels. Below it, the name stays on the parcel's financing block alone, with no id. The list and the search hide `INDIVIDUAL` and `PRIVATE` lenders unless `include_persons=true`. They hide `GOVERNMENT` lenders unless `include_government=true`. This is the way investor lists hide institutional buyers. ## Contact data Nothing in any delivery carries a lender's phone or email, so no lender object has a contact block. Lender names are business records of the loan. The API serves them in full to every key, whatever the class. The API serves a borrower as a key and, when it is a company, its name. A person borrower's name is never on the profile, and this host does not serve it on the [borrowers route](/api-reference/endpoints/lenders-borrowers). The profile names the investor behind a borrower by its registry name, the deed spelling, as every deal row names it. ## Availability The counties in `meta.coverage[].lenders.counties` can be narrower than the market. [Counties, cities and ZIP codes](/coverage/places) lists them. A ZIP, city or county outside them answers `422 outside_coverage` and names the covered counties, never an empty page. A geometry outside every loaded market's tolerance answers the same. A market without a published lender registry answers `422 lenders_unavailable` on every lender route. `meta.coverage[].lenders` is null there. A registry built before a phase serves that phase's fields as null. It answers `422 lenders_unavailable` on the routes and parameters that need them. `meta.coverage[].lenders` carries the flags: `purchase_measured`, `investor_lending_measured`, `flips_measured`, `borrowers_measured`, `takebacks_measured` and `counties_measured`. | Endpoint | What it gives you | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | [`GET /v1/lenders/search`](/api-reference/endpoints/lenders-search) | The lender id, from any spelling of the name. | | [`GET /v1/lenders`](/api-reference/endpoints/lenders-list) | The ranked [lender list](/api-reference/objects/lender-ranking) of a market, a ZIP, a city or a county. | | [`GET /v1/lenders/{id}`](/api-reference/endpoints/lenders-get) | The profile below. | | [`GET /v1/lenders/{id}/loans`](/api-reference/endpoints/lenders-loans) | Every [loan](/api-reference/objects/lender-loan) of theirs, newest recording first. | | [`GET /v1/lenders/{id}/borrowers`](/api-reference/endpoints/lenders-borrowers) | Every [borrower](/api-reference/objects/lender-borrower) of theirs, most loans first. | | [`GET /v1/lenders/{id}/rankings`](/api-reference/endpoints/lenders-rankings) | Every place they rank in, as [ranking buckets](/api-reference/objects/lender-ranking-bucket), or their month series. | | [`GET /v1/lenders/{id}/cells`](/api-reference/endpoints/lenders-cells) | Their loans per hex cell, as [lender cells](/api-reference/objects/lender-cell), for a map. | ## Related topics - [The Financing object](/api-reference/objects/financing.md) - [The Investor object](/api-reference/objects/investor.md) - [The Lender cell](/api-reference/objects/lender-cell.md) - [The Lender ranking row](/api-reference/objects/lender-ranking.md) - [The Lender ranking bucket](/api-reference/objects/lender-ranking-bucket.md)