Companies

Company borrower retention (weekly snapshot)

getapi.modelmatch.com/v1/companies/{nmlsId}/retention

How well a company keeps its borrowers when they refinance: kept (refinanced again by ANY LO at the company) vs lost to other companies, with the capturing companies and LOs, timing, the trend, a verdict, and per-LO retention for the company's own loan officers. Precomputed weekly — computedAt says when. 404 means not computed (no loans since 2017, or not reached yet), never zero retention.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Path parameters

nmlsIdstringrequired

Company NMLS ID

Query parameters

windowenumdefault: "last12Months"

last12Months (the trailing 12 months to the computation date, with the 12 months before as previous) or allTime (2017-01-01 on). Default last12Months.

Options:last12MonthsallTime

Responses

200objectThe stored snapshot

Show attributes

activeListingsobject | nullrequired

Retained borrowers listed for sale now, on loans by the company's own LOs: the count and top LOs (rows: GET /companies/{nmlsId}/retention/active-listings). Same for every window. Null until the weekly batch has checked listings for this company.

Show child attributes

computedAtstringrequired

When the listings were checked (ISO-8601) — the run that wrote the rows. Listings are as of this time, not live.

parcelsCheckedintegerrequired

Retained parcels whose latest company loan was written by an LO the company employed on it — the population checked for listings.

statusenumrequired

timeout: the listing check did not finish in this run, so the previous run's rows and counts are kept (or none, on a first run).

Options:oktimeout

teamobject | null

The current-team view's counts; null until the batch has checked it for this company.

Show child attributes

rosterintegerrequired

Current LOs (active sponsorships) checked.

statusenumrequired

Options:oktimeout

totalintegerrequired

Rows in view=team: listings on loans by the company's current LOs, written at the company or at a previous employer.

writtenElsewhereintegerrequired

Of those, loans the LOs wrote at a previous employer.

topOriginatorsobject[]required

Top 10 LOs by active listings.

Show child attributes

countintegerrequired

namestringrequired

nmlsIdstringrequired

totalintegerrequired

Retained borrowers whose home is listed for sale right now, on loans written by the company's own LOs.

bookobjectrequired

Rows the computation read (sizing / provenance).

Show child attributes

laterLoansnumberrequired

ownLoansnumberrequired

parcelsnumberrequired

salesnumberrequired

capturingCompaniesobject[]required

Top 10 companies that captured lost borrowers, by volume.

Show child attributes

countnumberrequired

laneenumrequired

Options:own_companyservicercompetitor

namestringrequired

nmlsIdstringrequired

volumenumberrequired

capturingOriginatorsobject[]required

Top 10 LOs that captured lost borrowers, by volume.

Show child attributes

companyNamestringrequired

countnumberrequired

namestringrequired

nmlsIdstringrequired

volumenumberrequired

capturingTotalsobjectrequired

Show child attributes

companiesobjectrequired

Show child attributes

distinctnumberrequired

loansnumberrequired

volumenumberrequired

originatorsobjectrequired

Show child attributes

distinctnumberrequired

loansnumberrequired

unattributedLoansnumberrequired

volumenumberrequired

churnTrendobject[]required

Show child attributes

churnednumberrequired

keptnumberrequired

monthstringrequired

retainednumberrequired

secondPositionsnumberrequired

companyNamestring | nullrequired

companyNmlsIdstringrequired

computedAtstringrequired

When the weekly batch computed this snapshot (ISO-8601).

lanesobjectrequired

Where lost refinances went: the borrower's funding lender (servicer) or another company (competitor). own_company is always 0 at company level (those are kept).

Show child attributes

competitorobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

own_companyobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

servicerobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

likelyToSellobject | nullrequired

Retained borrowers likely to list their home for sale (likely-to-list score 90+, not listed now), on loans by the company's own LOs: the count and top LOs (rows: GET /companies/{nmlsId}/retention/likely-to-sell). Same for every window. Null until the weekly batch has checked this company.

Show child attributes

computedAtstringrequired

When the batch checked these borrowers (ISO-8601) — the run that wrote the rows. As of this time, not live.

parcelsCheckedintegerrequired

Retained parcels whose latest company loan was written by an LO the company employed on it — the population checked (the same one active listings checks).

parcelsScoredintegerrequired

Of those, parcels with a likely-to-list score on file. A parcel without one is unknown, not unlikely.

statusenumrequired

timeout: the check did not finish in this run, so the previous run's rows and counts are kept (or none, on a first run).

Options:oktimeout

teamobject | null

The current-team view's counts; null until the batch has checked it for this company.

Show child attributes

rosterintegerrequired

Current LOs (active sponsorships) checked.

statusenumrequired

Options:oktimeout

totalintegerrequired

Rows in view=team: borrowers likely to list on loans by the company's current LOs, written at the company or at a previous employer.

writtenElsewhereintegerrequired

