Getting Started

Logo

Quick Start¶

Access to the API¶

Demo Access Token

Demo access is disabled for Autosuggest due to various security and GDPR reasons.
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.

1. Create a dataset¶

Autosuggest works in a concept of datasets which serve as collection of data used to train machine learning models. In this step, you'll initiate the creation of a bank statement classifier dataset. To create the dataset, submit the following request.

The dataset name has to be unique per project.

POST v2/datasets¶

https://api.stag.asgt.visma.ai/v2/datasets

<dataset-name> has to be unique per project.

Authorization - Bearer Token¶

Token: [API token]

Body - raw (json)¶

Body

{
    "dataset_name": "dataset-name",
    "tags": [
        "customer1",
        "company1"
    ]
}

2. Stream in or batch create examples¶

The dataset represents a collection of data therefore we need to upload a dataset to train on.

POST v2/datasets/<dataset-name>/examples:batchCreate¶

https://api.stag.asgt.visma.ai/v2/datasets/dataset-name/examples:batchCreate

<dataset-name> should be taken from the body of the create dataset request.

Authorization - Bearer Token¶

Token: [API token]

Body - raw (json)¶

Body

{
    "examples": [
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Local Supermart - Weekly Groceries",
                    "amount": 120.50
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Buying toilet paper",
                    "amount": 198.50
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Local Supermart",
                    "amount": 120.99
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Shopping mall - Groceries",
                    "amount": 125.99
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Super Supermart - Daily Groceries",
                    "amount": 18.50
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Local-ish Supermart - Weekly Groceries",
                    "amount": 120.69
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Fresh Market - Produce and Snacks",
                    "amount": 45.75
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Neighborhood Grocers - Monthly Supplies",
                    "amount": 150.20
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Discount I couldn't resist",
                    "amount": 69
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "supermarket"
                },
                {
                    "name": "account",
                    "value": "001"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Supersuper market",
                    "amount": 99.99
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Local Office Supplies Store - Monthly Restock",
                    "amount": 85.50
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Online Office Depot - Printer Paper and Ink",
                    "amount": 35.25
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Stationery World - New Office Supplies",
                    "amount": 120.75
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Dunder Mifflin",
                    "amount": 999
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Tech Solutions Inc. - Tech Accessories",
                    "amount": 50.00
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Business Essentials Co. - Office Equipment",
                    "amount": 200.30
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Business Essentials Co.",
                    "amount": 199.30
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Essentials Co.",
                    "amount": 999.99
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Printer Business Co.",
                    "amount": 16890.79
                }
            }
        },
        {
            "targetValues": [
                {
                    "name": "expense",
                    "value": "office-supplies"
                },
                {
                    "name": "account",
                    "value": "002"
                }
            ],
            "data": {
                "transaction": {
                    "text": "Office desks Business Co.",
                    "amount": 1234.79
                }
            }
        }
    ]
}

3. Check on the status of the training¶

The get trainings or get dataset trainings endpoint shows trainings for multiple or a single dataset and their status.

GET v2/datasets/<dataset-name>/trainings¶
https://api.stag.asgt.visma.ai/v2/datasets/<dataset-name>/trainings
<dataset-name> should be taken from the body of the create dataset request.
Authorization - Bearer Token¶

Token: [API token]

Body - empty¶

4. Make a prediction¶

After confirming that the model has been successfully trained through the get trainings endpoints, you are ready to make predictions. The model, having learned from the dataset you created, will provide predictions based on the input, giving suggestions on how you categorise expenses and assign them to the relevant accounts.

POST v2/datasets/<dataset-name>:suggest¶

https://api.stag.asgt.visma.ai/v2/datasets/dataset-name:suggest

<dataset-name> should be taken from the body of the create dataset request.

Authorization - Bearer Token¶

Token: [API token]

Body - raw (json)¶

Body

{
    "input": {
        "transaction": {
            "text": "Groceries",
            "amount": 199.00
        }
    }
}

5. Improve your dataset with adding more data¶

To continuously improve your datasets and keep them up to date, Autosuggest provides functionality to add more data under a dataset.

