> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycactus.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve the structured output of a completed extraction ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/extractions/{extraction_id}/result openapi: 3.1.0 info: title: Cactus Partner API version: 1.0.0-draft.1 summary: Document extraction and automated underwriting for CRE. description: | # Overview The Cactus Partner API provides two products: - **Extraction** — upload commercial real estate documents (offering memoranda, rent rolls, T-12 / operating statements, and other business documents) and receive structured, validated JSON with per-field confidence. - **Underwriting** — provide a property address, asset class, and notification email (documents optional) to run a full automated underwriting; results are delivered as a hosted financial-analysis report link plus a machine-readable summary. ## Authentication Every request carries an API key: `Authorization: Bearer ck_live_...` (or `ck_sandbox_...`). Keys are issued by Cactus at kickoff, are scoped per product, and can be rotated or revoked at any time. ## Sandbox `ck_sandbox_` keys hit the same endpoints but never debit your usage pool: uploads are accepted, and jobs return deterministic fixture output within seconds. Use sandbox keys for integration development and CI. ## Asynchronous jobs Extractions and underwritings are asynchronous. Create the job (`202 Accepted`), then either poll the job resource or register a webhook endpoint to receive signed events (recommended). Typical extraction turnaround is minutes. ## Billing semantics A document is **accepted** when it passes validation (size caps, page/row counts, type resolution). Acceptance debits your usage pool at the fixed rate-card price for the document type — before processing, so pricing is deterministic. Rejected documents are never charged. Documents exceeding their type's size cap bill as multiple units of the same type; the accept response discloses `billed.units`. Files over 500 pages or 100 MB are rejected outright. ## Idempotency All `POST` endpoints accept an `Idempotency-Key` header (any unique string, e.g. a UUID). Retrying a request with the same key returns the original response instead of creating a duplicate. ## Errors Errors follow RFC 9457 (`application/problem+json`) and always include a stable machine-readable `code` and the `request_id` to quote in support requests. ## Versioning The path major version (`/v1`) changes only for breaking API changes. Extraction output schemas are versioned independently per document type (e.g. `rent_roll.v1`) and declared in every result; breaking output changes ship as a new schema version with advance notice and an overlap window. --- All field-level output schemas — `RentRollData` (`rent_roll.v1`), `T12Data` (`t12.v1`), `OfferingMemorandumData` (`offering_memorandum.v1`), and `GenericDocumentData` (`facts.v1`) — are finalized against the extraction engine's real output. contact: name: Cactus API Support email: api@trycactus.com license: name: Proprietary — Cactus API License Agreement identifier: LicenseRef-Cactus-Partner-Agreement servers: - url: https://api.trycactus.com description: Production (live and sandbox keys) security: - apiKey: [] tags: - name: Documents description: Upload and manage documents via presigned URLs. - name: Extractions description: Structured data extraction jobs and results. - name: Underwritings description: Automated underwriting runs. - name: Usage description: Usage pool balance and metered activity. - name: Webhook Endpoints description: Manage endpoints that receive signed event notifications. paths: /v1/extractions/{extraction_id}/result: parameters: - $ref: '#/components/parameters/ExtractionId' get: tags: - Extractions summary: Retrieve the structured output of a completed extraction operationId: getExtractionResult responses: '200': description: Versioned structured output. content: application/json: schema: $ref: '#/components/schemas/ExtractionResult' '404': $ref: '#/components/responses/NotFound' '409': description: Extraction is not complete yet. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: parameters: ExtractionId: name: extraction_id in: path required: true schema: type: string example: ext_01J9ZJYA schemas: ExtractionResult: type: object required: - extraction_id - results properties: extraction_id: type: string results: type: array items: type: object required: - document_id - document_type - schema_version - data properties: document_id: type: string document_type: $ref: '#/components/schemas/DocumentType' schema_version: type: string example: rent_roll.v1 data: description: > Type-specific structured output; `schema_version` names the shape (`rent_roll.v1`, `t12.v1`, `offering_memorandum.v1`, `facts.v1`). oneOf: - $ref: '#/components/schemas/RentRollData' - $ref: '#/components/schemas/T12Data' - $ref: '#/components/schemas/OfferingMemorandumData' - $ref: '#/components/schemas/GenericDocumentData' validation: type: object properties: checks: type: array items: $ref: '#/components/schemas/ValidationCheck' confidence_status: type: - string - 'null' description: >- State of the engine's asynchronous confidence scoring (`completed` when every confidence is final, `processing` while some are still null). Problem: type: object description: RFC 9457 problem details. required: - title - status - code - request_id properties: type: type: string format: uri example: https://docs.trycactus.com/errors/document_over_size_cap title: type: string example: Document exceeds the size limit status: type: integer example: 422 detail: type: string example: Files over 500 pages or 100 MB are rejected and not charged. code: type: string description: Stable machine-readable error code. example: document_over_size_cap request_id: type: string errors: type: array description: Field-level validation errors, when applicable. items: type: object properties: field: type: string code: type: string message: type: string DocumentType: type: string description: > Declared/resolved document type; determines the rate-card price and the output schema family. enum: - offering_memorandum - rent_roll - t12 - other_standard - other_complex RentRollData: type: object description: > `rent_roll.v1` — the consolidated rent roll: typed column headers, one object of real values per unit row, the detected unit count, and the document-level facts (title, property, export/as-of dates, totals) extracted alongside. required: - as_of_date - headers - units - unit_count - facts properties: as_of_date: type: - object - 'null' description: > The rent roll's stated as-of date; null when the document does not declare one. `confidence` is null until asynchronous confidence scoring completes. required: - value - confidence - source properties: value: {} confidence: type: - number - 'null' minimum: 0 maximum: 1 source: type: object description: >- Where the value was found in the source document (only non-null keys are present). properties: page: type: integer sheet: type: string cell: type: string bbox: type: array items: type: number minItems: 4 maxItems: 4 headers: type: array description: >- Normalized column headers in display order. `key` is the property name carrying that column's value in each `units` entry. items: type: object required: - key - label - type properties: key: type: string description: >- Property name used in `units` rows. Columns outside the standard set are prefixed `custom__`. example: lease_start label: type: string example: Lease start type: type: string description: >- Value type hint (e.g. `text`, `number`, `date`, `currency`, `area`). example: date units: type: array description: > One object per unit row, in document order. Values are keyed by header `key`; empty cells are omitted. When row provenance is known, a `_source` object lists the source page numbers. items: type: object properties: _source: type: object properties: pages: type: array items: type: integer additionalProperties: description: Cell value for the header of the same key. type: - string - number - boolean unit_count: type: integer description: Number of unit rows detected in the consolidated rent roll. facts: type: array description: >- Document-level facts in engine order — the same list `facts.v1` returns for this document. items: type: object required: - path - value - confidence - source properties: path: type: array items: type: string example: - as_of value: {} confidence: type: - number - 'null' minimum: 0 maximum: 1 source: type: object description: >- Where the value was found in the source document (only non-null keys are present). properties: page: type: integer sheet: type: string cell: type: string bbox: type: array items: type: number minItems: 4 maxItems: 4 T12Data: type: object description: > `t12.v1` — the trailing-12-month statement as extracted: report metadata, a best-effort mapping of spreadsheet columns to calendar months, and every line item with its cell values. required: - metadata - months - line_items - facts properties: metadata: type: object description: > Report header metadata keyed by snake_cased label (e.g. `title`, `company`, `period_range`, `accounting_basis`); first stated value wins. additionalProperties: $ref: '#/components/schemas/Field' months: type: - object - 'null' description: > Best-effort mapping of each spreadsheet column letter to the ISO month (`"2024-02"`) it contains, derived from the stated period range; columns after the last month map to `"total"`. Null when the period range is missing or unparseable, or the columns don't line up — see the `t12_month_mapping` validation check (`passed` or `skipped`). additionalProperties: type: string description: ISO month (`YYYY-MM`) or `total`. example: 2024-02 line_items: type: array description: >- One entry per statement line item, grouped by (sheet, row label) in document order. items: type: object required: - sheet - label - cells properties: sheet: type: string example: Sheet1 label: type: string example: Rent Income cells: type: array description: >- Cell values sorted by column letter. Cross- reference `column` with `months` to place a value in time. items: type: object required: - column - value - confidence - cell properties: column: type: string example: B value: {} confidence: type: - number - 'null' minimum: 0 maximum: 1 cell: type: - string - 'null' description: Source spreadsheet cell. example: B16 facts: type: array description: >- Document-level facts (report metadata) in `facts.v1` shape, deduplicated by source cell. items: $ref: '#/components/schemas/Fact' OfferingMemorandumData: type: object description: > `offering_memorandum.v1` — every extracted fact grouped into the document's topic sections, plus a `property` convenience view of the core property attributes. required: - property - sections properties: property: type: object description: > Convenience view of the `Property` facts keyed by snake_cased attribute (e.g. `name`, `address`, `city`, `unit_count`); first stated value wins. The same facts also appear in the `Property` entry of `sections`. additionalProperties: $ref: '#/components/schemas/Field' sections: type: array description: >- All extracted facts grouped by top-level topic in document order — full fidelity, nothing is filtered. items: type: object required: - name - facts properties: name: type: string example: Investment Highlights facts: type: array description: >- Facts in document order; each fact's `path` is relative to the section (and may be empty). items: $ref: '#/components/schemas/Fact' GenericDocumentData: type: object description: > `facts.v1` — the generic shape for other document types: every extracted fact in document order, each with its hierarchical path, value, confidence, and source location. required: - facts properties: facts: type: array items: $ref: '#/components/schemas/Fact' ValidationCheck: type: object required: - code - status properties: code: type: string example: rent_roll_unit_reconciliation status: type: string enum: - passed - warning - failed - skipped message: type: string Field: type: object description: >- A single extracted value with confidence and provenance. `confidence` is null until asynchronous confidence scoring completes. required: - value - confidence - source properties: value: {} confidence: type: - number - 'null' minimum: 0 maximum: 1 source: type: object description: >- Where the value was found in the source document (only non-null keys are present). properties: page: type: integer sheet: type: string cell: type: string bbox: type: array items: type: number minItems: 4 maxItems: 4 Fact: type: object description: >- One extracted fact — hierarchical path, value, confidence (null until asynchronous scoring completes), and source location (only non-null keys are present). required: - path - value - confidence - source properties: path: type: array items: type: string example: - Report - Period Range value: {} confidence: type: - number - 'null' minimum: 0 maximum: 1 source: type: object properties: page: type: integer sheet: type: string cell: type: string bbox: type: array items: type: number minItems: 4 maxItems: 4 responses: NotFound: description: Resource does not exist (or belongs to another partner). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: ck_live_* or ck_sandbox_* description: Partner API key issued by Cactus. ````