You can use this endpoint to retrieve the status, and once completed, the extraction results for any upload.

The extraction results will be fully available for a document once the documentStatus is completed.

Document Status details

The complete list of possible options for documentStatus is:

Document Status ValueDescription
UploadingFileThe file is being uploaded to Butler's document extraction engine.
DetectingTextThe text within the file is being detected by Butler's OCR ensemble.
ExtractingDataThe specific data is being identified and extracted from the text by Butler's document extraction engine.
WaitingForButlerOpsReviewThe file is being reviewed by the Butler Ops team. Only relevant if Butler Ops is enabled for the Queue.
WaitingForUserReviewThe file is waiting for review by someone on your team. Only relevant if the All Documents or Low Confidence Documents setting is specified for the Queue.
CompletedThe file has been successfully processed by Butler and the extraction results are ready.
FailedThe file was not processed successfully. If this continues to occur, reach out to the Butler customer success team.

📘

Polling and Timeouts

In a production integration, while waiting for extraction results to complete, you'll want to poll on this endpoint until the job completes.

You can poll as frequently as you like (we recommend every 30 seconds). If you need to have a polling timeout, we recommend using a timeout of 2 hours

Including extra results

The extraResults query parameter will include extra extraction results from Butler's general Form Field, Table and Line Item extraction. The upload must have specified the extra extraction results parameters in order for the extra extraction results to be available for query.

This parameter is helpful when you need additional information extracted from your documents that are not included in the formFields or tables values.

The extra results you can include in your API response are:

  1. FormFields: all Form Field values that are extracted from the document by Butler's general form field extraction
  2. Tables: all Table values that are extracted from the document by Butler's general table extraction algorithm
  3. LineBlocks: all Line Block values that are extracted from the document by Butler's general Line Block extraction algorithm

Here are example code snippets for how to use these additional parameters in your extraction request:

# Update your extraction results query parameters to include the extraResults parameter
extraction_results_url = f'https://app.butlerlabs.ai/api/queues/{queue_id}/extraction_results'

upload_id = 'UPLOAD_ID' # This is returned from the upload endpoint
params = { 
  'uploadId': upload_id,
  # Make sure to include the extraResults parameter
  'extraResults': [ 'FormFields', 'Tables', 'LineBlocks' ]
}
// Update your extraction results query parameters to include the extraResults parameter
const extractionResultsUrl = `${apiBaseUrl}/queues/${queueId}/extraction_results`;
const params = { 
  uploadId,
  // Make sure to include the extraResults parameter
  extraResults: [ 'FormFields', 'Tables', 'LineBlocks' ]
};
curl -X 'GET' \
  'https://app.butlerlabs.ai/api/queues/<queue_id>/extraction_results?uploadId=<my_upload_id>&extraResults=LineBlocks&extraResults=FormFields&extraResults=Tables' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <api_key>'

And here are some example JSON response values for each of the different extra results:

{
  "extraResults": {
    "formFields": [
      {
        "key": {
          "text": "Subtotal",
          "boundingBox": {
            "left": 0.6669099926948547,
            "top": 0.4188222289085388,
            "width": 0.05863356217741966,
            "height": 0.011895955540239811,
            "page": 0
          }
        },
        "value": {
          "text": "$9.95",
          "boundingBox": {
            "left": 0.8803355693817139,
            "top": 0.4187440872192383,
            "width": 0.04193178564310074,
            "height": 0.012884643860161304,
            "page": 0
          }
        }
      },
      {
        "key": {
          "text": "Amount Due",
          "boundingBox": {
            "left": 0.6650778651237488,
            "top": 0.5415648818016052,
            "width": 0.11919223517179489,
            "height": 0.013962442986667156,
            "page": 0
          }
        },
        "value": {
          "text": "$0.00",
          "boundingBox": {
            "left": 0.8722577095031738,
            "top": 0.541800320148468,
            "width": 0.04961105063557625,
            "height": 0.014779133722186089,
            "page": 0
          }
        }
      }
    ]
  }
}
{
  "extraResults": {
    "tables": [
      {
        "rows": [
          {
            "cells": [
              {
                "text": "Date",
                "boundingBox": {
                  "left": 0.0628201812505722,
                  "top": 0.31638190150260925,
                  "width": 0.15651123225688934,
                  "height": 0.030434997752308846,
                  "page": 0
                }
              },
              {
                "text": "Description",
                "boundingBox": {
                  "left": 0.21933141350746155,
                  "top": 0.31638190150260925,
                  "width": 0.26085206866264343,
                  "height": 0.030434997752308846,
                  "page": 0
                }
              },
              {
                "text": "Qty",
                "boundingBox": {
                  "left": 0.480183482170105,
                  "top": 0.31638190150260925,
                  "width": 0.06886492669582367,
                  "height": 0.030434997752308846,
                  "page": 0
                }
              },
              {
                "text": "Total",
                "boundingBox": {
                  "left": 0.8432894945144653,
                  "top": 0.31638190150260925,
                  "width": 0.09181994199752808,
                  "height": 0.030434997752308846,
                  "page": 0
                }
              }
            ]
          },
          {
            "cells": [
              {
                "text": "Feb 27 – Mar 27, 2020",
                "boundingBox": {
                  "left": 0.0628201812505722,
                  "top": 0.34681689739227295,
                  "width": 0.15651123225688934,
                  "height": 0.051107827574014664,
                  "page": 0
                }
              },
              {
                "text": "Lucidchart Individual Monthly",
                "boundingBox": {
                  "left": 0.21933141350746155,
                  "top": 0.34681689739227295,
                  "width": 0.26085206866264343,
                  "height": 0.051107827574014664,
                  "page": 0
                }
              },
              {
                "text": "1",
                "boundingBox": {
                  "left": 0.480183482170105,
                  "top": 0.34681689739227295,
                  "width": 0.06886492669582367,
                  "height": 0.051107827574014664,
                  "page": 0
                }
              },
              {
                "text": "$9.95",
                "boundingBox": {
                  "left": 0.8432894945144653,
                  "top": 0.34681689739227295,
                  "width": 0.09181994199752808,
                  "height": 0.051107827574014664,
                  "page": 0
                }
              }
            ]
          }
        ]
      }
    ]
  }
}
{
  "extraResults": {
    "lineBlocks": [
      {
        "text": "Lucid Software Inc.",
        "boundingBox": {
          "left": 0.06718823529411766,
          "top": 0.03720909090909091,
          "width": 0.18764705882352944,
          "height": 0.013681818181818179,
          "page": 0
        }
      },
      {
        "text": "Invoice",
        "boundingBox": {
          "left": 0.5149058823529411,
          "top": 0.037427272727272726,
          "width": 0.07731764705882359,
          "height": 0.01346363636363636,
          "page": 0
        }
      },
      {
        "text": "10355 South Jordan Gateway Suite 300",
        "boundingBox": {
          "left": 0.0670235294117647,
          "top": 0.06247272727272728,
          "width": 0.28165882352941174,
          "height": 0.01223636363636363,
          "page": 0
        }
      },
      {
        "text": "Invoice #",
        "boundingBox": {
          "left": 0.5147058823529411,
          "top": 0.06262727272727273,
          "width": 0.06205882352941175,
          "height": 0.009618181818181819,
          "page": 0
        }
      },
      {
        "text": "4923692",
        "boundingBox": {
          "left": 0.6605882352941177,
          "top": 0.06288181818181818,
          "width": 0.062400000000000025,
          "height": 0.009363636363636362,
          "page": 0
        }
      }
    ]
  }
}
Language