> ## 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. # Create an extraction job > Validates, accepts, and bills the referenced document(s), then starts extraction. Submit either a single `document_id` or a `bundle` of offering memorandum + rent roll + T-12 (billed at the bundle rate). Validation failures for the document (size cap, unreadable file, unresolvable type) reject the request with `422` and **no charge**. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/extractions 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: post: tags: - Extractions summary: Create an extraction job description: | Validates, accepts, and bills the referenced document(s), then starts extraction. Submit either a single `document_id` or a `bundle` of offering memorandum + rent roll + T-12 (billed at the bundle rate). Validation failures for the document (size cap, unreadable file, unresolvable type) reject the request with `422` and **no charge**. operationId: createExtraction parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExtractionCreateRequest' responses: '202': description: Accepted and billed; processing started. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Extraction' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': description: > Usage pool exhausted and overage disabled for this account (by default, service continues in arrears and this error is not returned). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': description: Document rejected during validation (not charged). 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: ExtractionCreateRequest: type: object description: Provide exactly one of `document_id` or `bundle`. oneOf: - required: - document_id - required: - bundle properties: document_id: type: string description: Single document to extract. bundle: type: object description: > Deal bundle (offering memorandum + rent roll + T-12), billed at the bundle rate. Size caps apply per component. required: - offering_memorandum_document_id - rent_roll_document_id - t12_document_id properties: offering_memorandum_document_id: type: string rent_roll_document_id: type: string t12_document_id: type: string Extraction: type: object required: - id - object - status - documents - created_at - sandbox properties: id: type: string example: ext_01J9ZJYA object: type: string const: extraction status: $ref: '#/components/schemas/ExtractionStatus' documents: type: array items: $ref: '#/components/schemas/ExtractionDocument' billed_total_usd: type: string example: '12.00' sandbox: type: boolean created_at: type: string format: date-time completed_at: type: string format: date-time result_url: type: string description: >- Convenience link to `/v1/extractions/{id}/result`; present when completed. 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 ExtractionStatus: type: string enum: - processing - completed - failed ExtractionDocument: type: object required: - document_id - document_type - schema_version - status properties: document_id: type: string document_type: $ref: '#/components/schemas/DocumentType' schema_version: type: string example: rent_roll.v1 status: type: string enum: - processing - completed - failed billed: $ref: '#/components/schemas/BilledLine' error: type: object properties: 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 BilledLine: type: object required: - rate_code - units - amount_usd properties: rate_code: type: string description: Rate-card line the debit was priced against. example: rent_roll units: type: integer description: > Billing units. Documents exceeding their type's size cap bill as multiple units (e.g. a 2,400-row rent roll = 3 units). example: 1 amount_usd: type: string description: Decimal string, e.g. "12.00". example: '12.00' 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' 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. ````