---
title: "Owner card -- the owner of record and their mailing contact (account required)"
method: GET
path: "/api/v1/owners/card"
tags: ["Owners"]
---

# Owner card -- the owner of record and their mailing contact (account required)

`GET /api/v1/owners/card`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/owners/card`
- Auth: HTTP bearer

The owner of record and how to reach them BY MAIL, for one parcel (`parcel_id`) or one owner name (`name`, the exact owner-of-record spelling). Returns the co-owners the same assessor record names (`co_owners`, `co_owner_status`: listed / none_listed / not_checked) and the best mailing address -- read from ONE address column family of the record, with its ZIP, flagged mail_ready / po_box / equals_situs, graded A-D with its source and as-of date (`as_of_basis`: roll_year = the record's tax year; release_vintage = the PropRaven parcel release that served a record with no roll year, never presented as the county's date; recording_date = a deed; null when there is no date) -- plus, for an owner name, the owner's distinct mailing addresses across up to 50 of their parcels (`parcels_citing`). `phones` are OWNER phones only: a building permit filed in the current owner's era published the phone for the owner role (the field name, the publisher, or a role column on the permit says so) and names the current owner; otherwise `phone_status` says none_published, or not_checked when the lookup could not run. `people_on_permits` separately lists applicant and contractor phones from the parcel's permits (role, name, permit, date, and `era`: filed in the current owner's era or before it); they are never the owner's phone, and a phone whose role the source does not state is never served. Every phone is E.164 with its extension split off and the published value kept verbatim (`phone_raw`). Grade-D (contradictory) addresses are hidden unless include_low_confidence=true.

ACCOUNT REQUIRED: an API key, an MCP OAuth token or a signed-in session. Anonymous callers -- including x402 / credit-token wallets -- get HTTP 401 `code: "account_required"` before any read.

LOOKUP CAP: on an account without a paid plan each card counts as ONE lookup against the monthly lookup cap, spent before any read (a card that is not served is refunded). At the cap: HTTP 402 `code: "lookup_cap_reached"` with used / limit / plan and the upgrade link. Each served card is recorded in PropRaven's people-data access log.

## Query parameters

- `parcel_id` string
- `name` string
- `include_low_confidence` boolean

## Response `200`

The owner card.

- OwnerCard: The owner card: the owner of record and how to reach them by mail, from what the publishing authorities released.
  - `subject` object, required: { kind: "parcel", canonical_id } or { kind: "owner", parcels_considered, parcels_capped }.
    - `kind` string, required
    - `canonical_id` string, required
  - `owner` object, required
    - `name` string, required
    - `name_status` 'present' | 'missing' | 'placeholder' | 'confidential', required
    - `entity_type` string, required
    - `roles` unknown[], required
      - unknown
  - `contact` object, required
    - `owner_name` string, required
    - `owner_name_status` string, required
    - `owner_roles` unknown[], required
      - unknown
    - `owner_name_provenance` object, required
      - `source` object, required
        - `authority` string, required
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, required
      - `as_of_basis` string, required
      - `grade` string, required
    - `co_owners` CoOwner[], required: The other owners the same assessor record names, in the record's order; never the owner again. Name mode: across the side-read parcels, distinct by name.
      - `name` string
      - `basis` 'assessor_co_owner'
      - `source` ContactSource
        - `authority` string, required: Who published the value, e.g. the county assessor.
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, nullable
      - `as_of_basis` 'roll_year' | 'release_vintage' | 'null', nullable
      - `grade` 'A' | 'B' | 'C' | 'D'
    - `co_owner_status` 'listed' | 'none_listed' | 'not_checked', required: none_listed is claimed only for a record whose state's co-owners were loaded from the release that serves it; not_checked when the lookup could not run, the state is not loaded yet, or the loaded row was read beside a different owner.
    - `mailing` MailingAddress, required: One mailing address, read from ONE address column family of the record (owner_mailing_* or owner_*), never a street from one family and a ZIP from the other.
      - `basis` string, required: Where the address came from, e.g. owner_mailing, owner_address, deed_grantee.
      - `line1` string, required
      - `city` string, required
      - `state` string, required
      - `zip5` string, required
      - `zip4` string, nullable, required
      - `mail_ready` boolean, required: Street, city, state and a 5-digit ZIP are all present and consistent.
      - `po_box` boolean, required
      - `equals_situs` boolean, required: The mailing address is the property itself (owner-occupied).
      - `zip_conflict` boolean, required
      - `parcels_citing` number, required: Owner (name) cards only: how many of the owner's parcels carry this address.
      - `parcels_citing_basis` string, required
      - `label` string, required: The address as one mailing label.
      - `source` ContactSource, required
        - `authority` string, required: Who published the value, e.g. the county assessor.
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, required
      - `as_of_basis` string, required
      - `grade` 'A' | 'B' | 'C' | 'D', required: A = the authority's own complete record; D = contradictory (hidden unless include_low_confidence=true).
    - `mailing_alternates` MailingAddress[], required: Parcel mode: a latest-deed grantee address naming the same owner, when it differs.
      - `basis` string, required: Where the address came from, e.g. owner_mailing, owner_address, deed_grantee.
      - `line1` string, required
      - `city` string, required
      - `state` string, required
      - `zip5` string, required
      - `zip4` string, nullable, required
      - `mail_ready` boolean, required: Street, city, state and a 5-digit ZIP are all present and consistent.
      - `po_box` boolean, required
      - `equals_situs` boolean, required: The mailing address is the property itself (owner-occupied).
      - `zip_conflict` boolean, required
      - `parcels_citing` number, required: Owner (name) cards only: how many of the owner's parcels carry this address.
      - `parcels_citing_basis` string, required
      - `label` string, required: The address as one mailing label.
      - `source` ContactSource, required
        - `authority` string, required: Who published the value, e.g. the county assessor.
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, required
      - `as_of_basis` string, required
      - `grade` 'A' | 'B' | 'C' | 'D', required: A = the authority's own complete record; D = contradictory (hidden unless include_low_confidence=true).
    - `entity` object, required: Secretary of State principals (entity type, status, registered agent, officers) when the owner is an entity. When the parcel record carries no registered agent or officers, they come from the single matching Secretary of State filing (`principals_basis: sos_registry`).
      - `entity_type` string, required
      - `status` string, nullable, required
      - `state_of_formation` string, nullable, required
      - `formation_date` string, nullable, required
      - `registered_agent` string, nullable, required
      - `officers` unknown[], required
        - unknown
      - `source` object, required
        - `authority` string, required
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, nullable, required
      - `as_of_basis` string, nullable, required
      - `grade` string, required
      - `principals_basis` 'parcel_record' | 'sos_registry'
    - `phones` object[], required: OWNER phones (owner role only) published on a building permit filed in the current owner's era and naming them (grade C): { e164, display, ext, phone_raw, role_basis, permit_ref, source, as_of, as_of_basis, grade }.
    - `phone_status` 'published' | 'none_published' | 'not_checked', required: none_published is claimed only after the permit lookup ran; not_checked when it could not (timeout, no acquisition date, no owner name).
    - `emails` object[], required: OWNER e-mails a building permit published (a key naming the owner's e-mail, e.g. Mecklenburg owner_email_address), on a permit filed in the current owner's era whose owner name matches the current owner (grade C): { email, valid, basis: permit_owner_email, email_key, permit_ref, source, as_of, as_of_basis, grade }.
    - `none_published` string[], required
    - `hidden_low_confidence` number, required
    - `people_on_permits` object[], required: Applicant, contractor and unknown-role phones on the parcel's permits (name mode: across the side-read parcels), newest first, one per (role, number), at most 10: { role: applicant|contractor|unknown (the publisher states no role), role_basis, name, e164, display, ext, phone_raw, permit_ref, era: current_owner|prior_owner|unknown, source, as_of, as_of_basis, grade }. Never the owner's phone.
    - `people_on_permits_status` 'listed' | 'none_published' | 'not_checked', required: none_published only after the parcel's permits were read in full; not_checked when the read did not run or stopped at its cap.
    - `other_addresses` object[], required
      - `parcel_id` string, required
      - `state` string, nullable, required
      - `county` string, nullable, required
      - `kind` string, nullable, required
      - `address` object, required
        - `line1` string, nullable, required
        - `city` string, nullable, required
        - `state` string, nullable, required
        - `zip5` string, nullable, required
        - `zip4` string, nullable, required
        - `label` string, nullable, required
        - `mail_ready` boolean, nullable, required
        - `po_box` boolean, nullable, required
      - `same_as` string, nullable, required
      - `grade` string, nullable, required
      - `link` string, nullable, required
      - `basis` string, nullable, required
      - `label_note` string, nullable, required
      - `evidence` unknown[], required
        - unknown
      - `mail_merge` boolean, nullable, required
      - `owner_name_on_record` string, nullable, required
      - `owner_roles` unknown[], required
        - unknown
      - `cited_by` object[], required
        - `parcel_id` string, required
        - `state` string, nullable, required
        - `county` string, nullable, required
      - `parcels_citing` number, nullable, required
      - `source` object, required
        - `authority` string, nullable, required
        - `dataset` string, nullable, required
        - `url` string, nullable, required
      - `as_of` string, nullable, required
      - `as_of_basis` string, required
    - `other_addresses_status` string, required
    - `other_addresses_scope` object, required
      - `name_basis` string, required
      - `spellings` number, required
      - `parcels_read` number, required
      - `capped` boolean, required
      - `copies_skipped` number, required
      - `parcels_linked` number, required
      - `possible_found` number, required
      - `possible_listed` number, required
      - `possible_cap` number, required
      - `possible_withheld_reason` string, nullable, required
      - `listed_capped` boolean, required
      - `evidence_providers` object[], required
        - `id` string, required
        - `status` string, nullable, required
      - `co_owner_link` string, required
    - `co_owner_scope` object: Name mode: { parcels_checked, parcels_considered }.
    - `mailing_addresses` MailingAddress[]: Name mode: the owner's distinct mailing addresses, most-cited first.
      - `basis` string, required: Where the address came from, e.g. owner_mailing, owner_address, deed_grantee.
      - `line1` string, required
      - `city` string, required
      - `state` string, required
      - `zip5` string, required
      - `zip4` string, nullable, required
      - `mail_ready` boolean, required: Street, city, state and a 5-digit ZIP are all present and consistent.
      - `po_box` boolean, required
      - `equals_situs` boolean, required: The mailing address is the property itself (owner-occupied).
      - `zip_conflict` boolean, required
      - `parcels_citing` number, required: Owner (name) cards only: how many of the owner's parcels carry this address.
      - `parcels_citing_basis` string, required
      - `label` string, required: The address as one mailing label.
      - `source` ContactSource, required
        - `authority` string, required: Who published the value, e.g. the county assessor.
        - `dataset` string, required
        - `url` string, nullable, required
      - `as_of` string, required
      - `as_of_basis` string, required
      - `grade` 'A' | 'B' | 'C' | 'D', required: A = the authority's own complete record; D = contradictory (hidden unless include_low_confidence=true).
    - `phone_scope` object: Name mode: { parcels_checked, parcels_considered }.
    - `email_status` 'published' | 'none_published' | 'not_checked': none_published is claimed only after the permit lookup ran (as phone_status); before 2026-10-09 the card claimed "no email" without looking.
    - `registry_filings` object[]: Secretary of State filings whose registry name equals the owner's exactly (public.sos_name_key; FL Sunbiz today): { registry, doc_number, name, status, filing_type, file_date, state_of_formation, principal_address, mailing_address, registered_agent { name, type, address }, principals [{ title, role, party_type, name, address }], as_of, source, grade }. Grade B for the one filing under the name in the parcel's own state, else C.
    - `registry_status` 'listed' | 'none_found' | 'not_an_entity' | 'not_checked': not_an_entity: the owner name reads as an individual and is never looked up in a business registry.
  - `note` string, required

## Other responses

- `400`: Neither or both of `parcel_id` / `name`, a placeholder name (e.g. PROPERTY OWNER), or a name over 200 characters.
- `401`: No account (`code: "account_required"`, `reason: "people_data_requires_account"`), or an invalid API key.
- `402`: The account's monthly lookup cap is reached (`code: "lookup_cap_reached"`, with used / limit / plan / upgrade). Nothing was read or charged.
- `404`: No served parcel has this identity, or no served parcel lists this exact owner spelling. The lookup is refunded.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error. The body never carries database or driver text.
- `503`: The lookup meter was unavailable; the card was not served and nothing was charged.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)