> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spreadspace.app/api/api-reference/webhook-events/webhook-extraction-mapped/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server.

# extraction.mapped

POST 

Fires once for every mapping of a profit and loss statement onto the chart of accounts: the statement's first mapping, and each one made again after its extraction, the workspace's chart of accounts, caption rules or export map, or the mapping logic changed, or the statement was corrected in the workspace. The payload carries ids and versions, not figures. Fetch the mapping from `GET /api/borrowers/{borrowerId}/extractions/{docId}/mapping`. Sent to workspaces whose plan includes the Statement mapping feature.

Reference: https://docs.spreadspace.app/api/api-reference/webhook-events/webhook-extraction-mapped

## Request

### Headers

- `SpreadSpace-Signature` (string, required) — Signature over the exact request body: `t=<seconds since the Unix epoch>,v1=<lowercase hex HMAC-SHA256 of "{t}.{body}" keyed with your endpoint's signing secret>`. Verify it before trusting the body, and reject a `t` more than five minutes from your own clock. During a secret rotation both the new and the previous secret verify for 24 hours; each delivery is signed with exactly one.
- `SpreadSpace-Event-Id` (string, required) — The event id, identical to the body's `id`. Stable across retries and replays, and shared by every endpoint one event fans out to. Delivery is at-least-once, so dedupe on it.

### Payload

- `id` (string, required) — Event id: `evt_` plus 24 lowercase hex characters. Also sent as the `SpreadSpace-Event-Id` header. Stable across retries and replays, so dedupe on it.
- `type` (enum, required) — Always this event type on this body.
  - Allowed values: `extraction.mapped`
- `created` (long, required) — Seconds since the Unix epoch at which the event was created server-side. Seconds, not milliseconds. Deliveries are not ordered; reconcile on this.
- `tenant_id` (string, required) — The workspace the event belongs to. Reject a delivery whose tenant does not match the endpoint you registered.
- `livemode` (boolean, required) — `true` for live activity, `false` for test mode (an `ss_test_` key or the sandbox simulator). Branch on it to route test deliveries to a staging handler.
- `data` (ExtractionMappedPayload, required) — The `data` object on an `extraction.mapped` delivery, sent once for every mapping of a profit and loss statement onto the chart of accounts: the statement's first mapping, and each one made again after its extraction, the workspace's chart of accounts, caption rules or export map, or the mapping logic changed, or the statement was corrected in the workspace. A pointer, not a payload: ids, versions, two states, a reason and a time, with no figures, no captions and no names. Read the mapping through `GET /api/borrowers/{borrower_id}/extractions/{document_id}/mapping`, where the caller's own scope and plan apply.

## Types

### ExtractionMappedPayload

The `data` object on an `extraction.mapped` delivery, sent once for every mapping of a profit and loss statement onto the chart of accounts: the statement's first mapping, and each one made again after its extraction, the workspace's chart of accounts, caption rules or export map, or the mapping logic changed, or the statement was corrected in the workspace. A pointer, not a payload: ids, versions, two states, a reason and a time, with no figures, no captions and no names. Read the mapping through `GET /api/borrowers/{borrower_id}/extractions/{document_id}/mapping`, where the caller's own scope and plan apply.

- `document_id` (string, required) — The document that was mapped.
- `borrower_id` (string, required) — The borrower the document belongs to.
- `extraction_version` (integer, required) — The revision of the stored extraction the mapping was made from.
- `mapping_id` (string, required) — The mapping this event announces, the `mapping_id` the mapping read returns.
- `status` (string, required) — `ready` when the statement was mapped, or `unmappable` when it was read and could not be mapped.
- `engine_version` (string, required) — The version of the mapping logic that made the mapping.
- `chart_document_version` (integer, required) — 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_version` (integer, required) — 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.
- `reason` (string, required) — Why the mapping was made: `first` for the document's first mapping, otherwise what changed since its previous one. `extraction` when the extraction was revised, `chart` when the workspace's chart of accounts, caption rules or export map changed, `logic` when the mapping logic changed, the first of those three when more than one changed, and `correction` when none of them changed and the statement was corrected in the workspace: a figure edited, or a printed line placed on another account than the one the chart chose for its caption.
- `mapped_at` (datetime, required) — When the mapping was made, the `created_at` the mapping read returns.
- `loan_id` (string, optional, nullable) — The loan the document belongs to. Null when it belongs to none.
- `mapping_state` (string, optional, nullable) — `mapped` when the statement's lines are filed on the chart of accounts, or `unfooted` when they are returned as printed because they do not walk to the statement's bottom line. Null when `status` is `unmappable`.
- `chart_version` (string, optional, nullable) — The version of the platform chart of accounts the mapping's accounts come from. Null when `status` is `unmappable`.