# SmartExtractSimple API

The SmartExtractSimple API provides a much simpler and cleaner interface than [SmartExtract API](/smart-extract-documentation/smart-extract.js/smartextract-api.md). Most of the times you should be good using this. This API is a wrapper on top of the SmartExtract hiding all the event handling API with a simpler promise based API.

## Usage

### Creating an Instance

To start a SmartExtract session in order to extract a document or edit previously extracted data, you need to first create a SmartExtract instance.

{% tabs %}
{% tab title="Production Environment" %}

```javascript
import { SmartExtractSimple } from '@clik-ai/smart-extract';

const smex = new SmartExtractSimple({
  baseUrl: 'https://app.clik.ai/smart-extract',
});
```

{% endtab %}

{% tab title="Staging Environment" %}

```javascript
import { SmartExtractSimple } from '@clik-ai/smart-extract';

const smex = new SmartExtractSimple({
  baseUrl: 'https://app.clik.ai/smart-extract-stg',
});
```

{% endtab %}
{% endtabs %}

| Parameter | Required | Description                                                                                                                        |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| baseUrl   | No       | Points to the SmartExtract service base url. You normally will not need to provide this value. It will default to the correct url. |

### Extracting Document Data

You can start a document data extraction session by calling a simple promised based `extractDocumentData` API. The promise returned by this API will be resolved with the extracted data or `null` in case the user clicked the cancel button.

```javascript
const data = await smex.extractDocumentData({
  session: {
    mountNode: $('#smexWrapper')[0],
    sessionAuthToken: token,
    closeOnComplete: false,
  },
  file: fileDataUrl,
  fileName: file.name,
  options: {
    disableRetry: true,
    shouldPreProcessData: false,
    preProcessFunction: someFunctionToPreProcessExtractedData,
    
    // ...
  }
});

// Note:
// -----
//
// If user clicked 'Cancel'
// data = null 

// If user clicked 'Save'
// data = {
//   meta: {
//     assetType: '<The asset type of the document>',
//     documentType: '<The document type>',
//     osPeriod: [new Date('<start-date>'), new Date('<end-date>')],
//     fileName: <The document file name>,
//     ...
//   },
//   workbookData: {...},
//   documentData: {
//     // plain text data as detected in the document
//     source: {
//       rows: [
//         // First value is S.N. on each row signifying a unique row-id for each row in the document
//         ['S.N.', '', '', '', ....], // Each row is an array of all text-tokens detected in the row
//         [1010, ..., ..., ..., ...],
//         // ... rest of the data rows
//       ],
//     }
//     // extracted document data as a list of object. 
//     extracted: {
//       rows: [
//         { '<column-name-1>': '<column-value>', '<column-name-2>': '<column-value>', /* ... ,*/}
//         // ... rest of the data rows
//       ]
//     }
//   },
// }
```

