Skip to navigation
APIStatement Mappings

Retrieve a statement mapping

Retrieves one profit and loss statement mapped onto the workspace’s chart of accounts: each printed line on its account, every section and account with its figure per period, the headline measures, and the source of each figure in the document. status is ready or unmappable, and a ready mapping’s mapping_state is mapped or unfooted. Answers 404 with a Retry-After header while the statement’s first mapping is prepared; a document that is not a profit and loss statement answers 404 with no Retry-After. Carries stale: true while a newer mapping is prepared. Requires a plan that includes statement mapping; other plans get a 403.

Requires the extractions:read 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.

Path parameters

borrowerIdstringRequired
The borrower's id.
docIdstringRequired
The document's id.

Headers

SpreadSpace-VersionstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

Pin the API version, e.g. 2026-07-19. Omit to get the latest. See Versioning.

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.

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

OK
mapping_idstringformat: "uuid"
The mapping's id. A statement gets a new mapping, under a new id, when its extraction, the workspace's chart of accounts, caption rules or export map, or the mapping version changes.
document_idstring
The id of the document the mapping is of.
statusstring

ready or unmappable. A ready mapping carries a payload, whose mapping_state says how far the statement could be mapped. unmappable means the statement could not be read as a profit and loss statement at all; it carries no payload.

extraction_versioninteger

The revision of the document's extraction the mapping was made from, the same extraction_version the document list and the document webhooks carry.

engine_versionstring
The version of the mapping logic that made this mapping.
chart_document_versioninteger

The version of the workspace's chart of accounts the mapping was made under, the version that GET /api/chart-of-accounts returns. 0 when the workspace has saved no chart.

chart_rules_versioninteger

The version of the workspace's caption rules the mapping was made under, the rules_version that GET /api/chart-of-accounts returns. 0 when none was written.

created_atdatetime
When the mapping was made.
staleboolean

True when the workspace's chart of accounts, caption rules or export map, or the mapping version, changed after this mapping was made. A stale mapping is still returned while a new one is prepared; read again to receive it.

payloadobject or null

A statement as mapped. Every values and sources array, every measure and foot run in the order of periods: position i of each belongs to period i. Every figure is a decimal string with exactly two decimal places.

error_codestring or nullOptional

unmappable on an unmappable mapping, otherwise null.

chart_versionstring or nullOptional
The version of the platform chart of accounts the mapping's accounts come from. Null on an unmappable mapping.

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