Processor output types

Legacy extraction outputs follow a standardized format that you’ll encounter when working with evaluation sets, webhooks, and API responses.

Extraction output type (Fields Array)

This section is relevant for the Fields Array config type. If you are using the JSON Schema config type, please see the Extraction output type (JSON Schema) documentation. If you aren’t sure which config type you are using, please see the Migrating to JSON Schema.

For processors using the legacy Fields Array configuration, the extraction output is a flat dictionary where each key is the fieldName (or sometimes the id if names aren’t unique) you defined in the configuration, and the value is an ExtractionFieldResult object containing the extracted data and associated details.

Type definition

Each ExtractionFieldResult object contains the core id, type, and extracted value. It can also include the following optional details:

schema: The schema definition for nested fields (like objects or array items).
insights: Reasoning or explanations from the model (if enabled).
references: Location information, including the page number and specific Bounding Boxes relevant to the legacy Fields Array configuration (see Bounding Boxes Guide).
enum: The available options if the field type is enum.

1 type ExtractionOutput = {
2   [fieldName: string]: ExtractionFieldResult;
3 };
4 
5 type ExtractionFieldResult = {
6   id: string;
7   type:
8     | "string"
9     | "number"
10     | "currency"
11     | "boolean"
12     | "date"
13     | "enum"
14     | "array"
15     | "object"
16     | "signature";
17   value:
18     | string
19     | number
20     | Currency
21     | boolean
22     | Date
23     | ExtractionValueArray
24     | ExtractionValueObject
25     | Signature
26     | null;
27 
28   /* The following fields are included in outputs, but not required for creating an evaluation set item */
29 
30   /* Includes the field schema of nested fields (e.g. array fields, object fields, signature fields etc) */
31   schema: ExtractionFieldSchemaValue[];
32 
33   /* Insights the reasoning and other insights outputs of the model (when reasoning is enabled) */
34   insights: Insight[];
35 
36   /* References for the extracted field, always includes the page number for all fields, and might include bounding boxes and citations when available. */
37   references: ExtractionFieldResultReference[];
38 
39   /* The enum options for enum fields, only set when type=enum */
40   enum: EnumOption[];
41 };
42 
43 type Currency = {
44   amount: number;
45   iso_4217_currency_code: string;
46 };
47 
48 type Signature = {
49   printed_name: string;
50   signature_date: string;
51   is_signed: boolean;
52   title_or_role: string;
53 };
54 
55 type EnumOption = {
56   value: string; // The enum value (e.g. "ANNUAL", "MONTHLY", etc.)
57   description: string; // The description of the enum value
58 };
59 
60 type ExtractionValueArray = Array<ExtractionValueObject>;
61 type ExtractionValueObject = Record<string, any>;

References

1 type ExtractionFieldResultReference = {
2   /* The field id. When nested for arrays, this is the index of the row number */
3   id: string;
4   /* The field name */
5   fieldName: string;
6   /* The page number (starting at 1) that this bounding box is from */
7   page: number;
8   /**
9    * Array of bounding box references for this field.
10    * There can be multiple is the extraction result was drawn from multiple distinct sources on the page.
11    */
12   boundingBoxes: BoundingBox[];
13 };
14 
15 /* See the Bounding boxes guide for information on how to use/interpret this data */
16 type BoundingBox = {
17   /* The left most position of the bounding box */
18   left: number;
19   /* The top most position of the bounding box */
20   top: number;
21   /* The right most position of the bounding box */
22   right: number;
23   /* The bottom most position of the bounding box */
24   bottom: number;
25 };

Examples

Basic Field Types

1 {
2   "invoice_number": {
3     "id": "field_123",
4     "type": "string",
5     "value": "INV-2024-001"
6   },
7   "amount_due": {
8     "id": "field_456",
9     "type": "currency",
10     "value": {
11       "amount": 1250.5,
12       "iso_4217_currency_code": "USD"
13     }
14   }
15 }

Nested Structures with References and Insights

1 {
2   "line_items": {
3     "id": "field_789",
4     "type": "array",
5     "value": [
6       {
7         "item": "Widget A",
8         "quantity": 5,
9         "price": {
10           "amount": 10.0,
11           "iso_4217_currency_code": "USD"
12         }
13       },
14       {
15         "item": "Widget B",
16         "quantity": 2,
17         "price": {
18           "amount": 15.0,
19           "iso_4217_currency_code": "USD"
20         }
21       }
22     ],
23     "schema": [
24       // Schema definition for the items in the array
25       {
26         "id": "item",
27         "name": "Item Name",
28         "type": "string",
29         "description": "..."
30       },
31       {
32         "id": "quantity",
33         "name": "Quantity",
34         "type": "number",
35         "description": "..."
36       },
37       {
38         "id": "price",
39         "name": "Price",
40         "type": "currency",
41         "description": "..."
42       }
43     ]
44   },
45   "signature_block": {
46     "id": "field_101",
47     "type": "signature",
48     "value": {
49       "printed_name": "John Smith",
50       "signature_date": "2024-03-15",
51       "is_signed": true,
52       "title_or_role": "Purchasing Manager"
53     },
54     "schema": [
55       // Schema for the signature object fields
56       {
57         "id": "printed_name",
58         "name": "Printed Name",
59         "type": "string",
60         "description": "..."
61       },
62       {
63         "id": "signature_date",
64         "name": "Signature Date",
65         "type": "date",
66         "description": "..."
67       },
68       {
69         "id": "is_signed",
70         "name": "Is Signed",
71         "type": "boolean",
72         "description": "..."
73       },
74       {
75         "id": "title_or_role",
76         "name": "Title/Role",
77         "type": "string",
78         "description": "..."
79       }
80     ],
81     "insights": [
82       {
83         "type": "reasoning",
84         "content": "Signature block found at the bottom of page 2. 'is_signed' is true based on visual confirmation."
85       }
86     ],
87     "references": [
88       {
89         "id": "signature_block", // Refers to the top-level field ID
90         "fieldName": "Signature Block",
91         "page": 2,
92         "boundingBoxes": [
93           // Box around the whole signature area
94           { "left": 100, "top": 700, "right": 400, "bottom": 780 }
95         ]
96       }
97     ]
98   }
99 }

Shared Types

Certain types are shared across different processor outputs. These provide additional context and information about the processor’s decisions.

Type Definition

1 type Insight = {
2   type: "reasoning" | "issue" | "review_summary";
3   content: string;
4 };

Example

1 {
2   "insights": [
3     {
4       "type": "reasoning",
5       "content": "This was classified as an invoice because it contains standard invoice elements including an invoice number, billing details, and itemized charges."
6     }
7   ]
8 }

Insights can appear in both Extraction and Classification outputs to provide transparency into the model’s decision-making process. They are particularly useful when debugging or validating processor results.