Maturr
Get started
Docs / API

REST API v1.

Read-only access to Maturr's CRE loan-level data. Five endpoints, JSON in, JSON out. Authenticated with a Bearer API key. Included on Advanced and Enterprise plans.

Machine-readable OpenAPI 3.1 spec: /api/v1/openapi.json

Quick start

  1. Be on the Advanced or Enterprise plan. Upgrade at Settings → Billing.
  2. Create a key at Settings → API keys. The full token is displayed once — copy it immediately.
  3. Send it as a Bearer header on every request:
    curl 'https://www.maturr.io/api/v1/properties?msa_id=33100&limit=5' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Authentication

Every request must include an Authorization: Bearer <token> header. Tokens are opaque 32-byte hex strings. We never store the raw token — only its SHA-256 hash — so once the dashboard closes the create dialog, neither you nor Maturr support can recover it; create a new key instead.

Keys are scoped to a single user account. The owner's plan determines the rate limit (see below). Keys can be revoked from the dashboard immediately. Pro-plan keys created before 2026-05-28 are revoked automatically.

Endpoints

GET/api/v1/properties

Search properties

Filter and paginate the property index. Mirrors every filter on the in-app /search page. Returns up to 5,000 rows per page. Pass format=geojson for a FeatureCollection suitable for map rendering.

Parameters

msa_id
5-digit CBSA code.
state_code
2-letter US state.
bbox
`south,west,north,east`.
property_types
Comma-separated. multifamily, office, retail, …
distress
Comma-separated. AND-combined.
maturity_window
3m / 6m / 12m / 24m / 36m.
dscr_min / dscr_max / occupancy_min / occupancy_max / ltv_min / ltv_max
Numeric ranges.
balance_min / balance_max
Loan balance USD.
sort
balance_desc (default), balance_asc, maturity_asc, maturity_desc, name_asc.
limit / offset
Default limit 1000, max 5000.
format
json (default) or geojson.

Example

cURL
curl 'https://www.maturr.io/api/v1/properties?msa_id=33100&property_types=multifamily&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Node
const res = await fetch(
  'https://www.maturr.io/api/v1/properties?msa_id=33100&property_types=multifamily&limit=10',
  { headers: { Authorization: `Bearer ${process.env.MATURR_API_KEY}` } },
);
const { data, pagination } = await res.json();
Python
import os, requests

res = requests.get(
    "https://www.maturr.io/api/v1/properties",
    params={"msa_id": "33100", "property_types": "multifamily", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['MATURR_API_KEY']}"},
)
res.raise_for_status()
payload = res.json()

Response (200)

{
  "data": [
    {
      "property_uid": "maturr:prop:8da29e2a60ef7457",
      "property_name": "Vista Commons",
      "city": "Tampa",
      "state_code": "FL",
      "property_type": "multifamily",
      "current_balance": 9000000,
      "dscr": 1.42,
      "occupancy_pct": 96.5,
      "ltv": 68.2,
      "severity": "current"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "count": 4567 }
}
GET/api/v1/properties/{uid}

Single property detail

Returns the property row plus the latest 8 financial statements and every loan linked to the property. UIDs are stable — they don't change as new disclosures arrive.

Parameters

uid*
Maturr UID, form `maturr:prop:<hex>`.

Example

cURL
curl 'https://www.maturr.io/api/v1/properties/maturr:prop:8da29e2a60ef7457' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response (200)

{
  "property": { "property_uid": "…", "property_name": "Vista Commons", … },
  "financials": [ { "statement_period_end": "2025-12-31", "noi": 612000, … }, … ],
  "loans": [ { "loan_id": "…", "current_balance": 9000000, "rate_pct": 3.635, … } ]
}
GET/api/v1/loans

Loan list with maturity filter

Returns loan-level rows, optionally restricted to loans maturing within N months from today. Useful for maturity-wall workflows that need loan-level granularity.

Parameters

maturity_within_months
Integer 1-60.
limit
Max 200, default 50.

Example

cURL
curl 'https://www.maturr.io/api/v1/loans?maturity_within_months=12&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response (200)

{ "data": [ { "loan_id": "…", "current_balance": 9000000, "maturity_date": "2026-12-01", … }, … ] }
GET/api/v1/markets/{msa_id}/stats

Aggregate stats for one MSA

Property/loan counts, total UPB, distress mix, weighted DSCR and occupancy for a single MSA. Mirrors the `public_market_stats_by_msa` view used by the marketing hero.

Parameters

msa_id*
CBSA code.

Example

cURL
curl 'https://www.maturr.io/api/v1/markets/45300/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response (200)

{ "msa_id": "45300", "property_count": 583, "total_upb": 12340000000, … }

Rate limits

Limits are per API key, sliding 60-second window. Every successful response carries:

  • X-RateLimit-Limit — your ceiling
  • X-RateLimit-Remaining — requests left in this window
  • X-RateLimit-Reset — seconds until the window resets

When you exceed the limit you'll get a 429 with the same headers plus Retry-After and a JSON body of the form { error: "rate_limited", retry_after: 12 }. Treat 429 as a backoff signal, not an error.

PlanLimit
ProAPI access not included
Advanced500 requests/min per key
Enterprise1,000 requests/min per key (higher on request)

Errors

Errors return a JSON body of the form { error, message }. error is a stable machine-readable code; message is for logs.

StatusCodeMeaning
401unauthorizedMissing/invalid key, or owner is not on Advanced+.
404not_foundResource by the given identifier does not exist.
429rate_limitedPer-key rate limit exceeded. See `Retry-After`.
500db_errorDatabase error. Safe to retry with backoff.

Versioning

The current version is v1. v1 is stable — additive schema changes (new fields, new endpoints) won't bump the version. Breaking changes — renamed fields, removed endpoints, changed param semantics — will ship as /api/v2/alongside v1, with a deprecation window.

Changelog

2026-05-28 — v1 launch
Five read endpoints. Bearer auth. Per-plan rate limits. OpenAPI 3.1 spec published at /api/v1/openapi.json.