SubmitExtractionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/invoicedataextraction-com/json-schema/invoicedataextraction-com-submit-extraction-request-schema.json",
  "title": "SubmitExtractionRequest",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/invoicedataextraction-com-openapi.json#/components/schemas/SubmitExtractionRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "submission_id",
    "upload_session_id",
    "file_ids",
    "task_name",
    "prompt",
    "output_structure"
  ],
  "properties": {
    "submission_id": {
      "$ref": "#/$defs/ClientId"
    },
    "upload_session_id": {
      "$ref": "#/$defs/ClientId"
    },
    "file_ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 6000,
      "items": {
        "$ref": "#/$defs/ClientId"
      },
      "description": "Files completed in this session."
    },
    "task_name": {
      "type": "string",
      "minLength": 3,
      "maxLength": 40,
      "description": "Your own label for the extraction."
    },
    "prompt": {
      "description": "What to extract: a sentence of up to 5,000 characters, or an object naming the exact output fields.",
      "oneOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 5000
        },
        {
          "$ref": "#/$defs/PromptObject"
        }
      ]
    },
    "output_structure": {
      "$ref": "#/$defs/OutputStructure"
    },
    "options": {
      "$ref": "#/$defs/ExtractionOptions"
    }
  },
  "$defs": {
    "ClientId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,200}$",
      "description": "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`."
    },
    "ExtractionOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "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.",
      "properties": {
        "exclude_columns": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "source_file",
              "review_needed"
            ]
          },
          "default": [],
          "description": "System columns to leave out of the output files. Completed responses still carry `review_needed` when the column is excluded."
        },
        "output_language": {
          "$ref": "#/$defs/OutputLanguage"
        },
        "review_needed_fill_color": {
          "$ref": "#/$defs/FillColor"
        },
        "affected_field_fill_color": {
          "$ref": "#/$defs/FillColor"
        },
        "send_completion_email": {
          "type": "boolean",
          "default": false,
          "description": "Email the account when this extraction finishes, whether it completes, fails or is cancelled."
        },
        "json_typed_values": {
          "type": "boolean",
          "default": false,
          "description": "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": {
          "type": "boolean",
          "default": false,
          "description": "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."
        }
      }
    },
    "FillColor": {
      "type": "string",
      "enum": [
        "none",
        "yellow",
        "orange",
        "red"
      ]
    },
    "OutputLanguage": {
      "type": "string",
      "enum": [
        "automatic",
        "en",
        "ar",
        "zh-Hant",
        "zh-Hans",
        "nl",
        "fr",
        "de",
        "el",
        "he",
        "it",
        "ja",
        "pl",
        "pt",
        "es",
        "th"
      ]
    },
    "OutputStructure": {
      "type": "string",
      "enum": [
        "automatic",
        "per_invoice",
        "per_line_item"
      ],
      "description": "`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."
    },
    "PromptField": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 50,
          "description": "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": {
          "description": "Instructions for this field, 3 to 600 characters. May be omitted or empty.",
          "anyOf": [
            {
              "type": "string",
              "const": ""
            },
            {
              "type": "string",
              "minLength": 3,
              "maxLength": 600
            }
          ]
        }
      }
    },
    "PromptObject": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fields"
      ],
      "properties": {
        "fields": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "items": {
            "$ref": "#/$defs/PromptField"
          }
        },
        "general_prompt": {
          "type": "string",
          "maxLength": 1500,
          "description": "Instructions that apply to the whole task and every field."
        }
      }
    }
  }
}