Export value conventions

Public money uses two-decimal strings: loan requested_amount, query amounts and totals, EBITDA write-ins, report_data, attribute snapshots (Spreads), and export files.

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

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:

{
  "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:

Money keys are JSON strings with exactly two decimals on every family ("9200000.00", "-1250.50").