Of those, loans the LOs wrote at a previous employer.

topOriginatorsobject[]required

Top 10 LOs by borrowers likely to list.

Show child attributes

countintegerrequired

namestringrequired

nmlsIdstringrequired

totalintegerrequired

Retained borrowers, on loans written by the company's own LOs, whose home has a likely-to-list score of 90 or more and is not listed for sale or under contract now.

originatorRetentionobject[]required

Refinance retention for the company's own loan officers, ranked by borrowers who refinanced at another company (top 10; only LOs with at least 10 refi events in the window).

Show child attributes

churnedCountnumberrequired

Their borrowers who refinanced at another company.

churnedVolumenumberrequired

keptCountnumberrequired

Their borrowers the company refinanced again (any LO).

namestringrequired

nmlsIdstringrequired

refiRetentionRatenumber | nullrequired

verdictenumrequired

On refiRetentionRate (kept ÷ (kept + churned) refi events): quiet under 10 events, holding ≥ 60%, leaking 35–60%, bleeding < 35% — the LO tab's thresholds.

Options:holdingleakingbleedingquiet

periodobjectrequired

Show child attributes

endstringrequired

Last day (UTC, inclusive).

startstringrequired

First day (UTC).

previousobject | nullrequired

The preceding period of equal length (for deltas); null for allTime.

Show child attributes

periodobjectrequired

Show child attributes

endstringrequired

Last day (UTC, inclusive).

startstringrequired

First day (UTC).

summaryobjectrequired

Show child attributes

churnRatenumberrequired

churnedCountnumberrequired

daysToRefiPairsUsednumberrequired

keptRefiCountnumberrequired

Same-LO refinances of the LO's own borrowers in the period

keptRefiVolumenumberrequired

keptSecondCountnumberrequired

medianDaysToRefinumber | nullrequired

propertySoldCountnumberrequired

refiRetentionRatenumber | nullrequired

kept ÷ (kept + churned) refi events; null with none

retainedCountnumberrequired

secondPositionCountnumberrequired

secondPositionVolumenumberrequired

totalBorrowersnumberrequired

unattributedCountnumberrequired

volumeLostnumberrequired

volumeRetainednumberrequired

verdictenumrequired

On refiRetentionRate (kept ÷ (kept + churned) refi events): quiet under 10 events, holding ≥ 60%, leaking 35–60%, bleeding < 35% — the LO tab's thresholds.

Options:holdingleakingbleedingquiet

schemaVersionintegerrequired

secondPositionLanesobjectrequired

Show child attributes

competitorobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

own_companyobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

servicerobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

statusenumrequired

truncated: a loan / sale scan hit its row cap, so counts cover the rows read. timeout: the book could not be read within the batch's per-company budget — every count is 0 and means 'not available', not 'none'.

Options:oktimeouttruncated

summaryobjectrequired

Same fields as the LO report. At company level a refinance by ANY LO at the company is kept; only a refinance at another company is churned.

Show child attributes

churnRatenumberrequired

churnedCountnumberrequired

daysToRefiPairsUsednumberrequired

keptRefiCountnumberrequired

Same-LO refinances of the LO's own borrowers in the period

keptRefiVolumenumberrequired

keptSecondCountnumberrequired

medianDaysToRefinumber | nullrequired

propertySoldCountnumberrequired

refiRetentionRatenumber | nullrequired

kept ÷ (kept + churned) refi events; null with none

retainedCountnumberrequired

secondPositionCountnumberrequired

secondPositionVolumenumberrequired

totalBorrowersnumberrequired

unattributedCountnumberrequired

volumeLostnumberrequired

volumeRetainednumberrequired

timingobjectrequired

Show child attributes

cashOutCountnumberrequired

cashOutSharenumber | nullrequired

loanTypeChangeCountnumberrequired

medianMonthsnumber | nullrequired

monthsToExitobject[]required

Show child attributes

bucketstringrequired

countnumberrequired

rateDeltaMediannumber | nullrequired

rateDeltaPairsnumberrequired

verdictenumrequired

On refiRetentionRate (kept ÷ (kept + churned) refi events): quiet under 10 events, holding ≥ 60%, leaking 35–60%, bleeding < 35% — the LO tab's thresholds.

Options:holdingleakingbleedingquiet

windowenumrequired

Options:last12MonthsallTime

400objectValidation error

401objectUnauthorized

403objectForbidden (authenticated, but missing required context — e.g. no active organization)

404objectNot found

413objectResponse payload too large — detail endpoint capped to fit Lambda response limits

503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.

curl -X GET "https://api.modelmatch.com/v1/companies/<nmlsId>/retention" \
  -H "x-api-key: $MODEL_MATCH_API_KEY"

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

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

const { data, error } = await client.companies.retention({
  path: {
    nmlsId: "<nmlsId>"
  }
});

import os
import requests

