Skip to navigation
API

API Reference

A single REST API for SpreadSpace, covering borrowers, loans, document packages, extractions, and embed sessions.

The SpreadSpace API is organized by resource. Pick a group from the sidebar to see its endpoints, request and response schemas, and copy-paste examples in cURL and every official SDK.

Base URL

Every request goes to one base URL. The API key prefix (not the URL) selects the environment:

https://api.spreadspace.app
  • ss_live_… operates on live workspace data.
  • ss_test_… routes to the isolated developer sandbox (test mode), where uploads return premade sample extractions at no charge.

Authentication

Every request carries a bearer token in the Authorization header:

curl https://api.spreadspace.app/api/borrowers \
  -H "Authorization: Bearer ss_live_..."

Key management, prefixes, and secret handling: Authentication.

Find an extraction

When browsing a mixed document packet, list the borrower’s documents first. The optional loan_id query parameter limits the list to one loan; omit it to browse across the borrower’s loans.

curl "https://api.spreadspace.app/api/documents?borrower_id=111111111111111111111111&loan_id=222222222222222222222222" \
  -H "Authorization: Bearer ss_test_..."

The list answers { data, has_more, next_cursor }, newest first; page on has_more, not on the length of data. Each item in data describes one document. This fictional item identifies the statement and its reporting period:

{
  "document_id": "333333333333333333333333",
  "document_type": "balance_sheet",
  "borrower_id": "111111111111111111111111",
  "loan_id": "222222222222222222222222",
  "status": "extracted",
  "status_reason": null,
  "duplicate_of_document_id": null,
  "period": {
    "type": "point_in_time",
    "start": null,
    "end": "2025-12-31",
    "fiscal_year": 2025,
    "months_covered": null,
    "label_raw": null,
    "source": "print_stamp"
  },
  "currency": "USD",
  "extraction_version": 1,
  "created_at": "2026-01-15T14:30:00Z",
  "updated_at": "2026-01-15T14:30:00Z",
  "deleted_at": null
}

document_type names the document’s kind and the shape of its extracted object. period describes the reporting period, each key null when it is not known. This statement’s columns print no date, so source says the date it was printed on dates it. currency is the document’s ISO 4217 currency code: the code the document prints where it prints one, else USD. created_at records when the document was stored, not the report date, and updated_at when it last changed. status says where the document stands: extracted for one whose data you can read, and duplicate, superseded, undated, paused, unextractable or deleted otherwise.

Read one document with its document_id and the same bearer token. The request uses the same access checks as any other extraction read:

curl "https://api.spreadspace.app/api/documents/333333333333333333333333" \
  -H "Authorization: Bearer ss_test_..."

The document read, GET /api/documents/{document_id}, answers the document’s envelope with its extracted object in report_data, whose first key, document_type, names its shape. report_data is null when the document has no extracted object. If you already know the document kind, filter the list with document_type=balance_sheet; add include=report_data to receive each document’s extracted object in the list.

Versioning

The API surface is versioned with date stamps. Pin one per request with the optional SpreadSpace-Version header; omit it to get the latest. Resolution order, supported versions, and drift detection: Versioning. What changed on the public surface: Changelog.

Idempotency

Mutating calls accept an optional Idempotency-Key header so retries never double-apply an operation: Idempotency.

Request IDs

Every response carries an X-Request-ID header: yours echoed back if you sent one shaped req_ plus 1 to 64 letters or digits, otherwise minted server-side as req_<24 hex chars>. Quote it in support tickets so we can find the request’s logs.

SDKs

Prefer a typed client? The SDKs wrap the core integration surface (borrowers, loans and attributes, jobs, documents, exports, webhooks, embed sessions) with retries, cursor pagination, idempotency, and webhook verification.

Resources

  • OpenAPI spec: https://api.spreadspace.app/v1/openapi.json is the public contract used by these reference pages. Download it:

    curl -sS https://api.spreadspace.app/v1/openapi.json -o spreadspace-openapi.json

  • Postman: a collection with one request per public operation, grouped by resource, and a test mode environment. Import both, select the environment, and paste an ss_test_ key into its apiKey variable.

  • Status: spreadspace.app/status shows the result of a live probe of GET https://api.spreadspace.app/health (which answers 200 with the plain-text body Healthy when the API is up), the version stamp the API resolved for it, and, when available, the trailing successful request rate.

  • SDK packages: @spreadspace/sdk 2.0.0 (npm), spreadspace 2.0.0 (PyPI), SpreadSpace 2.0.0 (NuGet), @spreadspace/react 0.2.0 (npm), @spreadspace/embed 1.0.0 (npm).

  • Agents: https://docs.spreadspace.app/llms.txt indexes every page, and any page is served as Markdown when you append .md to its URL, for example https://docs.spreadspace.app/api/versioning.md. A coding agent can follow Agent-assisted integration.

  • Changelog: what changed on the public surface: Changelog.

  • Support: contact support@spreadspace.app and include the request’s X-Request-ID.