You can stream examples as they come in. This can be done when a user corrects or confirms a suggestion from Autosuggest. Send examples in batch when transitioning an existing user to Autosuggest, and want to use their existing data to train the Autosuggest model. Alternatively, you may be using Autosuggest in an existing batch workflow in your product.

POST v2/datasets/<dataset-name>/examples¶

https://api.stag.asgt.visma.ai/v2/datasets/dataset-name/examples

<dataset-name> should be taken from the body of the create dataset request.

Authorization - Bearer Token¶

Token: [API token]

Body - raw (json)¶

Body

{
    "example": {
        "targetValues": [
            {
                "name": "expense",
                "value": "office-supplies"
            },
            {
                "name": "account",
                "value": "002"
            }
        ],
        "data": {
            "transaction": {
                "text": "Office desks Business Co.",
                "amount": 1234.79
            }
        }
    }
}

Prediction Quality¶

Every prediction generated by the Autosuggest API come with a confidence score (numerical value) and confidence level (VERY_HIGH to VERY_LOW) in the response, which serve as an indicator for the quality of the prediction. Generally, higher confidence scores and level indicate a higher probability of the suggestion being accurate.

Threshold Confidence Level and Suggestion Limit¶

You can configure two parameters for the Autosuggest suggestions:

Suggestion Limit: The maximum number of suggestions in the response request. DEFAULT: If you don't specify anything in the api call, the number of suggestions shown is going to be 10.
Threshold Confidence Level: The minimum confidence level which each returned suggestion candidate will have. In other words, this allows you to filter results by confidence level.

Thresholds are dynamically selected cutoff values to maintain the optimal performance of a trained model. Selecting the optimal cutoff threshold involves some trial and error. To simplify this process, we introduced automated selection of thresholds with confidence levels. There are five confidence levels:

VERY_HIGH
HIGH
MID
LOW
VERY_LOW

These values are calculated for each model target.

The higher the confidence level you choose, the better the quality of the predictions shown to the user. However, this also means providing fewer prediction outputs. The current thresholds are:

VERY_LOW: Results in no filtering.
LOW: For a prediction to have low confidence, the resulting precision of the model for the target must be above 0.5. This means if the model predicts something, it is likely to be correct at least 50% of the time.
MEDIUM: For a prediction to have medium confidence, the resulting precision of the model for the target must be above 0.8. This means if the model predicts something, it is likely to be correct at least 80% of the time.
HIGH: For a prediction to have high confidence, the resulting precision of the model for the target must be above 0.9. This means if the model predicts something, it is likely to be correct at least 90% of the time.
VERY_HIGH: For a prediction to have very high confidence, the resulting precision of the model for the target must be above 0.95. This means if the model predicts something, it is likely to be correct at least 95% of the time.

!!! Information If you are receiving UNKNOWN confidence level in your suggestions it is likely that your model was trained before we introduced confidence thresholds. We recommend retraining the model.

Best practice

While it seems intuitive to interpret a high confidence score like 0.99 as an indicator of a very certain result, this is in reality rarely the case. These models tend towards claimed extreme certainty even when it is completely unwarranted.

It is therefore highly recommended to instead use the confidence level when filtering answers - these levels have been tuned to provide a more realistic and intuitive description of answer quality. The levels (like HIGH) are precision-driven. So choosing a level of HIGH means that, when the model makes a prediction, it is correct at least 90% of the time.

The confidence scores are still provided to remain backwards compatible.

Getting Started

Quick Start¶

Access to the API¶

1. Create a dataset¶

POST v2/datasets¶

Authorization - Bearer Token¶

Body - raw (json)¶

2. Stream in or batch create examples¶

POST v2/datasets/<dataset-name>/examples:batchCreate¶

Authorization - Bearer Token¶

Body - raw (json)¶

3. Check on the status of the training¶

GET v2/datasets/<dataset-name>/trainings¶

Authorization - Bearer Token¶

Body - empty¶

4. Make a prediction¶

POST v2/datasets/<dataset-name>:suggest¶

Authorization - Bearer Token¶

Body - raw (json)¶

5. Improve your dataset with adding more data¶

POST v2/datasets/<dataset-name>/examples¶

Authorization - Bearer Token¶

Body - raw (json)¶

Prediction Quality¶

Threshold Confidence Level and Suggestion Limit¶