> ## 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. # Extract normalized underwriting model inputs from documents > Reads every supplied document together and returns the populated input fields of the underwriting model for an asset class and investment strategy — a stable, documented field set, whatever shape the source documents took. This differs from `POST /v1/extractions` in kind, not quality. An extraction reports what one document says, in that document's own structure, with cell-level provenance. This reports the model's fields, reconciled across documents. Use extractions for rent rolls and T-12s, where the document *is* the structure; use this when you need a guaranteed field set — offering memoranda especially, whose layout varies per document. Every field carries the `basis` on which it was populated. `document` and `derived` values came from your documents and cite them; `assumed` values are model defaults chosen where the documents were silent, and carry no citation. `validation.coverage` reports the split. Pass `sourced_only` to receive only what the documents supported. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/underwriting-inputs 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 and can be rotated or revoked at any time. ## Products and access Accounts are enabled per product, so not every endpoint below is available to every account: | Product | Endpoints | | --- | --- | | Extraction | `/v1/extractions` | | Underwriting | `/v1/underwritings`, `/v1/underwriting-inputs` | | Usage reporting | `/v1/usage` | `/v1/documents` and `/v1/webhook-endpoints` are available to every account — uploads and webhook delivery underpin both products. Calling an endpoint your account is not enabled for returns `403` with code `product_not_enabled`; contact api@trycactus.com to add a product. A `403` with code `missing_scope` means the account *is* enabled but this particular key was issued without that scope — use a key that carries it. The MCP server advertises only the tools your key can use, so the same rules apply there. ## 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. Registering a sandbox document under a documented example filename (e.g. `example-rent-roll-1.xlsx`) returns the real extracted output of that reference document — see the Sandbox guide for the full list. ## 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: Underwriting inputs description: Normalized underwriting model inputs extracted from documents. - name: Usage description: Usage pool balance and metered activity. - name: Webhook Endpoints description: Manage endpoints that receive signed event notifications. paths: /v1/underwriting-inputs: post: tags: - Underwriting inputs summary: Extract normalized underwriting model inputs from documents description: | Reads every supplied document together and returns the populated input fields of the underwriting model for an asset class and investment strategy — a stable, documented field set, whatever shape the source documents took. This differs from `POST /v1/extractions` in kind, not quality. An extraction reports what one document says, in that document's own structure, with cell-level provenance. This reports the model's fields, reconciled across documents. Use extractions for rent rolls and T-12s, where the document *is* the structure; use this when you need a guaranteed field set — offering memoranda especially, whose layout varies per document. Every field carries the `basis` on which it was populated. `document` and `derived` values came from your documents and cite them; `assumed` values are model defaults chosen where the documents were silent, and carry no citation. `validation.coverage` reports the split. Pass `sourced_only` to receive only what the documents supported. operationId: createUnderwritingInputs parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnderwritingInputsCreateRequest' responses: '202': description: Job accepted. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/UnderwritingInputs' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': description: >- Rejected documents, or an asset class / strategy with no underwriting model behind it. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: Unique key making the request safely retryable. schemas: UnderwritingInputsCreateRequest: type: object required: - document_ids - asset_class properties: document_ids: type: array minItems: 1 maxItems: 10 items: type: string description: | Documents to read together. They are reconciled as one property, so send the whole package (OM, rent roll, T-12) rather than one job per file — a field stated in one document is available to every section. asset_class: $ref: '#/components/schemas/AssetClass' description: | Selects the underwriting model. Only asset classes with a model behind them are accepted; the rest return `422` (`unsupported_asset_class`). investment_strategy: type: string example: mf-value-add description: >- Strategy within the asset class. Defaults to that class's value-add strategy. sourced_only: type: boolean default: false description: | Return only fields the documents supported (`basis` of `document` or `derived`), omitting model defaults. `validation.coverage` still counts the full run, so you can see how much was withheld. end_user_ref: type: string minLength: 1 maxLength: 255 description: >- Your own identifier for the end user this job is for. Isolates the job's working data from other end users'. UnderwritingInputs: type: object required: - id - object - status - created_at - sandbox properties: id: type: string example: uwi_01J9ZK4P object: type: string const: underwriting_inputs status: $ref: '#/components/schemas/UnderwritingInputsStatus' progress: type: object description: Present while the job is active. properties: phase: type: string enum: - ingesting - matching detail: type: string document_ids: type: array items: type: string asset_class: $ref: '#/components/schemas/AssetClass' investment_strategy: type: string schema_version: type: string const: underwriting_inputs.v1 billed: type: object properties: rate_code: type: string units: type: integer amount_usd: type: string billed_total_usd: type: string sandbox: type: boolean created_at: type: string format: date-time completed_at: type: string format: date-time elapsed_seconds: type: integer description: Whole seconds since `created_at`. Present while the job is active. poll_after_seconds: type: integer description: >- Recommended seconds to wait before polling again. Mirrors the `Retry-After` header. result_url: type: string description: Present when completed. error: type: object properties: code: type: string message: type: string Problem: type: object description: RFC 9457 problem details. required: - title - status - code - request_id properties: type: type: string format: uri description: > Link to this code's entry on the errors page. An anchor, not a path — every code lives on the one page. 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 AssetClass: type: string enum: - multifamily - self-storage - industrial-outdoor-storage - commercial - industrial - office - retail - hotel UnderwritingInputsStatus: type: string enum: - processing - completed - failed headers: RequestId: description: Unique request identifier; quote in support requests. schema: type: string responses: BadRequest: description: Malformed request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: Missing, invalid, or revoked API key. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: > The key authenticated, but this product is not available to it. `product_not_enabled` — your account has not been enabled for this product; contact api@trycactus.com. `missing_scope` — your account has the product but this particular key was issued without it; use a key that carries the scope. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: product_not_enabled: summary: Account not enabled for the product value: type: https://docs.trycactus.com/errors#product_not_enabled title: Product not enabled for this account status: 403 detail: >- Your account is not enabled for underwriting. Contact api@trycactus.com to enable it. code: product_not_enabled request_id: req_01J9Z6X2QK8N4M missing_scope: summary: Key narrower than the account value: type: https://docs.trycactus.com/errors#missing_scope title: API key lacks the required scope status: 403 detail: >- This API key does not have the 'underwriting' scope. Use a key with underwriting access. code: missing_scope request_id: req_01J9Z6X2QK8N4M RateLimited: description: Rate limit exceeded. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. 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. ````