Properties

Enrich several properties with owner contact info in one request

postapi.modelmatch.com/v1/properties/enrich

Looks up owner contact information for up to 50 properties in a single synchronous request. Each id is resolved independently and returned in the results array with its own status — a bad id never fails the batch. Each match debits 10 credits; cache hits and no-matches are free. Every ok item also carries property — the parcel's Community Lending neighborhood profile and mortgage party rosters. For larger sets use the asynchronous bulk job.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Body application/json

propertyIdsstring[]required

Property ids to enrich in one request. 1–50; larger sets must use the async bulk job. Use the id/mmPropertyId from a property search or a loan/sale record (e.g. mm_<fips><apn>) — bare APNs, fips+apn, or loan_… ids will not resolve.

refreshboolean

When true, bypass both caches for every id, force a fresh skip-trace, and re-charge per match.

Responses

200objectPer-item results (each cached, fresh, or errored)

Show attributes

resultsobject[]required

Show child attributes

alternatesstring[]

Sibling document ids. Present only on ambiguous_ref — pass one as a precise id to enrich that exact unit.

balancenumber

Remaining credit balance. Present only on insufficient_credits.

cachedboolean

Served from cache (member entitlement or internal). ok items only.

chargedboolean

True when this id resulted in a credit debit. ok items only.

codeenum

Failure reason. error items only.

Options:not_foundambiguous_refno_addressprovider_errorinsufficient_creditsrate_limiteddaily_limit_exceededpermission_deniedmember_not_foundbad_requestbilling_unavailable

dataobject

Show child attributes

enrichedAtstringrequired

ISO 8601 timestamp

personsobject[]required

sourcestringrequired

Data source identifier

propertyobject | null

The parcel behind this enrichment. ok items only; null when the id resolved to more than one parcel.

Show child attributes

communityLendingobject | nullrequired

Community Lending — the profile of the neighborhood (U.S. Census tract) this parcel sits in: program designations, income and affordability, the population profile, the local mortgage market, remoteness and proximity. Values describe the U.S. Census tract (neighborhood) as a whole — tract-level aggregate statistics, never an individual, household or applicant attribute. Percentages are 0-100. Two fields are deliberately NOT 0-100: tractIncomeVsMetroPct is a ratio where 100 means parity with the metro (it exceeds 100), and tractRuralGradient is an ordinal 1-10 code. null — not an all-null object — for the roughly 6% of parcels that resolve to no neighborhood. Every field here is also a filter key on POST /properties.

partiesobjectrequired

Mortgage parties attributed to the parcel, split by scope: alltime (everyone on record, a strict superset of the rest), active (parties on loans still outstanding), matched (the subset whose loan resolved to a known NMLS entity) and last (the most recent loan). Real estate agents are not part of this block — reach parcels from an agent through POST /v1/agents/{id}/properties.

propertyIdstringrequired

reasonenum

Pipeline path used to produce this enrichment. Pair with charged to drive billing UX; pair with data.persons to drive the empty-state UX.

Options:member_cache_hitinternal_cache_hitinternal_cache_hit_emptyfresh_skip_tracefresh_skip_trace_empty

resultobject

Per-batch counts BatchData echoed back (or all-zero on cache hits). matched > 0 implies a fresh hit; noMatch > 0 with matched: 0 implies a genuine no-match.

Show child attributes

errorintegerrequired

matchedintegerrequired

noMatchintegerrequired

requestedintegerrequired

statusenumrequired

Options:okerror

summaryobjectrequired

Show child attributes

chargedintegerrequired

Items that resulted in a credit debit (one per match).

failedintegerrequired

Items with status error.

requestedintegerrequired

succeededintegerrequired

Items with status ok (cache hits + fresh, matched or empty).

400objectInvalid request (Zod validation failure)

401objectAuthentication required

curl -X POST "https://api.modelmatch.com/v1/properties/enrich" \
  -H "x-api-key: $MODEL_MATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyIds": [
      "<string>"
    ],
    "refresh": true
  }'

import { createClient } from "@model-match/api";

