> This page is for API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.spreadspace.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server. # Export value conventions Public money uses two-decimal strings: loan `requested_amount`, query amounts and totals, EBITDA write-ins, `report_data`, attribute snapshots ([Spreads](/api/spreads)), and [export files](/api/exports). Loan amounts accept `"0.00"` through `"999999999999.99"`. Send `"250000.00"`, with no separators, signs, or extra decimal places; invalid formats return `400 validation_failed`. On update, omission or `null` leaves the amount unchanged. Loan `interest_rate` stays numeric: `5.25` means 5.25%. Inside an export file: **Decimals are strings; integers are numbers.** ## Numbers | Kind | You receive | Rules | | ----------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Money | `"1250000.00"` | String, exactly 2 decimal places, `.` decimal point, no thousands separators, no currency symbols. Base units: never "in thousands", even where the source form prints that way. | | Ratios (`dscr`, `fccr`, `leverage_ratio`) | `"1.4167"` | String, at most 4 decimal places. Round for display yourself. | | Percentages (`*_percent`) | `"5.25"` | String, at most 4 decimal places. `"5.25"` means 5.25%, never 0.0525. Every percentage field name ends in `_percent`. | | Basis points (`*_bps`) | `275` | JSON integer. `275` means 2.75%. Every basis-point field name ends in `_bps`. | | Counts, `fiscal_year`, `months_covered`, `sort_order` | `12` | JSON integers. | Response rounding is round half to even. Export and attribute rates use `*_percent` or `*_bps` to state their scale; an attribute snapshot follows the same table. ## Signs Negative means outflow or contra: `"-8200.55"`; no parentheses-negatives, no separate sign flags. A classification such as `flow_direction` (`INFLOW` or `OUTFLOW` on bank lines) rides beside the signed amount, never inferred from it. ## Null versus zero `null` means the value is absent from the source document. `"0.00"` means the document affirmatively shows zero. These are different facts and both are always emitted: keys are never dropped, in export files and attribute snapshots alike. ## Dates and timestamps * Business dates are ISO 8601 date-only strings: `"2023-12-31"`. No time, no timezone; parse them as dates, never as instants (`new Date("2023-12-31")` in JavaScript is UTC midnight, a day off in US timezones). * Timestamps (`generated_at`, audit fields): API response timestamps are RFC 3339 with a numeric UTC offset and fractional seconds (`2026-08-18T03:15:29.403074+00:00`); inside export files they are `Z`-suffixed at seconds precision (`"2026-07-20T13:30:05Z"`). ## Fiscal periods In an export file, never a bare label like `"FY23"`. Always a struct: ```json { "period_start": "2023-04-01", "period_end": "2023-11-30", "period_type": "ANNUAL", "fiscal_year": 2023, "months_covered": 8 } ``` `period_type` is `ANNUAL`, `INTERIM`, or `TTM`. A short-year return stays `ANNUAL` with `months_covered` under 12; non-calendar fiscal year ends are just what the dates say. An attribute snapshot keys its values by fiscal-year label (`"2024"`) instead, or by as-of date (`"2024-06-30"`) for a point-in-time figure. ## Identifiers EINs, account numbers, and routing numbers are always strings with leading zeros preserved (`"041234567"`); a masked variant is a separate field such as `account_last4`. Record identifiers (`borrower_id`, `loan_id`, `job_id`, document ids) are opaque strings: store and compare them byte-for-byte, never parse meaning from an id or validate its shape. Where an identifier carries a stable prefix (`evt_`, `whsec_`, `ss_live_` / `ss_test_` / `ss_embed_`), the prefix is part of the value. ## Key casing Envelope fields are `snake_case` (`borrower_id`, `extracted_document_id`, `report_data`). Keys inside a document's `report_data` body keep the casing they were extracted with: bank statement bodies, for example, carry camelCase keys such as `accountNumberLast4`. Match keys exactly as the object page shows. ## Enums Enums are closed, versioned sets serialized as string tokens (numeric tokens are rejected). Wherever a value is mapped from an open source set, the enum includes an `OTHER` escape and a sibling `*_raw` string carries the source value verbatim (`statement_type` + `statement_type_raw`). Two have no `OTHER` by design: `period_type` is the fixed set above, and `flow_direction` has two values beside a signed amount, with the source rail in `transaction_type_raw`. ## Provenance In an export file, values may carry an optional `provenance` object pointing back at the source document: `{ "source_doc_id": "...", "page": 3, "field_ref": "line_7_officer_compensation" }`. `page` is 1-based; `field_ref` is the stable field handle, the form-line key for scalar tax lines or a dotted path for columnar schedule values (`schedule_l.line_1_cash.ending`). Map by `field_ref`, never by row position: line sets can grow additively. In an attribute snapshot, provenance is document-level: each period's `documents` entry lists the document ids and extraction versions its figure was read from. ## Currency `currency` is declared once at the root of an export file as an ISO 4217 code (`"USD"`). There are no per-value currency objects, and the attribute snapshot payload carries no `currency` key. ## Versioning `schema_version` at the root of an export file is a semver (`1.0.0`). Within a major version, changes are additive only: new optional fields and new enum values may appear; existing fields never change name, type, scale, or meaning. Build your export-file parser to ignore unknown fields. The attribute snapshot payload's `schema_version` is the tag `attributes.v1`, not a semver. ## Extracted documents `report_data` follows its published family schema, with no root `schema_version`. Dates follow the family: [conventions:start]: # "generated by fern/gen-object-pages.py from fern/public-schemas; do not edit by hand" Money keys are JSON strings with exactly two decimals on every family (`"9200000.00"`, `"-1250.50"`). | Family | Dates | Fields | | ------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Tax Return | As printed, or `YYYY-MM-DD` where the Type column states it | [Tax Return](/api/api-reference/tax-returns/object) | | Form W-2 | No date keys | [Form W-2](/api/api-reference/w2s/object) | | Paystub | `YYYY-MM-DD` | [Paystub](/api/api-reference/paystubs/object) | | Personal Financial Statement | As printed | [Personal Financial Statement](/api/api-reference/personal-financial-statements/object) | | Balance Sheet | As printed, or `YYYY-MM-DD` where the Type column states it | [Balance Sheet](/api/api-reference/balance-sheets/object) | | Profit and Loss Statement | `YYYY-MM-DD` | [Profit and Loss Statement](/api/api-reference/profit-loss-statements/object) | | Cash Flow Statement | As printed, or `YYYY-MM-DD` where the Type column states it | [Cash Flow Statement](/api/api-reference/cash-flow-statements/object) | | Equity Statement | `YYYY-MM-DD` | [Equity Statement](/api/api-reference/equity-statements/object) | | Comprehensive Income Statement | `YYYY-MM-DD` | [Comprehensive Income Statement](/api/api-reference/comprehensive-income-statements/object) | | Investment Income Statement | `YYYY-MM-DD` | [Investment Income Statement](/api/api-reference/investment-income-statements/object) | | Supporting Table | `YYYY-MM-DD` | [Supporting Table](/api/api-reference/supporting-tables/object) | | Debt Schedule | As printed, or `YYYY-MM-DD, YYYY-MM or YYYY` where the Type column states it | [Debt Schedule](/api/api-reference/debt-schedules/object) | | Bank Statement | `YYYY-MM-DD` | [Bank Statement](/api/api-reference/bank-statements/object) | | Accounts Receivable Aging | As printed, or `YYYY-MM-DD` where the Type column states it | [Accounts Receivable Aging](/api/api-reference/ar-agings/object) | | Accounts Payable Aging | As printed, or `YYYY-MM-DD` where the Type column states it | [Accounts Payable Aging](/api/api-reference/ap-agings/object) | | Bank Statement Account | `YYYY-MM-DD` | [Bank Statement Account](/api/api-reference/bank-statement-accounts/object) | [conventions:end]: # "end of the generated region"