Overview/Introduction
Overview

Introduction

Design

AzoraOne allows you to integrate self-learning automation directly into your application.

  • AzoraOne's API is designed around REST.

  • It supports the JSON format.

  • It is secured using an Ocp-Apim-Subscription-Key header and a Client-Key header in each request.

  • API requests must use the HTTPS protocol. Requests made with HTTP are terminated.

API

All AzoraOne API requests are made to the base URL:

https://api.azora.one/{api}/{version}

The value of the {api} parameter in the URL depends on which API you are trying to access. You can find this value in the API Explorer pages.

  • When exploring the sandbox API, the value will be sandbox.

  • When you have access to a production API, the value will be your application's name, or an abbreviation of it, for example myaccountingapp. If you have access to a test API, the value will be the production value followed by _test, i.e. myaccountingapp_test.

The value of the {version} parameter in the URL depends on which version of AzoraOne you want to access.

The current version is "v1".

Concept

AzoraOne is centred around the concept of:

  1. Adding a file to an existing company

  2. Extracting the file

  3. Submitting bookkeep data associated with the file

There is no user configuration or setup of rules for AzoraOne to learn what bookkeeping data to extract; instead, AzoraOne learns by being fed the actual bookkeeping data.

Required operations

In order to create a successful integration of AzoraOne you will need to implement the following four operations.

  Required operations flow Add a company happens once. Add a file, extract data, and bookkeep data repeat, with bookkeeping feeding back to improve future extraction accuracy. INITIAL STEP REPEATABLE STEPS Add a company Add a file Extract data Bookkeep file Improves future extraction accuracy

  1. Add a company
    The companies endpoint allows users to create a new company, used as a container for future file uploads and processing, as well as company-specific knowledge (i.e. model pool).

  2. Add a file
    The files endpoint allows users to upload a file to the specified company and prepare it for extraction.

  3. Extract a supplier invoice, receipt or customer invoice
    The supplierInvoices, receipts and customerInvoices endpoints allow users to extract bookkeeping data from the specified file. This data can be presented to the user as a bookkeeping suggestion.

  4. Bookkeep a supplier invoice, receipt or customer invoice
    The supplierInvoices, receipts and customerInvoices endpoints also allow users to add correct bookkeeping to the specified file, further developing AzoraOne's knowledge on how the company bookkeeps.

You can choose which of the three document types suits your application, but integrating at least one is required. Creating company-specific models on bookkeep is what produces AzoraOne's customised extraction results, so without it the integration provides no benefit.

Creating a company will only have to be performed once per customer. Once created, multiple files can be uploaded to the company. Uploaded files can be extracted and bookkept multiple times.

Optional operations

Once the required operations are working as intended, you can add optional operations that may provide additional value for your customer.

  • The suppliers and customers endpoints enable automatic matching of a file to a supplier or customer in your application's supplier/customer lists.

  • The patterns endpoint allows users to add deterministic control over sorting of files, by specifying identifiers that may appear on an uploaded file and the destination it should route to in the application. This differs from patching a file's type or verification series, which AzoraOne learns from passively in the background whenever a user moves a file, without the user necessarily being aware that AzoraOne is learning from it. With patterns, the user actively defines the routing rule up front.

  • The progenitors endpoint allows users to inherit knowledge from other companies that are already trained.

  • The memories endpoint allows users to reset a company's knowledge and start training it from scratch. This affects all users of that company, not just the one who triggers the reset.

  • The models endpoint allows users to selectively inactivate models that are no longer wanted.

  • Retrieving all files supports filtering and full-text search, so you can build views such as "all unprocessed receipts from last week" without fetching every file and filtering client-side.

  • The file details operation lets you retrieve a single file's raw content, OCR'd text, and full extraction and booking history, useful for building a file preview or audit view in your application.

  • Requesting a company with metrics set to true returns aggregated processing statistics, useful for dashboards or reporting.

AzoraOne provides many operations that may not add any value to the customer, but are helpful when integrating and testing the service.

You can find a full list of available operations in the AzoraOne Sandbox API below. It contains detailed descriptions for each operation.

The self-learning process

The diagram and steps below show how the operations above work together to build a company's model pool over time, and how that pool can be shared between companies using progenitors.

  AzoraOne self-learning process and model pool sharing Upload, sort, extract and bookkeep build a company's model pool. Extract and sort also draw from the pool. The pool can be shared with another company. COMPANY A Add a file 1 Sort file 2 Extract data 3 Bookkeep file 4 Model pool COMPANY B Add a file Sort file Extract data Dashed tile = optional step. Solid arrow = writes to the model pool. Dashed arrow = reads from it.

  1. A user uploads a file to your application.

  2. If the user moves the file to a different module than suggested, your app can update AzoraOne's sorting via a PATCH request to the files endpoint. This is optional, since bookkeeping (step 4) also updates it.

  3. Extraction fills fields using a model from the company's own model pool. Results are dynamic: they can change as activity elsewhere in the application improves the model pool over time. The same file also yields a different result per endpoint, supplier invoice, receipt, or customer invoice.

  4. Saving (bookkeeping) the file, with any edits the user made, builds a model and updates the pool.

  5. Future uploads and extractions in this company automatically use the updated model pool.

  6. A model pool can be shared with, or inherited by, another company. This requires explicitly setting up a progenitor relationship between the two companies.

Steps 1–4 describe what happens in your application. Each can involve one or more AzoraOne API calls.

Note: If no matching model can be found in the company's own model pool, for example on a fresh company with no models yet, extraction uses AzoraOne's precognition model instead.

Feedback

If you have any suggestions on how to improve the documentation, let us know by sending us an email at support@arkimera.se.