Query extractions in bulk

curl -X POST https://api.spreadspace.app/api/borrowers/borrowerId/extractions/query-bulk \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "document_ids": [
    "9f8b7c6a5d4e3f2a1b0c9d8e"
  ]
}'

{
  "borrower_id": "9f8e7d6c5b4a3210a1b2c3d4",
  "documents": [
    {
      "document_id": "9a7c6b5d4e3f210987654321",
      "items": [
        {
          "section": "Income",
          "group_name": null,
          "item_name": "Gross receipts or sales",
          "standard_category": "revenue",
          "amount": 2450000,
          "period": "2023",
          "fiscal_year": 2023,
          "aging_bucket": null
        },
        {
          "section": "Expenses",
          "group_name": "Operating expenses",
          "item_name": "Rent",
          "standard_category": "rent_expense",
          "amount": 96000,
          "period": "2023",
          "fiscal_year": 2023,
          "aging_bucket": null
        }
      ],
      "total": 2546000,
      "not_found": false
    },
    {
      "document_id": "1b2c3d4e5f67890123456789",
      "items": [],
      "total": 0,
      "not_found": true
    }
  ],
  "total_documents": 2,
  "total_line_items": 2,
  "total_amount": 2546000
}

Runs the line item query across up to 200 documents at once, one call against your rate limit instead of a per-document fan-out. Send document_ids plus the same optional category, section, year, search, and loan_id filters as the single query. Results come back grouped per document, in the order you sent the ids, capped at 500 line items per document. An id that doesn’t resolve comes back with not_found: true instead of failing the request, and if the combined result would pass 100,000 line items, the response is truncated and carries an X-Result-Truncated: true header.

Runs the line item query across up to 200 documents at once, one call against your rate limit instead of a per-document fan-out. Send `document_ids` plus the same optional `category`, `section`, `year`, `search`, and `loan_id` filters as the single query. Results come back grouped per document, in the order you sent the ids, capped at 500 line items per document. An id that doesn't resolve comes back with `not_found: true` instead of failing the request, and if the combined result would pass 100,000 line items, the response is truncated and carries an `X-Result-Truncated: true` header.

Authentication

AuthorizationBearer

Bearer token. Use ss_live_… for live data or ss_test_… for the sandbox (test mode). See Authentication.

Bearer token. Use `ss_live_…` for live data or `ss_test_…` for the sandbox (test mode). See [Authentication](https://docs.spreadspace.app/api/authentication).

Path parameters

borrowerIdstringRequired

The borrower's id.

Headers

Request

This endpoint expects an object.

document_idslist of stringsRequired

loan_idstring or nullOptional

categorystring or nullOptional

sectionstring or nullOptional

yearinteger or nullOptional

searchstring or nullOptional

Response headers

X-Request-IDstringOptional

Correlation ID for this request. Quote it in support tickets.

Idempotency-Replayboolean

Set to true when the response is replayed from the idempotency cache for a request that re-presented an Idempotency-Key it had already used. Absent on the original (winner) response. Replays are byte-for-byte identical to the original response body.

SpreadSpace-VersionstringOptional

The API surface version the server resolved for this request. Always present, regardless of whether the client supplied the request-side SpreadSpace-Version header. Default: 2026-07-19.

RateLimit-Limitinteger

Request budget of the endpoint’s rate-limit policy per 60-second sliding window. See Rate limits.

Request budget of the endpoint's rate-limit policy per 60-second sliding window. See [Rate limits](https://docs.spreadspace.app/api/rate-limits).

RateLimit-Remaininginteger

Requests left in the current window. Suppressed on 429 responses produced outside the rate limiter (for example a usage throttle), where a remaining budget would be misleading.

RateLimit-Resetinteger

Seconds until a guaranteed-fresh window.

RateLimit-PolicystringOptional

The active policy in limit;w=window-seconds form.

Response

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error