const client = createClient({ apiKey: process.env.MODEL_MATCH_API_KEY });

const { data, error } = await client.properties.enrichPropertiesBatch({
  body: {
    propertyIds: [
      "<string>"
    ],
    refresh: true
  }
});

import os
import requests

res = requests.post(
    "https://api.modelmatch.com/v1/properties/enrich",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
    json={
        "propertyIds": [
            "<string>"
        ],
        "refresh": True
    },
)
data = res.json()

200 response

{
  "results": [
    {
      "alternates": [
        "<string>"
      ],
      "balance": 123.45,
      "cached": true,
      "charged": true,
      "code": "not_found",
      "data": {
        "enrichedAt": "<string>",
        "persons": [
          {
            "death": {
              "deceased": true
            },
            "dnc": {
              "tcpa": true
            },
            "emails": [
              {
                "email": null,
                "tested": null
              }
            ],
            "litigator": true,
            "mailingAddress": {
              "addressValidity": "<string>",
              "city": "<string>",
              "county": "<string>",
              "formattedStreet": "<string>",
              "hash": "<string>",
              "houseNumber": "<string>",
              "state": "<string>",
              "street": "<string>",
              "streetNoUnit": "<string>",
              "zip": "<string>",
              "zipPlus4": "<string>"
            },
            "meta": {
              "error": null,
              "matched": true
            },
            "name": {
              "first": "<string>",
              "full": "<string>",
              "last": "<string>",
              "middle": "<string>"
            },
            "phoneNumbers": [
              {
                "carrier": null,
                "dnc": null,
                "lastReportedDate": null,
                "number": null,
                "reachable": null,
                "score": null,
                "tested": null,
                "type": null
              }
            ],
            "propertyAddress": {
              "addressValidity": "<string>",
              "city": "<string>",
              "county": "<string>",
              "formattedStreet": "<string>",
              "hash": "<string>",
              "houseNumber": "<string>",
              "state": "<string>",
              "street": "<string>",
              "streetNoUnit": "<string>",
              "zip": "<string>",
              "zipPlus4": "<string>"
            }
          }
        ],
        "source": "<string>"
      },
      "property": {
        "communityLending": {
          "affordableHousingTract": true,
          "difficultDevelopmentArea": true,
          "distressedTract": true,
          "floodHazardTract": true,
          "lowModIncomeTract": true,
          "majorityMinorityTract": true,
          "milesToCollege": 123.45,
          "milesToSchool": 123.45,
          "milesToWorship": 123.45,
          "opportunityZone": true,
          "ruralTract": true,
          "tractApplications": 123.45,
          "tractAsianPct": 123.45,
          "tractBlackPct": 123.45,
          "tractCountyCode": "<string>",
          "tractDenialRate": 123.45,
          "tractFamilyIncome": 123.45,
          "tractFloodZone": "<string>",
          "tractHispanicPct": 123.45,
          "tractHomeownershipRate": 123.45
        },
        "parties": {
          "active": {
            "brokers": [
              "<string>"
            ],
            "companies": [
              "<string>"
            ],
            "lenders": [
              "<string>"
            ],
            "originators": [
              "<string>"
            ]
          },
          "alltime": {
            "brokers": [
              "<string>"
            ],
            "companies": [
              "<string>"
            ],
            "lenders": [
              "<string>"
            ],
            "originators": [
              "<string>"
            ]
          },
          "last": {
            "originators": [
              "<string>"
            ]
          },
          "matched": {
            "brokers": [
              "<string>"
            ],
            "companies": [
              "<string>"
            ],
            "lenders": [
              "<string>"
            ],
            "originators": [
              "<string>"
            ]
          }
        }
      },
      "propertyId": "<string>",
      "reason": "member_cache_hit",
      "result": {
        "error": 123,
        "matched": 123,
        "noMatch": 123,
        "requested": 123
      },
      "status": "ok"
    }
  ],
  "summary": {
    "charged": 123,
    "failed": 123,
    "requested": 123,
    "succeeded": 123
  }
}