Flow Results API

Table of Contents

The Flow Result API helps you to view flow outputs. The API renders the view in Flow Review for human reviewers to fix validation errors and review results. This API also handles exporting data into various outputs to be reused within Instabase or sent downstream.

All API requests must include your valid access token to authenticate the request.

See Instabase API authorization and response conventions for authorization and error convention details.

import json, requests

api_root = 'https://www.instabase.com/api/v1/flow_binary/results'

Access Flow Results

Method	Syntax
POST	`URL_BASE/api/v1/flow_binary/results`

Description

Access a flow’s results by sending a POST to URL_BASE/api/v1/flow_binary/results with the request body encoded as JSON.

Request parameters

Parameters are required unless marked as optional.

Parameter	Type	Description	Values
`ibresults_path`	string	The path to a batch.ibflowresults file
`options`	Dict	Optional. JSON dictionary with additional options configured when loading the results.	`include_page_layouts`, `include_validations_standardization`, `include_checkpoint_results`, `refined_phrases_features`
`options/include_page_layouts`	boolean	Optional. Whether to include page_layout information about the original input document.	Defaults to `false`.
`options/include_validations_standardization`	boolean	Optional. Whether to enable the standardization of validation information, in order to enable compatibility with the Flow Review UI. For validations to be visible in Flow Review, this flag must be set to `true`.	Defaults to `false`.
`options/include_checkpoint_results`	boolean	Optional. Whether to include validation information in the response.	Defaults to `false`.
`options/refined_phrases_features`	Dict	Optional. JSON dictionary with additional information on what information to send for a record’s refined phrases.	`provenance_info`, `internal_keys`
`options/refined_phrases_features/provenance_info`	boolean	Optional. Include extracted word position information.
`options/refined_phrases_features/internal_keys`	boolean	Optional. Include intermediate phrases with field names that start with `_`
`file_offset`	integer	Optional (defaults to 0). Initial file index to start returning results from. Use this when dealing with large results that are paginated and exceed the default limit that is returned by the API.	Integer specifying a file index. Defaults to 0.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Type	Description	Value
`records`	Array	Array of all the results by records
`record/output_file_path`	string	The output ibdoc the record was retrieved from
`record/results`	Array	The set of extracted phrases by field names
`record/results/key`	string	field key. An internal field will have __ (double underscore) as a prefix
`record/results/value`	string	field value. If the field results has an error value is “ERROR”
`record/results/field_type`	string	field type. Extracted type of the field. Must be one of the following: ANY, TEXT, INT, FLOAT, DICT, LIST, BOOL, TABLE, IMG, EXTRACTED_TABLE, EXTRACTED_TABLE_LIST, SELECT
`record/results/provenance`	Dict	Provenance metadata on extracted value location
`record/results/model_confidence`	float	Average model confidence for the extracted value
`record/results/ocr_confidence`	float	Average OCR confidence for the extracted value
`record/results/information_regions`	List	List of bounding boxes in the pixel space of what anchor information was used to extract the field
`record/results/information_text_regions`	List	List of bounding boxes in the OCR text space of what anchor information was used to extract the field
`record/results/extracted_regions`	List	List of bounding boxes in the pixel space of where the extracted value is on the document
`record/results/extracted_text_regions`	List	List of bounding boxes in the OCR text space of where the extracted value is on the document
`record/results/error_msg`	string	Error message - only exists when value is “ERROR”.
`record/record_index`	integer	Record index in output path.
`record/file_name`	string	Name of the original document.
`record/is_manually_reviewed`	string	If the record is manually marked as reviewed
`record/checkpoint_results`	Dict	The full path to the root output folder.	A string showing the output folder path.
`record/checkpoint_results/flow_path_in_binary`	string	Path to the binary
`record/checkpoint_results/record_index`	integer	Record index of the checkpoint result
`record/checkpoint_results/results`	Dict	The full path to the root output folder.	A string showing the output folder path.
`record/checkpoint_results/results/valid`	boolean	If the validation function passed
`record/checkpoint_results/results/fields`	Array	Array of all fields passed to this validation function
`record/checkpoint_results/results/msg`	string	Validation message
`record/checkpoint_results/results/type`	string	Type of validation done.	’extraction-custom’, ‘classification_custom’, ’typecheck’
`record/layout`	Dict	Page metadata and information
`record/layout/page_layouts`	Array	List of page layouts
`record/layout/page_layouts/page_number`	integer	Page number
`record/layout/page_layouts/processed_image_path`	string	Image path to the generated image
`record/layout/page_layouts/width`	integer	Width of image
`record/layout/page_layouts/height`	integer	Height of image
`record/layout/page_layouts/corrected_rotation`	integer	Rotation angle of document
`record/layout/page_layouts/is_image_page`	boolean	Whether the page is an image
`record/layout/page_layouts/origin_pos`	Array	Original position of the document
`record/layout/page_layouts/origin_pos/x`	integer	x coordinate
`record/layout/page_layouts/origin_pos/y`	integer	y coordinate
`record/layout/document_path`	string	Path to the original document
`record/error`	Dict	Only if a record fails
`record/error/error_message`	string	Error message for the record.
`record/error/error_type`	string	Error type
`record/error/step_name`	string	Flow step where error occured

Examples

Request

Example (Python):

url = url_base + '/api/v1/flow_binary/results'

args = {
  'ibresults_path': "/jaydoe/my_repo/fs/Instabase Drive/flow_proj/out/batch.ibflowresults",
  'options': {
    'refined_phrases_features': ['provenance_info'],
    'include_page_layouts': True,
  },
  'file_offset': 0
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Full Pagination Example (Python):

url = url_base + '/api/v1/flow_binary/results'

args = {
  'ibresults_path': "/jaydoe/my_repo/fs/Instabase Drive/flow_proj/out/batch.ibflowresults",
  'options': {
    'refined_phrases_features': ['provenance_info'],
    'include_page_layouts': True,
  },
  'file_offset': 0
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

# Parse through pages until no more pages left to look through
all_records = resp_data.get('records', [])
while len(resp_data) > 0:
  # Retrieve the last file_index from the last record returned
  next_file_offset = resp_data['records'][-1]['file_index'] + 1
  args["file_offset"] = next_file_offset
  json_data = json.dumps(args)

  r = requests.post(url, data=json_data, headers=headers)
  resp_data = json.loads(r.content)
  resp_records = resp_data.get('records', [])

  all_records.extend(resp_records)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  records: [
    {
      "output_file_path": "path/to/my/output.ibdoc",
      "results": [
        {
          "key": "field1",
          "value": "value1",
          "model_confidence": 0.43
        }...,
        {
          "key": "field2",
          "value": "ERROR",
          "error_msg": "Some error happened (line: 120)",
          "ocr_confidence": 0.98
        },
        {
          "key": "__hidden_field3",
          "value": "value3"
        },
      ],
      "record_index": 0,
      "file_name": "document.pdf",
      "layout": {
        "page_layouts": [
          {
            "page_number": 0,
            "processed_image_path": "path/to/generated/image",
            "width": 600,
            "height": 800,
            "corrected_rotation": 0,
            "is_image_page": false,
            "origin_pos": {
              "x": 0.0,
              "y": 0.0
            }
          }..., //more pages
        ]
      },
      "document_path": "path/to/my/original/document.pdf"
    },
    {
      "error": {
        "error_message": "Columns failed: field1",
        "error_type": "process_files_failed",
        "step_name": "process_files"
      },
      "file_name": "error.pdf"
    }..., // more records
  ]
}