Asynchronous processing of Smartscan¶

Logo

The asynchronous processing of Smartscan allows you to submit a document for processing and receive the results at a later time. This feature is particularly useful for large documents that require more time to process.

Quicklinks¶

Read more about Smartscan.
API Reference.
Feature list available in asynchronous processing.
All supported countries.
All supported file types.
Data Deletion Policy.

Getting started¶

Asynchronous processing workflow¶

The asynchronous processing of Smartscan is built around Transactions. A Transaction is a request to process a document with a list of features - the data points you want to extract from the document. The transaction can be tagged with a custom ID for easier tracking and deletion. The workflow consists of the following steps:

Create Transaction: Submit a document for processing with a list of features and optional tags and custom ID.
Get Transaction Status: Check the status of the transaction to see if it is completed or failed.
Get Transaction Results: Retrieve the extracted data from the document.
Delete Transaction: Delete the transaction and its data if needed.

Access to the API¶

Demo Access Token

For development purposes, you can use the demo access token demo, like in the example below, for access to staging. Use the staging endpoints indicated in the endpoints section. Please note that this token is rate-limited and should only be used for testing. We strongly advise you to not use demo token for any sensitive data as anyone with the token can access the data.
Staging Access Token (Recommended)

For more extensive testing and integration purposes, we recommend generating a staging access token through our Staging portal. Follow the steps in the Quick Start Guide for generating a staging or production access tokens. Refer to the Authentication for more information on the server-to-server token method.

Example requests¶

Create Transaction Request¶

POST v1/transactions

https://api.stag.ssn.visma.ai/v1/transactions

Authorization - Bearer Token¶

Token: demo

Body - raw (json)¶

Body

{
    "document": {
        "source": {
            "httpUri": "http://storage.googleapis.com/vml-test-data/distributable/pdf5/10.pdf"
        }
    },
    "features": [ "RECEIVER_COUNTRY_CODE", "IBAN" ],
    "tags": ["testing"],
    "customId": "my-first-transaction"
}

Create Transaction Response¶

Body - raw (json)¶

Body

{
    "id": "<transaction-id>",
    "customId": "my-first-transaction"
}

Get Transaction Status Request¶

You can get transaction status either by the transaction ID or the custom ID. The transaction ID is unique for each transaction, while the custom ID is optional and can be set by the user.

GET v1/transactions/{transaction_id}/status
https://api.stag.ssn.visma.ai/v1/transactions/<transaction-id>/status
Authorization - Bearer Token¶

Token: demo

Calling the Get Transaction Status endpoint with the custom ID:

GET v1/transactions/status?custom_id={custom_id}
https://api.stag.ssn.visma.ai/v1/transactions/status?custom_id=my-first-transaction
Authorization - Bearer Token¶

Token: demo

Get Transaction Status Response¶

The status of the transaction can be CREATED, RUNNING, DONE, or FAILED.

Body - raw (json)¶

Body

{
    "id": "<transaction-id>",
    "status": "DONE",
    "customId": "my-first-transaction"
}

Get Transaction Results Request¶

You can get transaction results either by the transaction ID or the custom ID. The transaction ID is unique for each transaction, while the custom ID is optional and can be set by the user.

GET v1/transactions/{transaction_id}/results
https://api.stag.ssn.visma.ai/v1/transactions/<transaction-id>/results
Authorization - Bearer Token¶

Token: demo

Calling the Get Transaction Results endpoint with the custom ID:

GET v1/transactions/results?custom_id={custom_id}
https://api.stag.ssn.visma.ai/v1/transactions/results?custom_id=my-first-transaction
Authorization - Bearer Token¶

Token: demo

Get Transaction Results Response¶

The Get Transaction Results response includes:

Transaction ID: A unique identifier for the transaction.
Custom ID: The custom ID if provided in the request.

Body - raw (json)¶

Body

{
    "id": "<transaction-id>",
    "annotations": [
        {
            "feature": "RECEIVER_COUNTRY_CODE",
            "candidates": [
                {
                    "value": "DK",
                    "confidence": {
                        "level": "VERY_HIGH",
                        "value": 0.991518795
                    },
                    "modelMetadata": {
                        "modelName": "layoutlm-r3",
                        "modelVer": "1"
                    }
                }
            ]
        }
    ],
    "customId": "my-first-transaction"
}

Document Data Sources¶

The caller can choose either to send the document data as part of the request or as shown in the example request through URI. Key field content is the document data base64 encoded.

Example request¶

POST v1/transactions¶

https://api.stag.ssn.visma.ai/v1/transactions

Authorization - Bearer Token¶

Token: demo

Body - raw (json)¶

Body

{
    "document": {
        "content": "Vl00oANHjF3gxaYT4fQ0PSDJwwZIuMLl0GdNlgyKhF4KYOtcH3r... -- this is unfinished base64 enconding --"
    },
   "features": [ "RECEIVER_COUNTRY_CODE", "IBAN" ],
    "tags": ["testing"],
    "customId": "my-first-transaction"
}

Smartscan Response¶

The annotations returned from the Async Smartscan are the same as the synchronous Smartscan. For more information, refer to the Smartscan Documentation.

Data Deletion Policy¶

You can either delete the data by deleting the transaction either by transaction_id or custom_id, or you can delete multiple transactions via tag, if provided in the Create Transaction request.

Delete Transaction Request¶

DELETE v1/transactions/{transaction_id}
https://api.stag.ssn.visma.ai/v1/transactions/<transaction-id>
Authorization¶

Bearer Token

Token: demo

Response¶

200 OK

Calling the Delete Transaction endpoint with the custom ID:

DELETE v1/transactions?custom_id={custom_id}
https://api.stag.ssn.visma.ai/v1/transactions?custom_id=my-first-transaction
Authorization¶

Bearer Token

Token: demo

Response¶

200 OK

Delete Tag Request¶

Delete transaction by tag will delete all transactions with the provided tag.

DELETE v1/tags/{tag}
https://api.stag.ssn.visma.ai/v1/tags/testing
Authorization¶

Bearer Token

Token: demo

Response¶

200 OK