res = requests.get(
    "https://api.modelmatch.com/v1/companies/<nmlsId>/retention",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
)
data = res.json()

200 response

{
  "activeListings": {
    "computedAt": "<string>",
    "parcelsChecked": 123,
    "status": "ok",
    "team": {
      "roster": 123,
      "status": "ok",
      "total": 123,
      "writtenElsewhere": 123
    },
    "topOriginators": [
      {
        "count": 123,
        "name": "<string>",
        "nmlsId": "<string>"
      }
    ],
    "total": 123
  },
  "book": {
    "laterLoans": 123.45,
    "ownLoans": 123.45,
    "parcels": 123.45,
    "sales": 123.45
  },
  "capturingCompanies": [
    {
      "count": 123.45,
      "lane": "own_company",
      "name": "<string>",
      "nmlsId": "<string>",
      "volume": 123.45
    }
  ],
  "capturingOriginators": [
    {
      "companyName": "<string>",
      "count": 123.45,
      "name": "<string>",
      "nmlsId": "<string>",
      "volume": 123.45
    }
  ],
  "capturingTotals": {
    "companies": {
      "distinct": 123.45,
      "loans": 123.45,
      "volume": 123.45
    },
    "originators": {
      "distinct": 123.45,
      "loans": 123.45,
      "unattributedLoans": 123.45,
      "volume": 123.45
    }
  },
  "churnTrend": [
    {
      "churned": 123.45,
      "kept": 123.45,
      "month": "<string>",
      "retained": 123.45,
      "secondPositions": 123.45
    }
  ],
  "companyName": "<string>",
  "companyNmlsId": "<string>",
  "computedAt": "<string>",
  "lanes": {
    "competitor": {
      "count": 123.45,
      "volume": 123.45
    },
    "own_company": {
      "count": 123.45,
      "volume": 123.45
    },
    "servicer": {
      "count": 123.45,
      "volume": 123.45
    }
  },
  "likelyToSell": {
    "computedAt": "<string>",
    "parcelsChecked": 123,
    "parcelsScored": 123,
    "status": "ok",
    "team": {
      "roster": 123,
      "status": "ok",
      "total": 123,
      "writtenElsewhere": 123
    },
    "topOriginators": [
      {
        "count": 123,
        "name": "<string>",
        "nmlsId": "<string>"
      }
    ],
    "total": 123
  },
  "originatorRetention": [
    {
      "churnedCount": 123.45,
      "churnedVolume": 123.45,
      "keptCount": 123.45,
      "name": "<string>",
      "nmlsId": "<string>",
      "refiRetentionRate": 123.45,
      "verdict": "holding"
    }
  ],
  "period": {
    "end": "<string>",
    "start": "<string>"
  },
  "previous": {
    "period": {
      "end": "<string>",
      "start": "<string>"
    },
    "summary": {
      "churnRate": 123.45,
      "churnedCount": 123.45,
      "daysToRefiPairsUsed": 123.45,
      "keptRefiCount": 123.45,
      "keptRefiVolume": 123.45,
      "keptSecondCount": 123.45,
      "medianDaysToRefi": 123.45,
      "propertySoldCount": 123.45,
      "refiRetentionRate": 123.45,
      "retainedCount": 123.45,
      "secondPositionCount": 123.45,
      "secondPositionVolume": 123.45,
      "totalBorrowers": 123.45,
      "unattributedCount": 123.45,
      "volumeLost": 123.45,
      "volumeRetained": 123.45
    },
    "verdict": "holding"
  },
  "schemaVersion": 123,
  "secondPositionLanes": {
    "competitor": {
      "count": 123.45,
      "volume": 123.45
    },
    "own_company": {
      "count": 123.45,
      "volume": 123.45
    },
    "servicer": {
      "count": 123.45,
      "volume": 123.45
    }
  },
  "status": "ok",
  "summary": {
    "churnRate": 123.45,
    "churnedCount": 123.45,
    "daysToRefiPairsUsed": 123.45,
    "keptRefiCount": 123.45,
    "keptRefiVolume": 123.45,
    "keptSecondCount": 123.45,
    "medianDaysToRefi": 123.45,
    "propertySoldCount": 123.45,
    "refiRetentionRate": 123.45,
    "retainedCount": 123.45,
    "secondPositionCount": 123.45,
    "secondPositionVolume": 123.45,
    "totalBorrowers": 123.45,
    "unattributedCount": 123.45,
    "volumeLost": 123.45,
    "volumeRetained": 123.45
  },
  "timing": {
    "cashOutCount": 123.45,
    "cashOutShare": 123.45,
    "loanTypeChangeCount": 123.45,
    "medianMonths": 123.45,
    "monthsToExit": [
      {
        "bucket": "<string>",
        "count": 123.45
      }
    ],
    "rateDeltaMedian": 123.45,
    "rateDeltaPairs": 123.45
  },
  "verdict": "holding"
}