Document Insights API

Find handwritten signatures and build a table of contents for a document. A vision language model reads each page image. This API does not extract text, so use the Extraction API if you also need the text.

Endpoint	/document-insights
URL	https://llmwhisperer-api.us-central.unstract.com/api/v2/document-insights
Method	POST
Headers	unstract-key: <YOUR API KEY>
Body	Binary data (file contents)

For every page it processes, the API returns:

• Signatures: handwritten signatures found in a designated signature area, such as a field labelled "Signature", "Sign Here" or "Authorized Signature". Each signature carries the signer's name if a printed "Name:" field sits next to it. Empty signature lines, typed names and handwriting outside a signature area are not reported.
• Table of contents entries: section headings with their level and numbering. Entries from all pages are combined into one nested table of contents for the document.

Pages are read one at a time and in order. The model sees the previous page's heading levels when it reads each page, so numbering such as 1.1 or A. keeps its level from page to page. Because of this, a long document takes longer to process than in the Extraction API, which processes pages in parallel.

info

This API uses Google Gemini and is available on LLMWhisperer Cloud. On-prem installations need a Gemini API key configured for it. It does not use the optional GPU nodes of an on-prem deployment.

Parameters

Parameter	Type	Default	Required	Description
pages_to_extract	string		No	Define which pages to process. By default all pages are processed. Example 1-5,7,21- processes pages 1,2,3,4,5,7,21,22,23,24... till the last page.
url_in_post	boolean	false	No	If set to true, send the URL of the document to download in the request body instead of the document itself. See example below.
tag	string	default	No	Auditing feature. Set a value which will be associated with the invocation of the API. This can be used for cross referencing in usage reports.
file_name	string	sample.pdf	No	Auditing feature. Set a value which will be associated with the invocation of the API. This can be used for cross referencing in usage reports.
use_webhook	string		No	The name of the webhook to call when processing is complete. The webhook must have been registered earlier using the webhook management API.
webhook_metadata	string		No	Any metadata which should be sent to the webhook. This data is sent verbatim to the callback endpoint. Can only be used together with use_webhook.

The text extraction parameters of the /whisper API, such as mode, output_mode or lang, do not apply here and are ignored.

Supported file types

• PDF documents, including scanned PDFs
• Images (JPEG, PNG, TIFF, BMP, GIF and WEBP)
• Word, PowerPoint and LibreOffice documents, which are converted to PDF before processing

Excel files (XLS, XLSX) and plain-text files are rejected, because the model needs a page image to look at.

Request Body

The request body should contain the document to process. The document should be in application/octet-stream format.

If you are using the url_in_post parameter, the URL should be sent in the request body. Content-Type should be text/plain. See curl example below.

Example Curl Requests

Upload document

curl -X POST --location 'https://llmwhisperer-api.us-central.unstract.com/api/v2/document-insights' \
-H 'unstract-key: <Your API Key>' \
--data-binary '@your-file-to-process.pdf'

Process document from URL

curl -X POST --location 'https://llmwhisperer-api.us-central.unstract.com/api/v2/document-insights?url_in_post=true' \
-H 'unstract-key: <Your API Key>' \
--data 'https://your-url-to-process.pdf'

To include the headers in the response use curl -i in the request.

Response

A successful request will return a 202 status code with a JSON response containing the whisper_hash.

The typical workflow is:

1. Call the /document-insights API with your document.
2. Check the status by calling the Status API with the returned whisper_hash. Repeat this step until the status is processed.
3. Get the signatures and table of contents by calling the Document Insights Retrieve API.

Instead of polling, you can pass use_webhook to have the result delivered to a webhook.

HTTP Status	Content-Type	Headers	Description
202	application/json		The request was accepted. The JSON contains the whisper_hash to use with the status and retrieve APIs. Refer below for JSON format.
400	application/json		The request was rejected. Refer below for the error messages.
415	application/json		The file type is not supported.

Example 202 Response

{
  "message": "Document Insights Job Accepted",
  "status": "processing",
  "whisper_hash": "xxxxxa96|xxxxxxxxxxxxxxxxxxx4ed3da759ef670f"
}

Example 400 Response

{
    "message": "<Error Message>"
}

Possible Error Messages

• Excel and plain-text files are not supported for document insights. Please provide a PDF or image file.
• File type '<file type>' not supported (HTTP 415)
• Webhook not found: the webhook named in use_webhook is not registered.
• Webhook metadata provided without webhook: webhook_metadata was sent without use_webhook.
• File size exceeded. ...: the document is larger than your plan allows.

Status while processing

The Status API works with the whisper_hash from this API. While the document is processing, the status message reads Processing page <n> of <total>. Each processed page adds an entry to detail:

{
    "detail": [
        {
            "page_no": 1,
            "message": "extraction_success",
            "execution_time_in_seconds": 3.42,
            "toc_entries_found": 2,
            "signatures_found": 0,
            "input_tokens": 2150,
            "output_tokens": 180,
            "total_tokens": 2330
        }
    ],
    "message": "Processing page 1 of 4",
    "status": "processing"
}

When all pages are done, the status is processed and the message is document_insights_done. If processing fails, the status is error and the message is Error in document insights extraction. Please retry the operation.

Usage

Pages processed by this API are counted under current_page_count_document_insights in the Usage API. Only pages that were processed are counted.