@model-match/api 3.48.0 → 3.49.0

package/openapi.json

@@ -15146,6 +15146,668 @@
         },
         "type": "object"
       },
+      "CompanyRetentionSnapshot": {
+        "properties": {
+          "book": {
+            "description": "Rows the computation read (sizing / provenance).",
+            "properties": {
+              "laterLoans": {
+                "type": "number"
+              },
+              "ownLoans": {
+                "type": "number"
+              },
+              "parcels": {
+                "type": "number"
+              },
+              "sales": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "ownLoans",
+              "parcels",
+              "laterLoans",
+              "sales"
+            ],
+            "type": "object"
+          },
+          "capturingCompanies": {
+            "description": "Top 10 companies that captured lost borrowers, by volume.",
+            "items": {
+              "properties": {
+                "count": {
+                  "type": "number"
+                },
+                "lane": {
+                  "enum": [
+                    "own_company",
+                    "servicer",
+                    "competitor"
+                  ],
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "nmlsId": {
+                  "type": "string"
+                },
+                "volume": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "nmlsId",
+                "name",
+                "count",
+                "volume",
+                "lane"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "capturingOriginators": {
+            "description": "Top 10 LOs that captured lost borrowers, by volume.",
+            "items": {
+              "properties": {
+                "companyName": {
+                  "type": "string"
+                },
+                "count": {
+                  "type": "number"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "nmlsId": {
+                  "type": "string"
+                },
+                "volume": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "nmlsId",
+                "name",
+                "companyName",
+                "count",
+                "volume"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "capturingTotals": {
+            "properties": {
+              "companies": {
+                "properties": {
+                  "distinct": {
+                    "type": "number"
+                  },
+                  "loans": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "distinct",
+                  "loans",
+                  "volume"
+                ],
+                "type": "object"
+              },
+              "originators": {
+                "properties": {
+                  "distinct": {
+                    "type": "number"
+                  },
+                  "loans": {
+                    "type": "number"
+                  },
+                  "unattributedLoans": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "distinct",
+                  "loans",
+                  "volume",
+                  "unattributedLoans"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "companies",
+              "originators"
+            ],
+            "type": "object"
+          },
+          "churnTrend": {
+            "items": {
+              "properties": {
+                "churned": {
+                  "type": "number"
+                },
+                "kept": {
+                  "type": "number"
+                },
+                "month": {
+                  "type": "string"
+                },
+                "retained": {
+                  "type": "number"
+                },
+                "secondPositions": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "month",
+                "churned",
+                "retained",
+                "secondPositions",
+                "kept"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "companyName": {
+            "nullable": true,
+            "type": "string"
+          },
+          "companyNmlsId": {
+            "type": "string"
+          },
+          "computedAt": {
+            "description": "When the weekly batch computed this snapshot (ISO-8601).",
+            "type": "string"
+          },
+          "lanes": {
+            "description": "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).",
+            "properties": {
+              "competitor": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              },
+              "own_company": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              },
+              "servicer": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "own_company",
+              "servicer",
+              "competitor"
+            ],
+            "type": "object"
+          },
+          "leakiestOriginators": {
+            "description": "The company's own LOs ranked by borrowers lost to other companies (top 10; only LOs with at least 10 refi events in the window).",
+            "items": {
+              "properties": {
+                "churnedCount": {
+                  "description": "Their borrowers who refinanced at another company.",
+                  "type": "number"
+                },
+                "churnedVolume": {
+                  "type": "number"
+                },
+                "keptCount": {
+                  "description": "Their borrowers the company refinanced again (any LO).",
+                  "type": "number"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "nmlsId": {
+                  "type": "string"
+                },
+                "refiRetentionRate": {
+                  "nullable": true,
+                  "type": "number"
+                },
+                "verdict": {
+                  "description": "On `refiRetentionRate` (kept ÷ (kept + churned) refi events): `quiet` under 10 events, `holding` ≥ 60%, `leaking` 35–60%, `bleeding` < 35% — the LO tab's thresholds.",
+                  "enum": [
+                    "holding",
+                    "leaking",
+                    "bleeding",
+                    "quiet"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "nmlsId",
+                "name",
+                "churnedCount",
+                "churnedVolume",
+                "keptCount",
+                "refiRetentionRate",
+                "verdict"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "period": {
+            "properties": {
+              "end": {
+                "description": "Last day (UTC, inclusive).",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                "type": "string"
+              },
+              "start": {
+                "description": "First day (UTC).",
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                "type": "string"
+              }
+            },
+            "required": [
+              "start",
+              "end"
+            ],
+            "type": "object"
+          },
+          "previous": {
+            "description": "The preceding period of equal length (for deltas); null for `allTime`.",
+            "nullable": true,
+            "properties": {
+              "period": {
+                "properties": {
+                  "end": {
+                    "description": "Last day (UTC, inclusive).",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                    "type": "string"
+                  },
+                  "start": {
+                    "description": "First day (UTC).",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "start",
+                  "end"
+                ],
+                "type": "object"
+              },
+              "summary": {
+                "properties": {
+                  "churnRate": {
+                    "type": "number"
+                  },
+                  "churnedCount": {
+                    "type": "number"
+                  },
+                  "daysToRefiPairsUsed": {
+                    "type": "number"
+                  },
+                  "keptRefiCount": {
+                    "description": "Same-LO refinances of the LO's own borrowers in the period",
+                    "type": "number"
+                  },
+                  "keptRefiVolume": {
+                    "type": "number"
+                  },
+                  "keptSecondCount": {
+                    "type": "number"
+                  },
+                  "medianDaysToRefi": {
+                    "nullable": true,
+                    "type": "number"
+                  },
+                  "propertySoldCount": {
+                    "type": "number"
+                  },
+                  "refiRetentionRate": {
+                    "description": "kept ÷ (kept + churned) refi events; null with none",
+                    "nullable": true,
+                    "type": "number"
+                  },
+                  "retainedCount": {
+                    "type": "number"
+                  },
+                  "secondPositionCount": {
+                    "type": "number"
+                  },
+                  "secondPositionVolume": {
+                    "type": "number"
+                  },
+                  "totalBorrowers": {
+                    "type": "number"
+                  },
+                  "unattributedCount": {
+                    "type": "number"
+                  },
+                  "volumeLost": {
+                    "type": "number"
+                  },
+                  "volumeRetained": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "totalBorrowers",
+                  "churnedCount",
+                  "retainedCount",
+                  "propertySoldCount",
+                  "unattributedCount",
+                  "secondPositionCount",
+                  "secondPositionVolume",
+                  "keptRefiCount",
+                  "keptRefiVolume",
+                  "keptSecondCount",
+                  "refiRetentionRate",
+                  "churnRate",
+                  "volumeLost",
+                  "volumeRetained",
+                  "medianDaysToRefi",
+                  "daysToRefiPairsUsed"
+                ],
+                "type": "object"
+              },
+              "verdict": {
+                "description": "On `refiRetentionRate` (kept ÷ (kept + churned) refi events): `quiet` under 10 events, `holding` ≥ 60%, `leaking` 35–60%, `bleeding` < 35% — the LO tab's thresholds.",
+                "enum": [
+                  "holding",
+                  "leaking",
+                  "bleeding",
+                  "quiet"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "period",
+              "summary",
+              "verdict"
+            ],
+            "type": "object"
+          },
+          "schemaVersion": {
+            "type": "integer"
+          },
+          "secondPositionLanes": {
+            "properties": {
+              "competitor": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              },
+              "own_company": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              },
+              "servicer": {
+                "properties": {
+                  "count": {
+                    "type": "number"
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "count",
+                  "volume"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "own_company",
+              "servicer",
+              "competitor"
+            ],
+            "type": "object"
+          },
+          "status": {
+            "description": "`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'.",
+            "enum": [
+              "ok",
+              "timeout",
+              "truncated"
+            ],
+            "type": "string"
+          },
+          "summary": {
+            "description": "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.",
+            "properties": {
+              "churnRate": {
+                "type": "number"
+              },
+              "churnedCount": {
+                "type": "number"
+              },
+              "daysToRefiPairsUsed": {
+                "type": "number"
+              },
+              "keptRefiCount": {
+                "description": "Same-LO refinances of the LO's own borrowers in the period",
+                "type": "number"
+              },
+              "keptRefiVolume": {
+                "type": "number"
+              },
+              "keptSecondCount": {
+                "type": "number"
+              },
+              "medianDaysToRefi": {
+                "nullable": true,
+                "type": "number"
+              },
+              "propertySoldCount": {
+                "type": "number"
+              },
+              "refiRetentionRate": {
+                "description": "kept ÷ (kept + churned) refi events; null with none",
+                "nullable": true,
+                "type": "number"
+              },
+              "retainedCount": {
+                "type": "number"
+              },
+              "secondPositionCount": {
+                "type": "number"
+              },
+              "secondPositionVolume": {
+                "type": "number"
+              },
+              "totalBorrowers": {
+                "type": "number"
+              },
+              "unattributedCount": {
+                "type": "number"
+              },
+              "volumeLost": {
+                "type": "number"
+              },
+              "volumeRetained": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "totalBorrowers",
+              "churnedCount",
+              "retainedCount",
+              "propertySoldCount",
+              "unattributedCount",
+              "secondPositionCount",
+              "secondPositionVolume",
+              "keptRefiCount",
+              "keptRefiVolume",
+              "keptSecondCount",
+              "refiRetentionRate",
+              "churnRate",
+              "volumeLost",
+              "volumeRetained",
+              "medianDaysToRefi",
+              "daysToRefiPairsUsed"
+            ],
+            "type": "object"
+          },
+          "timing": {
+            "properties": {
+              "cashOutCount": {
+                "type": "number"
+              },
+              "cashOutShare": {
+                "nullable": true,
+                "type": "number"
+              },
+              "loanTypeChangeCount": {
+                "type": "number"
+              },
+              "medianMonths": {
+                "nullable": true,
+                "type": "number"
+              },
+              "monthsToExit": {
+                "items": {
+                  "properties": {
+                    "bucket": {
+                      "type": "string"
+                    },
+                    "count": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "bucket",
+                    "count"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "rateDeltaMedian": {
+                "nullable": true,
+                "type": "number"
+              },
+              "rateDeltaPairs": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "monthsToExit",
+              "medianMonths",
+              "cashOutCount",
+              "cashOutShare",
+              "rateDeltaMedian",
+              "rateDeltaPairs",
+              "loanTypeChangeCount"
+            ],
+            "type": "object"
+          },
+          "verdict": {
+            "description": "On `refiRetentionRate` (kept ÷ (kept + churned) refi events): `quiet` under 10 events, `holding` ≥ 60%, `leaking` 35–60%, `bleeding` < 35% — the LO tab's thresholds.",
+            "enum": [
+              "holding",
+              "leaking",
+              "bleeding",
+              "quiet"
+            ],
+            "type": "string"
+          },
+          "window": {
+            "enum": [
+              "last12Months",
+              "allTime"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "companyNmlsId",
+          "companyName",
+          "window",
+          "period",
+          "computedAt",
+          "status",
+          "summary",
+          "verdict",
+          "lanes",
+          "secondPositionLanes",
+          "timing",
+          "churnTrend",
+          "capturingCompanies",
+          "capturingOriginators",
+          "capturingTotals",
+          "leakiestOriginators",
+          "previous",
+          "book"
+        ],
+        "type": "object"
+      },
       "CompanyRoleScope": {
         "description": "Which of a loan's party roles make it this company's loan. `loanCompany` (default): the company named on the loan document — one company per loan. `all`: the company appears in ANY role — loan-document company, the originating LO's employer at time of loan, the LO's organization, broker, or funding lender; a loan matching several roles counts once. `employer`: the company employed the originating LO when the loan closed. `broker`: the company brokered the loan. `lender`: the company funded the loan. `tpo`: third-party origination — the company is the loan company or lender but did NOT employ the originating LO (the `channel` dimension's `tpo` bucket as a population; `employer` is its `inHouse` counterpart). Use `all` for a broker shop's full production — its loans are often recorded under the funding lender's name, so `loanCompany` undercounts it.",
         "enum": [
@@ -43265,7 +43927,7 @@
   "info": {
     "description": "ModelMatch API — mortgage and real-estate market data.\n\n## Bulk delivery limits\n\nThe `POST /{entity}/bulk-delivery` endpoints export a full result set to\nS3 as NDJSON, JSON, CSV, or Parquet.\n\n- **Up to 5,000 rows per delivery: no entitlement required.** Available to\n  every authenticated caller.\n- **Above 5,000 rows: requires the entity's `bulk-delivery.{entity}`\n  entitlement** (e.g. `bulk-delivery.loans`). The grant's scope sets your\n  row ceiling and may also restrict which rows and fields you receive.\n\nA delivery that would exceed the limit available to you is rejected with\n`403 entitlement_missing`, reporting the matched row count and the ceiling\nthat applied. To stay under the limit, pass `limit` — the job then delivers\n(and bills for) only the first `limit` rows of a broader query.\n\n**Need a higher limit?** Email support@modelmatch.com to request the\nentitlement. Limits are raised per organization and per entity.\n\nBulk delivery is billed at 1 credit per delivered row whether or not\nan entitlement is held.\n\nInstead of a download, a delivery can be sent to a push target configured\non your workspace: pass `destination: { type: \"push-target\", targetId }`.\nThe same limits and billing apply.",
     "title": "ModelMatch API",
-    "version": "3.109.2"
+    "version": "3.110.0"
   },
   "openapi": "3.1.0",
   "paths": {
@@ -53922,6 +54584,115 @@
         ]
       }
     },
+    "/v1/companies/{nmlsId}/retention": {
+      "get": {
+        "description": "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 the company's leakiest LOs. Precomputed weekly — `computedAt` says when. 404 means not computed (no loans since 2017, or not reached yet), never zero retention.",
+        "operationId": "companyRetention",
+        "parameters": [
+          {
+            "description": "Company NMLS ID",
+            "in": "path",
+            "name": "nmlsId",
+            "required": true,
+            "schema": {
+              "description": "Company NMLS ID",
+              "type": "string"
+            }
+          },
+          {
+            "description": "`last12Months` (the trailing 12 months to the computation date, with the 12 months before as `previous`) or `allTime` (2017-01-01 on). Default `last12Months`.",
+            "in": "query",
+            "name": "window",
+            "required": false,
+            "schema": {
+              "default": "last12Months",
+              "description": "`last12Months` (the trailing 12 months to the computation date, with the 12 months before as `previous`) or `allTime` (2017-01-01 on). Default `last12Months`.",
+              "enum": [
+                "last12Months",
+                "allTime"
+              ],
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CompanyRetentionSnapshot"
+                }
+              }
+            },
+            "description": "The stored snapshot"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SearchUnavailable"
+                }
+              }
+            },
+            "description": "Search timed out or the cluster is overloaded — retry after `Retry-After` seconds."
+          }
+        },
+        "summary": "Company borrower retention (weekly snapshot)",
+        "tags": [
+          "Companies"
+        ]
+      }
+    },
     "/v1/companies/{nmlsId}/sponsored-individuals": {
       "post": {
         "operationId": "companySponsoredIndividuals",