> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terrafai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Fields

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

```text theme={null}
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

<CodeGroup>
  ```bash theme={null}
  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=""'
  ```
</CodeGroup>

## Response Example

Below is an example of a success response.

```text theme={null}
{
    "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                                                                                                                                                                    |