Extract Fields - Terrafai API Docs

Synchronous extraction processes a document in a single request–response cycle. The connection remains open until the extraction process completes and the full response is returned.

Endpoint

https://smartsense-dev-api.nostello.com/api/v1/extractFields

Request Header

All requests must include an API key in the Authorization header.

Key	Value
Authorization	api-key [your api key]

Request Body

The request must be sent as multipart/form-data.

Document Source

Key	Type	Value
file	File	[binary file upload]

The file is compulsory when sending requests.

Extraction Options

Key	Type	Default	Value
templateName	Text		[template name]
filterName	Text		[filter name]
documentSplitting	Text	false	true/false
returnDocuments	Text	false	true/false
returnText	Text	false	true/false
schemaChunking	Text	auto	auto/combined
password	Text		[password]

Request Example

curl --location 'https://smartsense-dev-api.nostello.com/api/v1/extractFields' \
--header 'Authorization: api-key opt_ede920076469_M8M9wr6WnmlvM05iiz6Rqxlr9yG-X8WjItmmqzIp03A' \
--form 'file=@"[file path]"' \
--form 'templateName="[template name]"' \
--form 'filterName=""' \
--form 'documentSplitting="false"' \
--form 'returnDocuments="false"' \
--form 'returnText="false"' \
--form 'schemaChunking="auto"' \
--form 'password=""'

Response Example

Below is an example of a success response.

{
    "success": true,
    "data": {
        "completionTime": 48.94,
        "originalName": "[document name]",
        "processedPages": 1,
        "documents": [
            {
                "extracted": true,
                "averageDocumentConfidence": 94.32,
                "sourcePages": [
                    1
                ],
                "usedTemplateName": "[template name]",
                "content": {
                    "[field 1]": {
                        "value": "[field value]",
                        "confidence": 99.93,
                        "page": 1,
                        "boundingBox": {
                            "top": 0.24541398882865906,
                            "left": 0.7629675269126892,
                            "width": 0.03504106402397156,
                            "height": 0.007880417630076408
                        }
                    },
                    "[field 2]": {
                        "value": "[field value]",
                        "confidence": 99.02,
                        "page": 1,
                        "boundingBox": {
                            "top": 0.195048987865448,
                            "left": 0.7912929654121399,
                            "width": 0.04586394503712654,
                            "height": 0.007497004698961973
                        }
                    }
                },
                "returnedText": "[text blob]",
				"returnedDocumentBase64": "[Base 64]"
            }
        ]
    }
}

Field	Type	Values	Description
success	Boolean	true/false	Indicates the success or failure of the request as a whole.
data	Objects	-	Contains all of the data relating to the request.
completionTime	Decimal	≥ 0	The time it took to process the entire request.
originalName	String	-	The name of the original document sent in the request.
processedPages	Whole Number	≥ 0	The total number of pages processed that the original document contained.
documents	Array	-	Contains the information relating to each document extracted. When document splitting is on, then there will be multiple document objects.
extracted	Boolean	true/false	Indicates whether the document was extracted. When there is a filter in the extraction process, some documents will be false and not extracted depending on the rules specified in the filter.
averageDocumentConfidence	Decimal	0–100	Indicates the average confidence across all fields extracted from the document expressed as a percentage.
sourcePages	Array	page numbers	Pages from which this document was extracted
usedTemplateName	String	-	The template used to extract the document.
content	Object	field-name → object	This holds the information relating to each field extracted.
value	String	-	The value of the field extracted.
confidence	Decimal	0–100	The confidence value for that specific extracted field.
page	Whole Number	≥ 1	The page from where the document was extracted.
boundingBox	Objects	-	The 4 coordinates creating the box that surrounds the information extracted.
returnedText	String	-	Contains the text blob of all the text found on the document.
returnedDocumentBase64	String	Base64	Base64-encoded PDF document

​Endpoint

​Request Header

​Request Body

​Document Source

​Extraction Options

​Request Example

​Response Example