<table data-header-hidden><thead><tr><th>Parameter</th><th>Required</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Parameter</td><td>Required</td><td>Type</td><td>Description</td></tr><tr><td>session</td><td>Yes</td><td>object</td><td>Configuration option for the SmartExtract session</td></tr><tr><td>session.mountNode</td><td>Yes</td><td>DOM Element</td><td>The DOM element where SmartExtract iframe will be mounted</td></tr><tr><td>session.sessionAuthToken</td><td>Yes</td><td>string</td><td>The session auth token obtained from the <a href="/pages/-MkCzGXmEdeLcFu_-kWy#token">authentication api</a></td></tr><tr><td>session.closeOnComplete</td><td>No</td><td>boolean</td><td><p>If set to true the smart extract session will end removing the iframe element from DOM when user clicks <code>Save</code> or <code>Cancel</code> button.</p><p>Defaults to <code>false</code></p></td></tr><tr><td>file</td><td>Yes</td><td>string</td><td>The pdf or xlsx file encoded as a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs">Data Url</a> string</td></tr><tr><td>fileName</td><td>Yes</td><td>string</td><td>The file name. Make sure that the file name has correct extension or your users may not see a proper file preview. </td></tr><tr><td>options</td><td>No</td><td>object</td><td>Options to configure data extraction.<br>See <a href="/pages/-MkHMNsZmasTAm9sM9Q-">Styling and Customisation</a> section for more details on how to style and customise the extraction form and spreadsheet view.</td></tr><tr><td>options.disableRetry</td><td>No</td><td>boolean</td><td><p>If <code>true</code> the returned promise will be rejected in case data extraction fails.</p><p>If <code>false</code> SmartExtract will show a retry option so that user can retry extraction.</p></td></tr><tr><td>options.shouldPreProcessData</td><td>No</td><td>boolean</td><td><p>If <code>true</code> then function provided via the option </p><pre><code>preProcessFunction
</code></pre><p>will be called with the extracted data in the paramater. This data can be mutated  and then sent back to smart-extract to be rendered in the spreadsheet.</p><p>If <code>false</code> preProcessFunction will be ignored i.e there smart-extract will not send back the data for pre-processing.</p></td></tr><tr><td>options.preProcessFunction</td><td>No</td><td>Function</td><td>Smart-extract will pass extracted data to this function. This function can be used to mutate the extracted data before it is loaded in the spreadsheet. This function should return a promise which should resolve to the updated data.</td></tr></tbody></table>

### Editing Previously Extracted Data

The SmartExtract component not just allows you to extract data from documents, your users can continue editing the data in the SmartExtract widget from where they left off. The `editDocumentData` allows you to pass on previously saved data and continue editing in the SmartExtract component.

Under the edit mode, the user will be taken directly to the spread sheet screen where they can edit the data. Clicking 'Save' or 'Cancel' will trigger one of the 'data' or 'cancel' events.

```javascript
const data = await smex.editDocumentData({
  session: {
    mountNode: $('#smexWrapper')[0],
    sessionAuthToken: token,
    closeOnComplete: false,
  },
  data: {
    workbookData: {...},
    meta: {...},
  }
});
```

| Parameter                | Required | Type        | Description                                                                                                                                                                                          |
| ------------------------ | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| session                  | Yes      | object      | Configuration option for the SmartExtract session                                                                                                                                                    |
| session.mountNode        | Yes      | DOM Element | The DOM element where SmartExtract iframe will be mounted                                                                                                                                            |
| session.sessionAuthToken | Yes      | string      | The session auth token obtained from the [authentication api](/smart-extract-documentation/api-reference.md#token)                                                                                   |
| session.closeOnComplete  | No       | boolean     | <p>If set to true the smart extract session will end removing the iframe element from DOM when user clicks <code>Save</code> or <code>Cancel</code> button.</p><p>Defaults to <code>false</code></p> |
| data                     | Yes      | object      | The data object returned by the [`extractDocumentData`](/smart-extract-documentation/smart-extract.js/smartextractsimple-api.md#extracting-document-data) api                                        |

### Ending SmartExtract Session

If you passed the `closeOnClomplete` flag as `false` the SmartExtract session will remain open when user clicks `Save` or `Cancel`. It will be your responsibility to call the `endSession` API to end the session. Calling this API will remove the iframe from the DOM and clean up any event listeners added.

```javascript
smex.endSession()
```

{% hint style="warning" %}
Its important to end SmartExtract session when you are done with extraction. Ending the session clears any event handlers attached. Keeping the `closeOnComplete` flag as true would take care of this most of the times i.e. if the extraction flow completes in a success or cancel or error event. However, if you externally end the session e.g. by hiding a popup dialog on which the SmartExtract iframe was attached, you must call the `endSession` API to ensure that eveythins is cleaned up correctly.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://clik-ai.gitbook.io/smart-extract-documentation/smart-extract.js/smartextractsimple-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.