Submit a bulk-delivery job for agents

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

Row limit. Deliveries of up to 5,000 rows need no entitlement. Above that, the org's bulk-delivery.agents 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 row regardless of entitlement (deliveries submitted from the ModelMatch web app are not billed).

Push-target destination. Pass destination: { type: "push-target", targetId } to have the finished rows sent to a configured push target instead of downloaded. The target is checked before anything is queued; a refusal returns the push target's status and code (TARGET_NOT_FOUND 404, FORBIDDEN 403, PLAN_REQUIRED 402, TARGET_DISABLED 409, ENTITY_MISMATCH 400). Limits and billing are the same as a file delivery.

Authorization

x-api-key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

advancedFilters?|||

crmList?

Scope the result to the caller's CRM. Resolved against the caller's ACTIVE WORKSPACE at query time — list membership is read server-side, so the request never carries member ids. Only real-estate-agent members count; loan officers and manual (unlinked) records on the same list are ignored. mode: "in" with no matching members returns an empty page (not an unfiltered one). Errors: 400 crm_list_requires_workspace when the caller has no active workspace (API-key / OAuth callers must select an organization), 403 / 404 when a named list is not visible to the caller or does not exist, and 400 crm_list_too_large when the selected lists hold more than 50,000 agents in total — narrow the selection rather than get a silently partial answer.

filters?|||

flatFilters?

footprint?|array<>

Scoped lender filter(s). Each entry names ONE financing relationship and the metric bounds that must hold INSIDE it — {lender:'<id>', volume:{gte:10000000}} means '$10M of their sales were financed by that lender', not '$10M of sales and one deal with them'. Several entries AND together. Geographic market filters are not available here: use POST /v1/agents/{id}/markets (live-aggregated) for an agent's geography.

lenderFilters?array<>

lenderMatchMode?LenderMatchMode

Value in"and" | "or"

locationSource?AgentLocationSource

Which location signal city/state/zip/county, geoPoint and near match. any (default) = an office OR a market they transacted in (geoPoint: any office on record); office = their CURRENT office (a bare state also matches the state on their member record; county = the office inside the county boundary); production = transaction markets only.

Value in"any" | "office" | "production"

losOnMyTeam?

Relationship with loan officers at the CALLER's company, resolved server-side from the caller's profile NMLS id and that LO's current employer; the caller's own deals never count. 400 los_on_my_team_requires_company when the caller has no NMLS id on their profile or it resolves to no company.

near?array<>

Radius search, entries OR'd, on the locationSource points (current office / transactions / either). With city+state an entry also matches addresses in that city beyond the radius.

Items1 <= items <= 50

pagination?

period?Period

Pre-aggregated period block. Rolling windows (last30Days, last60Days, last90Days, previousMonth, currentMonth) are NOT accepted here and return 400; they are supported on the loans, sales and market endpoints (list, count, breakdowns, analytics summary / time-series / chart) (see DatedPeriod).

Value in

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

productMix?array<>

Agents whose buyers financed with these loan products in the selected period, ANDed: [{product: "fha"}, {product: "va", minShare: 10}]. Not a whole-book share — the index stores product mix per mortgage company only.

Items1 <= items <= 10

sideDominance?array<>

Which side the agent mostly represents in the selected period, OR'd: buyer = more buyer-side than seller-side deals, seller = the reverse (a tie is neither), dual = at least one dual-agency deal.

Items1 <= items

sort?array<>

columns?array<>

A FORMATTED file: its columns, in order, with header labels and number formats — for format csv or xlsx only, and not combined with fields or a push-target destination (400 columns_format_unsupported / columns_with_fields / columns_with_destination). Every field a column reads is gated by the entitlement exactly as if it were listed in fields: a withheld field drops out of a column's fallback list, and a column with nothing left is omitted. An unknown field is a 400 unknown_column_field. No id column is added. A formatted csv starts with a UTF-8 byte-order mark and uses CRLF line endings, so Excel opens it with accented names intact. Columns may read any DTO field and any opt-in column fields documents, including the computed governmentPct, branchCount and managerName / managerNmlsId.

