Skip to content

Getting Started

Important information to get started with Document Reader SDK.

Worker Model

By default, the web service starts with one worker. Each worker processes documents in a single-threaded mode that means that it can process only one request at a time. So, if you submit many requests at once, they queue up and are processed one by one.

To improve the throughput performance, you can launch more workers according to the planned load. The web service can spawn multiple workers under one service instance. You may set the workers number based on the hardware limitations you have. Also, you can use N web server instances with multiple workers under the loadbalancer to increase the performance even more.


Each worker in our license model counts as an instance. So, a setup of 3 machines with 2 workers on each requires a license with 6 instances. For transaction-based licenses, the number of workers is not limited, only the number of the process requests counts.

Interactions with Licensing Service

When working with an online license, the web service contacts the licensing service at via encrypted communication and sends requests for validation.


The licensing service is created to manage the license keys, and this is its only purpose. The web service is customer-hosted, on-prem, and all personal data remains on the customer's servers and is not being communicated back to Regula.

On the start of a worker, the licensing service is contacted and a registration request is sent. If the license is valid, the worker runs. Otherwise, it fails.

In case the online license is transaction-based, each time the functionality is used (on each /process call), the web service contacts the licensing service with the POST request. This request consists of the license id, transaction id, session id, client ip, transaction scenario, product type and version used, and the timestamp. If the license is valid for this kind of request, the request gets logged, the 'OK' response is provided, and the SDK returns the processing results.

In case the online license is instance/worker-based, heartbeats are monitored instead. Every hour the web service sends a heartbeat request to the licensing service providing the following information: the license id, session id, client ip, product type and version used, and the timestamp. If the license is valid and the response is 'OK', the web service continues to perform. Alternatively, if the response is 'FAIL', the Error message appears.

Heartbeats continue and as soon as the license becomes valid again, the operation of the web service restores automatically. In case there is no Internet connection when the request is sent, the result is 'TIMEOUT'.

Connect to Licensing Service via HTTP Proxy

If you host the SDK in an isolated private environment, you can specify an HTTP proxy via the HTTPS_PROXY env variable. The proxy will be used by the web service to connect to the licensing service.


Do not specify any protocol prefix in the proxy URL. Instead of HTTPS_PROXY=http(s)://host:port use HTTPS_PROXY=host:port


If you use your own TSL certs, place them in the /etc/ssl/certs folder in Linux and docker envs.


The recommended machine settings are: 1CPU and 2Gb RAM per worker.


For using the docker or Linux instances, you will need an online license. Internet connection is a mandatory requirement for an online license, thus the instance with pre-installed service must have internet access at least to the URL.


The version A.B.C.D is composed of:

  • A.B for the Regula SDK version
  • C for the document database version
  • D for the web service wrapper version

For example, a version 5.2.103350.140 should be interpreted as follows:

  • 5.2 is the Regula SDK version
  • 103350 is the current document database version
  • 140 is the web service wrapper version