---
title: "Add extraction types to an existing document (user credentials)"
method: POST
path: "/api/v1/documents/{document_id}/extractions/user"
tags: ["Document"]
---

# Add extraction types to an existing document (user credentials)

`POST /api/v1/documents/{document_id}/extractions/user`

## Request

- Base URL: `https://api.gemina.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemina.co/api/v1/documents/{document_id}/extractions/user`
- Auth: OAuth 2 (password, token URL `token`)

## Path parameters

- `document_id` string, uuid, required

## Request body

- AddExtractionsInDTO: Request body for ``POST /documents/{document_id}/extractions``. No file, external id or end-user id: they belong to the document. FileTag is structurally rejected by ``UploadExtractionTypeModel``.
  - `extractionTypes` UploadExtractionTypeEnum[], required: Extraction types to add to the existing document
  - `modelType` 'gemina' | 'google' | 'openai' | 'velox' | 'praetorian' | 'invictus'
  - `thinking` boolean, nullable: Enable extended reasoning; defaults to the account setting
  - `evaluation` boolean, nullable: Enable self-evaluation of the extracted data; defaults to the account setting
  - `correction` boolean, nullable: Enable self-correction of the extracted data; defaults to the account setting
  - `includeCoordinates` boolean, nullable: Return per-field bounding boxes; defaults to the account setting
  - `templateId` string, uuid, nullable: Custom template to extract with; required by (and only valid with) the custom_template type

## Response `200`

Successful Response

- DocumentAddExtractionsOutDTO: The document view (all extractions, old and new) plus what this call created. ``pollCorrelationId`` is the document's ORIGINAL correlation: the existing ``GET /documents/results/{id}`` / ``get_extraction_result`` report the whole document as done only once every row (including the new ones) is terminal.
  - `status` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty', required
  - `meta` DocumentAddExtractionsMetaOutDTO, required: The document-view meta plus the async poll pointer. Extends (never replaces) ``DocumentViewMetaOutDTO`` so the add-on response keeps every meta field a document view carries (``createdAt``, ``contentPurgedAt``, ``processingStatus``, ``documentId``, ...) and only ADDS ``next`` / ``correlationId`` -- the same poll pointer an upload response exposes, so an existing submit-and-wait SDK helper works unchanged.
    - `externalId` string, nullable
    - `documentId` string, uuid, nullable
    - `userId` string, uuid, nullable
    - `endUserId` string, nullable
    - `apiKeyId` string, uuid, nullable
    - `filename` string, nullable
    - `fileSize` integer, nullable
    - `contentType` string, nullable
    - `documentFileType` 'pdf' | 'image' | 'other'
    - `numberOfPages` integer, nullable
    - `normalizedWidth` integer, nullable
    - `normalizedHeight` integer, nullable
    - `normalizedMegapixels` number, nullable
    - `storageLocation` 'israel' | 'europe' | 'united_states' | 'asia'
    - `imageUrl` string, uri, nullable
    - `thumbnailUrl` string, uri, nullable
    - `originalDocumentUrl` string, uri, nullable
    - `processingStatus` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty'
    - `createdAt` string, date-time, required
    - `contentPurgedAt` string, date-time, nullable, required
    - `correlationId` string, uuid, nullable
    - `next` string, uri, nullable
  - `data` DocumentDataOutDTO, required
    - `extractions` ExtractionProcessingResultOutDTO[], nullable
      - `status` 'pending' | 'in_process' | 'failed' | 'success' | 'partial' | 'empty', required
      - `meta` ExtractionMetaOutDTO, required
        - `extractionId` string, uuid, nullable
        - `modelType` 'gemina' | 'google' | 'openai' | 'velox' | 'praetorian' | 'invictus', required
        - `thinking` boolean, required
        - `correction` boolean, required
        - `evaluation` boolean, required
        - `includeCoordinates` boolean, required
        - `processorClass` string, required
        - `extractionType` 'ocr' | 'document_details_hebrew' | 'document_line_items_hebrew' | 'invoice_headers' | 'invoice_line_items' | 'custom_template' | 'filetag', required: Defines the type of operation to perform on the uploaded document
        - `latencySeconds` number, nullable
        - `numberOfFields` integer, nullable
        - `purgeAt` string, date-time, nullable, required
        - `purgedAt` string, date-time, nullable, required
        - `purgeReason` 'user_deleted' | 'retention_expired' | 'admin_action', required
        - `validationFeedback` ValidationSchemaModel
          - `validationSchema` string[], required
          - `validationFields` ValidationFieldModel[]
            - `key` string, required
            - `label` string, required
            - `type` 'string' | 'number' | 'integer' | 'boolean' | 'date', required
            - `enum` string[], nullable
            - `format` string, nullable
            - `description` string, nullable
          - `rowMutableTables` RowMutableTableModel[]
            - `pointer` string, required
            - `keyTemplate` string, required
            - `columns` ValidationColumnModel[]
              - …
        - `validated` boolean
      - `values` object, nullable, required
      - `verifiedValues` object, nullable
      - `verifiedDiff` VerifiedDiffEntryOutDTO[], nullable
        - `field` string, required
        - `status` 'corrected' | 'added' | 'removed', required
        - `pointer` string, nullable
        - `original` union
          - string
          - integer
          - number
          - boolean
          - unknown[]
            - unknown
          - object
        - `verified` union
          - string
          - integer
          - number
          - boolean
          - unknown[]
            - unknown
          - object
      - `errors` object[]
  - `errors` object[]
  - `createdAt` string, date-time, nullable
  - `createdAtTimestamp` number, nullable
  - `newExtractionIds` string[]: Ids of the extractions this call created
  - `pollCorrelationId` string, uuid, required: Correlation id to poll for the document's completion

## Other responses

- `202`: The new extractions are still running. Poll `pollCorrelationId` (also in `Location`).
- `404`: The resource does not exist, or is not visible to the caller. Ownership failures are deliberately indistinguishable from a missing resource.
- `409`: The request conflicts with the resource's current state; `errors[0].error_code` says which rule.
- `410`: The resource's content has been purged and cannot be processed again.
- `422`: Request validation failed (`HTTPValidationError`), or the request was understood but cannot be applied — e.g. the extraction is under legal hold or did not complete successfully (`FoundationDTO`).
- `429`: Rate or quota limit exceeded; `errors[0].error_code` says which. Retryable limits (`FILETAG_RATE_LIMIT_EXCEEDED`, burst limits) send a `Retry-After` header: back off and retry after it. `CREDIT_EXHAUSTED` for an account with no active subscription or trial sends no `Retry-After` and is not resolved by waiting: start the free trial (once per account) or choose a plan in the console.

---

[API](https://skmtc.dev/gemina/apis/gemina-api.md) · [All operations](https://skmtc.dev/gemina/apis/gemina-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemina/apis/gemina-api/revisions/152fd3f6f6ec?raw)