> 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. # List all extracted documents GET https://api.spreadspace.app/api/borrowers/{borrower_id}/extractions Lists every extracted document on the borrower's file, newest first, as metadata only: category, period, fiscal year, line item count, and processing status. The extraction payloads themselves stay behind the retrieve endpoints. Nothing is filtered out here, so failed and duplicate extractions show up alongside successful ones, which makes this the list to reconcile against what you uploaded. Pass `loan_id` to narrow it to one loan. Requires the `extractions:read` scope. Rate limit: 200 requests per minute per key (the `api` lane). Reference: https://docs.spreadspace.app/api/api-reference/extractions/list-extracted-documents ## Authentication - `Authorization` header (bearer token, required) — Bearer token. Use `ss_live_…` for live data or `ss_test_…` for the sandbox (test mode). See [Authentication](https://docs.spreadspace.app/api/authentication). ## Request ### Path parameters - `borrower_id` (string, required) — Id of the borrower whose extractions are read. A borrower the caller cannot access is a 404. ### Query parameters - `loan_id` (string, optional) — Optional. Restricts the read to this loan's documents; omit to read across all of the borrower's loans. A loan the caller cannot access is a 404. An embed session is always held to its bound loan. ### Headers - `SpreadSpace-Version` (string, optional) — Pin the API version, e.g. `2026-10-07`. Omit to get the latest. See [Versioning](https://docs.spreadspace.app/api/versioning). ## Response ### 200 OK - `borrower_id` (string, required) - `documents` (list of ExtractedDocumentSummary, required) ## Errors ### 400 Bad Request Error Bad request: validation failed, the cursor is malformed, or the API version is unknown. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 401 Unauthorized Error Unauthorized: the bearer token or API key is missing or invalid. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 402 Payment Required Error Payment required: the standard error envelope with `type` `subscription_required` when the workspace has no active or trialing subscription, or `billing_required` where a plan entitlement applies. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 403 Forbidden Error Forbidden: authentication succeeded but the caller is not permitted to perform this action, for example an API key missing the required scope, an embed session reaching a loan it was not minted for, or a feature outside the workspace's plan. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 404 Not Found Error Not found: the resource does not exist or is not visible to the calling tenant. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 429 Too Many Requests Error Too many requests: the rate limit was hit, or an idempotency-key replay is still in progress. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 500 Internal Server Error Internal server error: an unexpected failure. Quote the `request_id` in support tickets. A mutation sent with an `Idempotency-Key` replays this fault under that key rather than re-running; confirm the resource state before resending with a new key. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ## Types ### ExtractedDocumentSummary - `extracted_document_id` (string, required) — The extracted document's id. - `job_id` (string, required) — The document package (job) the document was uploaded in. - `loan_id` (string, required) — The loan the document belongs to. - `document_category` (string, required) — What the document was classified as, for example `bank_statement_business` or `1120s`. Reads `unextractable` for a document that could not be extracted. - `line_item_count` (integer, required) — How many line items the document's extraction stored. 0 for a document that could not be extracted. - `created_at` (datetime, required) — When the extracted document was recorded. The list is ordered on it, newest first. - `company_attachment` (DocumentCompanyAttachment, required, nullable) — Which of the borrower's companies a financial document belongs to, as resolved for this read. A company identified later can change the answer on a subsequent read. - `links` (ExtractionDataLinks, required, nullable) — Links for reading an extracted document. - `original_filename` (string, optional, nullable) — The stored source-file or document label, which may include a section suffix. Null when none was recorded. - `period_start` (string, optional, nullable) — Start of the period the document covers, as `YYYY-MM-DD`. Null when it has none. - `period_end` (string, optional, nullable) — End of the period the document covers, as `YYYY-MM-DD`. Null when it has none. - `fiscal_year` (integer, optional, nullable) — The fiscal year the document covers. Null when it has none. - `extraction_status` (string, optional, nullable) — The extraction outcome: null, `success` or `completed` when the document was extracted, otherwise a status such as `duplicate`, `superseded`, `undated`, `unextractable`, `credits_paused` or `budget_paused`. - `error_message` (string, optional, nullable) — A human-readable message explaining the status, for example why an upload is a `duplicate` or why a document is `undated`. Null when there is none, and on every document that could not be extracted. - `duplicate_of_extracted_document_id` (string, optional, nullable) — Set when this document duplicates, or was superseded by, another document on the same loan, and names the document that was kept. The document stays listed but is left out of spreads and other totals. Null otherwise. - `dedup_resolution` (string, optional, nullable) — How the document was resolved against the kept one, for example `exact_duplicate` or `subset_superseded`. Null when `duplicate_of_extracted_document_id` is null. - `extraction_source` (string, optional, nullable) — Set when the document came from a Plaid or Finicity response rather than a document file, and names that response kind. Null otherwise. - `pfs_applicant_name` (string, optional, nullable) — The applicant's name on a personal financial statement. Null on every other document, and when no name could be read. - `pfs_kind` (string, optional, nullable) — Which form a personal financial statement is: `sba_413` or `freeform`. Null on every other document, and when it could not be read. - `supporting_category` (string, optional, nullable) — What a supporting table itemizes, for example `debt` or `lease`. Null on every other document, and when it could not be read. - `supporting_supports` (string, optional, nullable) — The balance sheet side, or the statement, a supporting table supports, for example `asset`, `liability` or `income_statement`. Null on every other document, and when it could not be read. - `supporting_shape` (string, optional, nullable) — The table's layout, for example `debt_composition` or `maturity_schedule`. Null on every other document, and when it could not be read. - `supporting_subject` (string, optional, nullable) — The subject a supporting table is about, read off its caption and rows, for example `regulatory_capital` or `net_interest_income`. Null on every other document, and when none was read. - `assurance_level` (string, optional, nullable) — The CPA engagement a financial statement was prepared under: `audited`, `reviewed` or `compiled`. Null when the statement states none, and on every other document. - `entity_ein_last4` (string, optional, nullable) — The last four digits of the filer's tax id (an EIN, or the SSN on a person form such as a W-2), which tells apart two filers with the same name. Null when there is none. - `extraction_version` (integer, optional, nullable) — The revision of the stored extraction, 1 as ingested and incremented on every later rewrite: the same `extraction_version` the document webhooks carry. Null on a document that could not be extracted. - `company_attachments` (list of DocumentCompanyAttachment, optional, nullable) — Every company the document belongs to, primary first; a shared operating account or a consolidated statement can list several. Absent wherever `company_attachment` is null. - `entity_unlinked` (boolean, optional, nullable) — True when the document was unlinked from every entity by hand: it belongs to none and is not resolved automatically until it is linked again or the unlink is cleared. Absent otherwise. - `unextractable_reason` (string, optional, nullable) — A sentence you can show for a document that could not be extracted, for example a bank statement that did not include all of its pages. Absent otherwise. - `display_name` (string, optional, nullable) — A readable document name, including its reporting period when known. - `period_label` (string, optional, nullable) — The reporting date or period printed on the document, or null when unknown. This is not the upload date. - `source_pages` (list of integer, optional, nullable) — Sorted, unique, one-based page numbers in the original uploaded PDF: cited pages when available, otherwise the pages of the source document section. Null when the original pages cannot be determined. ### ApiErrorBody Inner body of the canonical API error envelope. - `type` (string, required) — Stable error type identifier. Pattern-match on this value, not the human-readable message. - `message` (string, required) — Human-readable error message. Subject to wording changes; do not parse. - `request_id` (string, optional, nullable) — Per-request correlation ID (matches `X-Request-ID` response header). Quote in support tickets. - `details` (map from string to string, optional, nullable) — Structured detail. Some error types populate documented keys in every environment: a version conflict (409) carries `current_version`, the version the resource is actually at, so the client can reload and re-apply. Free-form diagnostic detail beyond those keys appears in development environments only. An `insufficient_credits` 402 carries `balance_usd`, `reserved_usd`, `in_flight_docs`, `incoming_docs` and `per_doc_reservation_usd` as decimal strings. ### DocumentCompanyAttachment Which of the borrower's companies a financial document belongs to, as resolved for this read. A company identified later can change the answer on a subsequent read. - `entity_name` (string, required) — The company's name as it files. - `entity_ein_last4` (string, optional, nullable) — The last four digits of the company's EIN, or null. - `printed_name` (string, optional, nullable) — The name printed on the document itself, or null when it named nobody. - `cross_kind` (boolean, optional, nullable) — True when a return or personal financial statement was filed by hand under an entity of the other kind. Such a document is grouped under that entity, while the spreads keep reading it as its printed filer. Absent otherwise. - `entity_kind` (string, optional, nullable) — The resolved target kind: 'company' or 'person'. ### ExtractionDataLinks Links for reading an extracted document. - `data` (string, required, nullable) — An API-relative GET path for this document's data. Requires authorization; null when no extracted data is available. ## Examples **Response** ```json { "borrower_id": "9f8e7d6c5b4a3210a1b2c3d4", "documents": [ { "extracted_document_id": "123abc456def7890a1b2c3d4", "job_id": "987a654b3c2d1e0f987a654b", "loan_id": "456def123abc7890456def12", "document_category": "1120s", "line_item_count": 42, "created_at": "2024-01-15T09:30:00.125293+00:00", "company_attachment": { "entity_name": "Acme Corporation", "entity_ein_last4": "4210", "printed_name": "Acme Corporation" }, "links": { "data": "/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions/123abc456def7890a1b2c3d4/tax-return" }, "original_filename": "acme_2023_form_1120s.pdf", "period_start": "2023-01-01", "period_end": "2023-12-31", "fiscal_year": 2023, "extraction_status": "completed", "error_message": null, "duplicate_of_extracted_document_id": null, "dedup_resolution": null, "extraction_source": null, "pfs_applicant_name": null, "pfs_kind": null, "assurance_level": null, "entity_ein_last4": "4210", "extraction_version": 1, "display_name": "Tax document (2023-01-01 to 2023-12-31)", "period_label": "2023-01-01 to 2023-12-31", "source_pages": null }, { "extracted_document_id": "456def789abc0123a1b2c3d4", "job_id": "1122334455667788aabbccdd", "loan_id": "456def123abc7890456def12", "document_category": "balance_sheet", "line_item_count": 18, "created_at": "2024-01-15T09:31:00.791760+00:00", "company_attachment": null, "links": { "data": "/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions/456def789abc0123a1b2c3d4/balance-sheet-statement" }, "original_filename": "acme_balance_sheet_dec_2024.pdf", "period_start": null, "period_end": "2024-12-31", "fiscal_year": 2024, "extraction_status": "completed", "error_message": null, "duplicate_of_extracted_document_id": null, "dedup_resolution": null, "extraction_source": null, "pfs_applicant_name": null, "pfs_kind": null, "assurance_level": null, "entity_ein_last4": null, "extraction_version": 1, "display_name": "Balance sheet (2024-12-31)", "period_label": "2024-12-31", "source_pages": null } ] } ``` **SDK Code** ```python import requests url = "https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.spreadspace.app/api/borrowers/9f8e7d6c5b4a3210a1b2c3d4/extractions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```