---
title: "Submit an extraction"
method: POST
path: "/extractions"
tags: ["Extractions"]
---

# Submit an extraction

`POST /extractions`

## Request

- Base URL: `https://api.invoicedataextraction.com/v1`
- URL: `https://api.invoicedataextraction.com/v1/extractions`
- Auth: HTTP bearer

Submits an extraction over completed files of one upload session. The `prompt` says
what to extract, as a sentence or as an object naming exact output fields.
`options.json_typed_values: true` is recommended for any integration that reads the
rows; `options.ask_questions: true` lets the extraction stop and ask when the documents
leave something unsettled.

Idempotent: the same request sent again with the same `submission_id` returns the
existing extraction. Any other request under a `submission_id` that already belongs to
an extraction is refused with `SUBMISSION_ID_ALREADY_USED`; use a new `submission_id`
for each extraction.
The task appears in the web dashboard alongside extractions submitted there.

Rate limit: 30 requests per minute per API key.

## Request body

- SubmitExtractionRequest
  - `submission_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
  - `upload_session_id` string, required: An identifier you choose: 1 to 200 characters from letters, digits, dots, underscores, colons and hyphens. Used for `upload_session_id`, `file_id` and `submission_id`.
  - `file_ids` ClientId[], required: Files completed in this session.
  - `task_name` string, required: Your own label for the extraction.
  - `prompt` union, required: What to extract: a sentence of up to 5,000 characters, or an object naming the exact output fields.
    - string
    - PromptObject
      - `fields` PromptField[], required
        - `name` string, required: The output column name, exactly as it will appear. Names are unique ignoring case, spaces and underscores, and may not be `Source File` or `Review Needed`.
        - `prompt` union: Instructions for this field, 3 to 600 characters. May be omitted or empty.
          - ''
          - string
      - `general_prompt` string: Instructions that apply to the whole task and every field.
  - `output_structure` 'automatic' | 'per_invoice' | 'per_line_item', required: `per_invoice`: one row per invoice. `per_line_item`: one row per line item, with the invoice-level fields repeated. `automatic`: chosen from your prompt and documents; responses report the resolved value once processing completes.
  - `options` ExtractionOptions: Every field is optional. The three output preferences default to the account's settings on the web app's Preferences page; a value sent here applies to this extraction only.
    - `exclude_columns` string[]: System columns to leave out of the output files. Completed responses still carry `review_needed` when the column is excluded.
    - `output_language` 'automatic' | 'en' | 'ar' | 'zh-Hant' | 'zh-Hans' | 'nl' | 'fr' | 'de' | 'el' | 'he' | 'it' | 'ja' | 'pl' | 'pt' | 'es' | 'th'
    - `review_needed_fill_color` 'none' | 'yellow' | 'orange' | 'red'
    - `affected_field_fill_color` 'none' | 'yellow' | 'orange' | 'red'
    - `send_completion_email` boolean: Email the account when this extraction finishes, whether it completes, fails or is cancelled.
    - `json_typed_values` boolean: Native JSON types in the JSON output and the results endpoint: numbers for amounts, quantities and rates, booleans for yes/no fields, `null` for an empty cell. Recommended for a new integration that reads the rows. Fixed at submission.
    - `ask_questions` boolean: Let the extraction stop and ask when the documents leave something unsettled. The status is then `input_required` with the questions; answer with `answerExtractionQuestions`. Off, the extraction never stops to ask.

## Response `202`

The extraction is queued. Wait for it with `getExtraction`.

- SubmitExtractionResponse
  - `success` true, required
  - `extraction_id` string, uuid, required
  - `submission_state` 'received', required

## Other responses

- `400`: `INVALID_INPUT`: the request does not match the contract; `details.issues` lists each problem with its `path`.
- `401`: `UNAUTHENTICATED`, `API_KEY_EXPIRED` or `API_KEY_REVOKED`.
- `409`: `SUBMISSION_ID_ALREADY_USED`: this `submission_id` already belongs to an extraction, and the request is not the one that created it. `details.extraction_id` is that extraction; `details.differing_fields` lists which of `upload_session_id`, `file_ids`, `prompt`, `output_structure` and `options` differ. Use a new `submission_id` for a new extraction; to retry the earlier request, read that extraction with `getExtraction` instead of submitting again.
- `429`: `RATE_LIMITED`: wait `details.retry_after_seconds` (also the `Retry-After` header), then retry.
- `500`: `INTERNAL_ERROR`: retry after a short delay.
- `503`: `SUBMISSIONS_PAUSED`: submissions are paused for a deploy; retry in a few minutes. `details.resumes_at`, when present, is the expected resume time in UTC.

---

[API](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api.md) · [All operations](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invoicedataextraction/apis/invoice-data-extraction-api/revisions/16d920350483?raw)