Items1 <= items <= 200

destination?

Where the finished delivery goes. Omit for the default — a file you download from the status endpoint. push-target: when the job completes, the rows are handed to the named push target, which sends them to its configured HTTPS destination using its own field mapping and signing. The target is checked at submit (it must exist, be enabled, accept this entity, and be usable by you on your plan) — a failed check rejects the submit with the push target's error code. format is ignored (the handoff is always gzipped NDJSON), and when the target's mapping reads only some fields, only those fields (plus id) are delivered. Row limits, entitlements, limit, and billing (1 credit / row) are unchanged, except that deliveries submitted from the ModelMatch web app are not billed. Poll the job for pushBatchId; a handoff that cannot be completed fails the job with error push_handoff_failed and is not billed.

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; marketCount / countyCount / stateCount / zipCount / lenderCount (originators) — the market-breadth rollups you can already filter on; and the computed governmentPct (originators: FHA + VA percent of loans, 0–100), branchCount (companies: NMLS branch count) and managerName / managerNmlsId (branches: the first branch manager). Agents also offer email2 / phone2 (the best-ranked email / phone distinct from email / phone, admitted by the email / phone entitlement field), bestEmail / bestEmail2 and bestPhone / bestPhone2 (the best and runner-up contact over every email / phone on the record, email / phone included — the pair the ModelMatch web app's agent export shows; same entitlement fields), officePhone (admitted by phone), activeListings (current active listings; null when unknown), and the profile-link columns facebook, instagram, linkedin, twitter, youtube, tiktok, zillow, otherLinks (a ; -joined list of profile URLs on no known platform) — all admitted by the links entitlement field. Loans offer the list row's transaction-export fields (employerName, employerNmlsId, brokerName, titleCompanyName, soldAgentName, listAgentName, coListAgentName, buyer1FirstMiddle … seller2Last). In csv and parquet the two block columns are JSON-encoded cells; in json and ndjson they are nested objects. Windowed production (originators, agents, companies, branches): name <field>_<n>mo for n in 3, 6, 12, 14, 18, 24 to get a production field for that trailing window regardless of period — e.g. volume_3mo, units_6mo, purchaseVolume_24mo. Available for originators volume, units, avgLoanAmount, purchaseVolume, purchaseUnits, refinanceVolume, refinanceUnits, conventionalPct, fhaPct, vaPct; agents volume, units, avgSoldPrice, buyerVolume, buyerUnits, sellerVolume, sellerUnits, totalOriginatorsWorkedWith, totalCompaniesWorkedWith, totalLendersWorkedWith; companies volume, units, avgLoanAmount, loCount; branches volume, units, avgLoanAmount, purchasePct, refinancePct, loCount. Numbers (null when the window has no data); an entitlement that allows a field allows every window of it.

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). xlsx: a single-sheet Excel workbook with a bold, frozen header row — numbers are numeric cells, everything else (ids, zips, phones) text cells (.xlsx). Pair with columns for labelled headers and number formats. Required on submit unless destination is a push target, which always delivers gzipped NDJSON (a missing format on a file delivery is a 400 format_required).

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

limit?integer

Optional hard cap on the number of rows delivered — and therefore billed (1 credit / row). 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 — 5,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 5,000-row allowance.

Range0 <= value

Response Body

`application/json`

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

{
  "billing": "credits",
  "destination": {
    "targetId": "string",
    "type": "push-target"
  },
  "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"
}

{
  "code": "TARGET_NOT_FOUND",
  "error": "TARGET_NOT_FOUND",
  "message": "string"
}

{
  "code": "TARGET_NOT_FOUND",
  "error": "TARGET_NOT_FOUND",
  "message": "string"
}

{
  "error": "string"
}

Submit a bulk-delivery job for agents

Authorization

Request Body

Response Body

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`