Originators

Borrower retention report for this LO

postapi.modelmatch.com/v1/originators/{nmlsId}/retention

Classifies every loan this LO originated since 2017 against every later loan and sale on the same parcel, for the period start–end: borrowers kept (the LO refinanced them again), lost (refinanced elsewhere — churnedLoans, with who captured them), sold, or a second lien taken elsewhere. Returns the summary, capture lanes (same funding lender vs other companies), capturing companies / LOs (top 25 + full-population totals), timing, monthly trend, the newest 500 loss rows, and exit signals on the retained book (atRisk). compare adds a second period's summary and monthly trend (previous) from the same scan. A very large book that cannot be read in time answers status: "timeout".

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Path parameters

nmlsIdstringrequired

Originator NMLS ID

Body application/json

compareobject

Optional comparison period (e.g. the prior 14 months). Its summary and monthly trend come back as previous; it reuses this request's loan scan, so it costs no extra search.

Show child attributes

endstringrequired

Last day of the period (UTC, inclusive).

startstringrequired

First day of the period (UTC).

endstringrequired

Last day of the period (UTC, inclusive).

includeAtRiskboolean

Scan the retained book for exit signals (listed / likely to sell / rate incentive). Default true.

startstringrequired

First day of the period (UTC).

Responses

200objectRetention report

Show attributes

atRiskobject | nullrequired

Exit signals on the retained book; null when not requested or the scan could not complete.

Show child attributes

equityBandsobject[]required

Show child attributes

bandstringrequired

countnumberrequired

highEquityLowRatenumberrequired

joinednumberrequired

likelyToSellnumberrequired

listedNownumberrequired

medianEquityPctnumber | nullrequired

medianRatenumber | nullrequired

rateIncentivenumberrequired

retainedScannednumberrequired

rowsobject[]required

Show child attributes

addressstringrequired

borrowerstringrequired

currentBalancenumber | nullrequired

currentLenderstring | nullrequired

currentRatenumber | nullrequired

equityPctnumber | nullrequired

flagsenum[]required

Options:listedlikely_sellrate

homeValuenumber | nullrequired

listPricenumber | nullrequired

listedDatenumber | nullrequired

listingStatusstring | nullrequired

originalAmountnumberrequired

originalLoanDatenumberrequired

originalLoanTypestringrequired

propensityCategorystring | nullrequired

propertyIdstringrequired

salePropensitynumber | nullrequired

signallingnumberrequired

capturingCompaniesobject[]required

Show child attributes

countnumberrequired

laneenumrequired

Options:own_companyservicercompetitor

namestringrequired

nmlsIdstringrequired

volumenumberrequired

capturingOriginatorsobject[]required

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

secondCompaniesobjectrequired

Show child attributes

distinctnumberrequired

loansnumberrequired

volumenumberrequired

churnByLoanTypeobject[]required

Show child attributes

countnumberrequired

typestringrequired

volumenumberrequired

churnTrendobject[]required

Show child attributes

churnednumberrequired

keptnumberrequired

monthstringrequired

retainednumberrequired

secondPositionsnumberrequired

churnedLoansobject[]required

Show child attributes

addressstringrequired

borrowerstringrequired

capturingAmountnumberrequired

capturingCompanystringrequired

capturingCompanyNmlsIdstringrequired

capturingLenderstringrequired

capturingLoNamestringrequired

capturingLoNmlsIdstringrequired

capturingLoanTypestringrequired

capturingRatenumber | nullrequired

cashOutbooleanrequired

currentobject | nullrequired

What the parcel looks like today, when a scored snapshot newer than the event joined; null otherwise (unknown, never 'retained').

Show child attributes

currentBalancenumber | nullrequired

currentLenderstring | nullrequired

currentRatenumber | nullrequired

lastSaleDatenumber | nullrequired

loStillActivebooleanrequired

ownerChangedboolean | nullrequired

daysToEventnumberrequired

eventDatenumberrequired

kindenumrequired

Options:refisecond

laneenumrequired

Options:own_companyservicercompetitor

originalAmountnumberrequired

originalLenderstringrequired

originalLoanDatenumberrequired

originalLoanTypestringrequired

originalRatenumber | nullrequired

originalTransactionTypestringrequired

propertyIdstringrequired

sameBorrowerboolean | nullrequired

lanesobjectrequired

Show child attributes

competitorobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

own_companyobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

servicerobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

previousobject | nullrequired

The compare period's summary and monthly trend, when asked.

Show child attributes

churnTrendobject[]required

Show child attributes

churnednumberrequired

keptnumberrequired

monthstringrequired

retainednumberrequired

secondPositionsnumberrequired

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

secondPositionCompaniesobject[]required

Show child attributes

countnumberrequired

laneenumrequired

Options:own_companyservicercompetitor

namestringrequired

