Retrieve a document's geometry

Retrieves where a document’s values sit on its pages: one bounding box per located value, keyed by address, plus the size of each page a box sits on. An address names a value in the document’s report data, such as lines.3.label for the caption of lines[3] or lines.3.0 for its figure in the first period column, so each box joins to the figure or caption a retrieve endpoint returns; no figure or caption rides this response. Boxes are in PDF points measured from the top-left corner of a page numbered from 1. A document with no located values returns empty lists. Requires a plan that includes source geometry; other plans get a 403 geometry_plan_denied.

Requires the extractions:geometry scope. Rate limit: 200 requests per minute per key (the api lane).

Retrieves where a document's values sit on its pages: one bounding box per located value, keyed by address, plus the size of each page a box sits on. An address names a value in the document's report data, such as `lines.3.label` for the caption of `lines[3]` or `lines.3.0` for its figure in the first period column, so each box joins to the figure or caption a retrieve endpoint returns; no figure or caption rides this response. Boxes are in PDF points measured from the top-left corner of a page numbered from 1. A document with no located values returns empty lists. Requires a plan that includes source geometry; other plans get a 403 `geometry_plan_denied`. Requires the `extractions:geometry` scope. Rate limit: 200 requests per minute per key (the `api` lane).

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.

docIdstringRequired

The document's id.

Response headers

X-Request-IDstringOptional

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

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

document_idstring

The document's id.

document_categorystring

The document's category.

extraction_versioninteger

The revision of the extraction the boxes belong to, the same extraction_version the document list and the document webhooks carry.

unitsstring

Always pt: PDF points, 72 to the inch.

originstring

Always top_left: x0 and x1 are measured from the left edge of the page, top and bottom from its top edge.

pageslist of objects

The size of each page a box sits on, in page order, where the document records it. Empty when no size is recorded.

boxeslist of objects

One box per located value, in ordinal order of address. Empty when the document has no located values.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error