> ## 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 Investor object > A buyer: every name the registry believes is one operator, what they buy, and how to reach them. An investor is a **group of names** the registry believes are one operator. "ZAK VENTURES LLC", "JSB HOMES LLC" and the person behind both are one investor with one stable id, `inv_` plus 12 hex characters. Store the id, and keep the name for display. After a data refresh, 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 registry **retired** it: you get `410 gone` with `superseded_by: null`. Then search by name again. ## Three counts that are not the same thing | Where | What it counts | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | The profile's own counts (`n_deals`, `n_flips`, `n_purchase_events_12m`) | Everything the investor did **across the whole market**. | | `in_radius` on a list or match row | Only what they did **inside the geometry you asked about**, after your filters. | | `summary` on the response | The whole filtered set, not the page. | A row can show `n_deals: 775` beside `in_radius.n_events: 12`. Both are right: a large operator with twelve deals in your neighbourhood. ## Holdings `n_holds` is what the investor still owns across the market: confirmed holdings plus purchases it did not resell. The profile adds `median_purchase_year` (since 0.26.0), the median year of purchase of those parcels. The API computes it over the dated `n_holds` rows when you read the profile. A midpoint between two years rounds up: holdings bought in 2020 and 2021 read 2021. The value is null when the API has nothing to measure. Read it with `n_holds`: 300 holdings bought around 2021 is a recent portfolio, and around 2009 a long-held one. The lists take the count as a filter: `holds_min` and `holds_max`, for example `holds_min=20` for the larger portfolios. `GET /v1/investors` sorts on the holdings inside the geometry with `sort=holds_desc`. See [Filters](/guides/concepts/filters). ## Scale, and who is hidden by default `scale` is `individual`, `small`, `mid`, `large` or `institutional`. Institutional means iBuyers, production homebuilders and bulk single-family landlords with 500 or more houses. They lead every neighbourhood by volume, and they are almost never the buyer for a wholesale deal. So the API **hides them by default**, together with public bodies: the county, the state land department, a housing authority. Ask for them with `scale=individual,small,mid,large,institutional` and `include_public=true`. ## Operators: when several ids are one buyer Many flippers buy through a new LLC per deal. Every list and match row carries `investor.operator_id` and `investor.n_operator_members`. The first is the id of the buying operation, the second how many ids it spans. Shared mailing addresses and shared names link those ids. Rows that share an `operator_id` are **one buyer**: collapse them in a table and contact them once. The API still ranks and pages each id on its own. So an operator with three ids can appear three times, and across pages. Keep the row whose id equals `operator_id` as the visible one. `operator_id` is the busiest member's id, and it can move after a refresh. So group by it within one response, and store the investor ids. [Same buyer, cash right now](/guides/walkthroughs/same-buyer) has the whole rule and the `buyer_signal` block. ## Contact fields This host does not serve `contact`: the people behind the entity, their parsed names, their mailing addresses and `skip_trace_targets[]`. `contact_redacted` is `true`, and four of the block's fields come back null: `primary_address`, `mailing_addresses`, `person_members` and `skip_trace_targets`. The host serves the block's counts, `n_person_members`, `has_home_address` and the rest, so the block itself is never null. Top-level `members` is null too, and `member_names` lists the entity and trust names only. The host serves the rest of the profile as normal. See [Authentication](/guides/concepts/authentication). A deed names a person as SURNAME GIVEN ("RIVERA DANA"). Never split `members[].name` yourself. Use the `given` and `surname` fields, which are already in the right order. ## Two names: `name` and `display_name` `name` is the deed spelling: the spelling most often on the investor's deeds, in upper case. For a person it is SURNAME GIVEN ("RIVERA DANA"). Search matches on `name`, and you join on it. It can change under a stable id when another of the investor's spellings overtakes. `display_name` (since 0.29.0) is the name to print. For a person whose deed spelling parsed cleanly it is GIVEN \[MIDDLE] SURNAME \[SUFFIX] in upper case ("DANA RIVERA"). For an entity, a trust, a public body, an institutional investor or an ambiguous spelling it equals `name`. Every investor object on this page carries both fields on every key. Those objects are the deal row's summary, the list row, the match row, the profile, the search hit, and a deal's `seller` and `end_buyer`. `display_name` is null exactly when `name` is null. The investor stubs on lender objects carry `name` alone. The agent and wholesale stubs carry `display_name` since 0.31.0. Print `display_name`. Match, join and search on `name`. Never reorder a `name` yourself. ## Auction and REO buyers `auction` is the foreclosure-auction and REO purchase block (since 0.7.0). On a list row or a match row it is the nine-field summary: * `n_auction_buys`: the houses a third party bought at a trustee's sale or an Arizona sheriff's sale, all time. * `n_auction_buys_24m` and `is_active_auction_buyer`: one or more such purchases in the last two years, the cash-within-a-day buyers. * `last_auction_buy_on`. * `auction_resale_share`: the share resold within a year. * The same four for houses bought from a lender after a foreclosure: `n_reo_buys`, `n_reo_buys_24m`, `is_active_reo_buyer` and `last_reo_buy_on`. The profile carries the full block: * `auction_kinds` and `n_auction_by_kind`. These include the kinds the API shows but does not count, `HOA_TRUSTEE_SALE`, `TAX_SALE` and `TAX_LIEN_DEED`, so `n_auction_parcels` can exceed `n_auction_buys`. * `n_auction_by_venue`: the Texas platform the servicer appointed, Auction.com, ServiceLink or Xome. * The outcomes of those purchases at 12 months: `n_auction_resold_12m`, `n_auction_transferred_12m`, `n_auction_lost` and `n_auction_held`. * `median_auction_discount` against the later resale. * `lender_note`. * The REO half by grantor class (`n_reo_by_grantor`: `SERVICER`, `GSE_HUD_VA`), with its own outcomes and `reo_resale_share`. The block is **null where the market has no published counts**, that is, where `meta.coverage[].auction_counted` is `false`. That null is an answer, not a zero. Two filters read the block, `buys_at_auction` and `buys_reo`. See [Filters](/guides/concepts/filters). ## The financing block `financing` (since 0.16.0) is what the [lender registry](/api-reference/objects/lender) ties to the investor: * The loans whose borrowers resolve to it, as the main borrower or a co-borrower: `n_loans`, `n_loans_12m` and `n_loans_24m`. The API counts each loan once across the open-lien and recorded-history tables. * The lenders behind them: `n_lenders`, and `lenders_used[]` with each lender's id, name, class and hard-money flag, how many loans, and the date of the last. * The most recent loan, `last_loan`: the lender, the parcel, the date, the amount, and a flag that says if it financed a purchase. * How many of the investor's purchases in the registry's 24-month window have a purchase loan the registry found: `n_deals_financed_24m` over `n_deals_measured_24m`, and `share_deals_financed_24m`. * `uses_hard_money`: a flag that says if a hard-money lender was among the recent ones. Every count is a floor of a partial feed. The recorded history sees about one loan in five. The open-lien table sees one purchase loan in five on holdings, and one in fifteen on flips. So `share_deals_financed_24m` is never a cash share. The block carries its own `as_of` and `dated`: the registry's slice date, not the deed data end. The host serves the block to every key, because lender names are business records. The block is null where the market has no published registry or no published borrower match. It reads zeros where the market has both and no loan resolves to the investor. Two filters read it, `financed_by` and `uses_private_lender`, and the buyers match adds a `financing` reason at weight 0. See [Filters](/guides/concepts/filters). ## Where investors come from | Endpoint | What it gives you | | -------------------------------------------------------------------------- | ------------------------------------------------- | | [`GET /v1/buyers/match`](/api-reference/endpoints/buyers-match) | Ranked against a subject property, with reasons. | | [`GET /v1/investors`](/api-reference/endpoints/investors-list) | The investors active inside an area, by activity. | | [`GET /v1/investors/search`](/api-reference/endpoints/investors-search) | By any name they buy under. | | [`GET /v1/investors/{id}`](/api-reference/endpoints/investors-get) | The full profile below. | | [`GET /v1/investors/{id}/deals`](/api-reference/endpoints/investors-deals) | Their whole deal history. | ## Related topics - [The Investorlift listing object](/api-reference/objects/wholesale-listing.md) - [Get one investor](/api-reference/endpoints/investors-get.md) - [Rank buyers for a property](/api-reference/endpoints/buyers-match.md) - [List investors in an area](/api-reference/endpoints/investors-list.md) - [The Deal object](/api-reference/objects/deal.md)