nmlsIdstringrequired

volumenumberrequired

secondPositionLanesobjectrequired

Show child attributes

competitorobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

own_companyobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

servicerobjectrequired

Show child attributes

countnumberrequired

volumenumberrequired

statusenumrequired

timeout when the LO's loan history could not be read within the time budget (very large book): every count is then 0 and means 'not available', not 'none'.

Options:oktimeout

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

timingobjectrequired

Show child attributes

cashOutCountnumberrequired

cashOutSharenumber | nullrequired

loanTypeChangeCountnumberrequired

medianMonthsnumber | nullrequired

monthsToExitobject[]required

Show child attributes

bucketstringrequired

countnumberrequired

rateDeltaMediannumber | nullrequired

rateDeltaPairsnumberrequired

truncatedbooleanrequired

A loan / sale scan hit its row cap; counts cover the rows read.

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 POST "https://api.modelmatch.com/v1/originators/<nmlsId>/retention" \
  -H "x-api-key: $MODEL_MATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end": "2025-08-15",
    "start": "2025-08-15",
    "includeAtRisk": true
  }'

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

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

const { data, error } = await client.originators.retention({
  path: {
    nmlsId: "<nmlsId>"
  },
  body: {
    end: "2025-08-15",
    start: "2025-08-15",
    includeAtRisk: true
  }
});

import os
import requests

res = requests.post(
    "https://api.modelmatch.com/v1/originators/<nmlsId>/retention",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
    json={
        "end": "2025-08-15",
        "start": "2025-08-15",
        "includeAtRisk": True
    },
)
data = res.json()

200 response

{
  "atRisk": {
    "equityBands": [
      {
        "band": "<string>",
        "count": 123.45
      }
    ],
    "highEquityLowRate": 123.45,
    "joined": 123.45,
    "likelyToSell": 123.45,
    "listedNow": 123.45,
    "medianEquityPct": 123.45,
    "medianRate": 123.45,
    "rateIncentive": 123.45,
    "retainedScanned": 123.45,
    "rows": [
      {
        "address": "<string>",
        "borrower": "<string>",
        "currentBalance": 123.45,
        "currentLender": "<string>",
        "currentRate": 123.45,
        "equityPct": 123.45,
        "flags": [
          "listed"
        ],
        "homeValue": 123.45,
        "listPrice": 123.45,
        "listedDate": 123.45,
        "listingStatus": "<string>",
        "originalAmount": 123.45,
        "originalLoanDate": 123.45,
        "originalLoanType": "<string>",
        "propensityCategory": "<string>",
        "propertyId": "<string>",
        "salePropensity": 123.45
      }
    ],
    "signalling": 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
    },
    "secondCompanies": {
      "distinct": 123.45,
      "loans": 123.45,
      "volume": 123.45
    }
  },
  "churnByLoanType": [
    {
      "count": 123.45,
      "type": "<string>",
      "volume": 123.45
    }
  ],
  "churnTrend": [
    {
      "churned": 123.45,
      "kept": 123.45,
      "month": "<string>",
      "retained": 123.45,
      "secondPositions": 123.45
    }
  ],
  "churnedLoans": [
    {
      "address": "<string>",
      "borrower": "<string>",
      "capturingAmount": 123.45,
      "capturingCompany": "<string>",
      "capturingCompanyNmlsId": "<string>",
      "capturingLender": "<string>",
      "capturingLoName": "<string>",
      "capturingLoNmlsId": "<string>",
      "capturingLoanType": "<string>",
      "capturingRate": 123.45,
      "cashOut": true,
      "current": {
        "currentBalance": 123.45,
        "currentLender": "<string>",
        "currentRate": 123.45,
        "lastSaleDate": 123.45,
        "loStillActive": true,
        "ownerChanged": true
      },
      "daysToEvent": 123.45,
      "eventDate": 123.45,
      "kind": "refi",
      "lane": "own_company",
      "originalAmount": 123.45,
      "originalLender": "<string>",
      "originalLoanDate": 123.45,
      "originalLoanType": "<string>"
    }
  ],
  "lanes": {
    "competitor": {
      "count": 123.45,
      "volume": 123.45
    },
    "own_company": {
      "count": 123.45,
      "volume": 123.45
    },
    "servicer": {
      "count": 123.45,
      "volume": 123.45
    }
  },
  "previous": {
    "churnTrend": [
      {
        "churned": 123.45,
        "kept": 123.45,
        "month": "<string>",
        "retained": 123.45,
        "secondPositions": 123.45
      }
    ],
    "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
    }
  },
  "secondPositionCompanies": [
    {
      "count": 123.45,
      "lane": "own_company",
      "name": "<string>",
      "nmlsId": "<string>",
      "volume": 123.45
    }
  ],
  "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
  },
  "truncated": true
}