Getting Started
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¶
All predictions generated by Autosuggest are accompanied by a confidence score, serving as a metric for the prediction's quality. Generally, higher confidences indicate to a higher probability of the suggestion being accurate.
To present your users with reliable predictions, it's advisable to filter out (i.e. simply disregard) answers with confidence scores below an acceptable threshold.
Threshold choice
Picking the optimal cutoff threshold involves a bit of trial and error. The higher number you choose, the better the quality of the predictions you're showing to the user, but conversely you're also providing less prediction output to the user.
What the right tradeoff is, depends on user preferences, UX considerations, and the specific use case you're using Autosuggest for.
For instance, if you set a quality score threshold of 0.85, Autosuggest automatically displays suggestions when their confidence exceeds 85%.