Submit a bulk-delivery job for companies

Queues an ECS task that dumps every matching companies document to S3 in the requested format. Returns 202 with a jobId; poll GET /v1/companies/bulk-delivery/{jobId} for status + the signed download URL.

Row limit. Deliveries of up to 1,000 rows need no entitlement. Above that, the org's bulk-delivery.companies entitlement is required and its scope (row ceiling, row filters, allowed fields) governs the delivery; without it the request is rejected with 403 entitlement_missing. Pass limit at or below the ceiling to deliver a capped subset of a broader query. Email support@modelmatch.com to request a limit increase.

Delivery is billed at 1 credit per 100 rows regardless of entitlement.

Authorization

x-api-key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

advancedFilters?|||

filters?|||

flatFilters?

footprint?|array<>

Scoped lender filter(s). Each entry names ONE lender relationship and the metric bounds that must hold INSIDE it — {lender:'<id>', volume:{gte:50000000}} means '$50M funded by that lender', not '$50M somewhere and one loan with them'. Several entries AND together. Geographic market filters are not available on companies: that rollup is not written for these records, so use POST /companies/{nmlsId}/markets (live-aggregated) for a company's geography.

lenderFilters?array<>

lenderMatchMode?LenderMatchMode

Value in"and" | "or"

locationBasis?string

What the geographic filters (city/state/zip/zipCode/geoPoint) select. registeredAddress (the default) matches companies whose REGISTERED BUSINESS ADDRESS is in the place — a company registered elsewhere is excluded no matter how much it lends there. production matches companies that PRODUCED loans in the place, whatever address they are registered at, which is usually what a geographic search means. It changes only WHICH companies are returned: every non-geographic filter applies identically either way, scopedVolume/scopedUnits report in-geography production under both, and countCompanies honors this field, so a count and a list built from the same body always describe the same set. Measured on an 8-state Southeast search: under registeredAddress the largest actual producer in the region is absent at any depth, because it is registered in Michigan.

Value in"registeredAddress" | "production"

pagination?

period?Period

Value in

"2017" | "2018" | "2019" | "2020" | "2021" | "2022" | "2023" | "2024" | "2025" | "2026" | "last3Months" | "last6Months" | "last12Months" | "last14Months" | "last16Months" | "last18Months" | "last24Months" | "yearToDate" | "allTime"

sort?array<>

fields?array<>

Optional output column projection, named by the response DTO fields (the same camelCase fields the list endpoint returns, e.g. city, interestRate). Intersected with the entitlement scope's allowedFields and the entity's full column set. If empty after intersection, falls back to all columns. It also SELECTS the opt-in columns, which are not part of the list DTO and are never delivered unless named here: communityLending (properties, originators, companies, branches) — the Community Lending neighborhood profile, identical to the block on the entity's detail endpoint; parties (properties) — the mortgage parties attributed to the parcel, by attribution scope; and marketCount / countyCount / stateCount / zipCount / lenderCount (originators) — the market-breadth rollups you can already filter on. In csv and parquet the two block columns are JSON-encoded cells; in json and ndjson they are nested objects.

format*BulkDeliveryFormat

Output file format for the delivered dataset. Every format contains the same rows — the entity's list/summary DTO (e.g. LoanSummary), one record per row. ndjson: gzipped newline-delimited JSON (application/x-ndjson, .ndjson.gz). json: a single JSON array (application/json, .json). csv: RFC 4180 (text/csv, .csv). parquet: typed columnar Apache Parquet — scalar fields keep their DTO types, nested fields are JSON-encoded strings (application/vnd.apache.parquet, .parquet).

Value in"ndjson" | "json" | "csv" | "parquet"

limit?integer

Optional hard cap on the number of rows delivered — and therefore billed (1 credit / 100 rows). The job delivers the first limit rows in sort order (default newest-first) and bills only for those. If the query matches fewer than limit, all matches are delivered. Distinct from the page-size size field, which is ignored on this endpoint. The row ceiling still applies — 1,000 without the entity's bulk-delivery entitlement, or the entitlement's maxRows with it. A limit above the ceiling is rejected, but a limit at or below it lets you export a capped top-N even when the full match exceeds the ceiling — which is the intended way to run a broad query under the 1,000-row allowance.

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/v1/companies/bulk-delivery" \  -H "Content-Type: application/json" \  -d '{    "format": "parquet"  }'

{
  "entityType": "string",
  "estimatedTotal": 0,
  "format": "parquet",
  "jobId": "string",
  "maxRows": 1,
  "status": "queued"
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "balance": 0,
  "cost": 0,
  "error": "payment_required",
  "message": "string",
  "reason": "out_of_credits"
}

{
  "entitlementKey": "string",
  "error": "entitlement_missing",
  "estimatedTotal": 0,
  "maxRows": 1,
  "message": "string"
}

{
  "error": "string"
}

Submit a bulk-delivery job for companies

Authorization

Request Body

Response Body

202application/json

400application/json

401application/json

402application/json

403application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`