Getting Started

This guide will help you get the most of the Mindee Java client library to easily extract data from your documents.

📘

Info

The library is written and compiled with Java 8. This guide assumes you have a compatible JVM language installed

Installation

Prerequisites

You'll need Apache Maven downloaded and installed

Maven

The easiest way to use the Mindee client library for your project is by adding the maven dependency in your projects POM:

<dependencies>
    ...
    <dependency>
      <artifactId>mindee-api-java</artifactId>
      <groupId>com.mindee.sdk</groupId>
      <version>${mindee.sdk.version}</version>
    </dependency>
</dependency>
<properties>
    ...
    <mindee.sdk.version>1.0.0</mindee.sdk.version>
</properties>

For the latest version of the Library please refer to our maven central repository

Development Installation

If you'll be modifying the source code, you'll need to follow these steps to get started.

  1. First clone the repo.
git clone [email protected]:mindee/mindee-api-java.git
  1. Navigate to the cloned directory and install all required libraries.
mvn clean install 

Updating the Library

When starting out it is recommended that you use the latest release version of the library from our maven central repository. Future updates can be made using the maven versions plugin.

mvn versions:use-next-releases -Dincludes=com.mindee.sdk:mindee-api-java

Usage

Using Mindee's APIs can be broken down into the following steps:

  1. Initialize a Client
  2. Load a file
  3. Send the file to Mindee's API
  4. Retrieve the response
  5. Process the response in some way

Let's take a deep dive into how this works.

Initializing the Client

The com.mindee.documentparser.Client class centralizes document configurations into a single class.

The Client requires your API key.

You can either pass these directly to the constructor or through environment variables.

Pass the API key directly

// Init a new client and passing the key directly
Client client = new Client("<your mindee api key>");

Set the API key in the environment

API keys can be set as environment variables.

The following environment variable will set the global API key:

MINDEE_API_KEY="my-api-key"

Then in your code:

// Init a new client without an API key
Client client = new Client();

Loading a Document File

Before being able to send a document to the API, it must first be loaded.

You don't need to worry about different MIME types, the library will take care of handling
all supported types automatically.

Once a document is loaded, interacting with it is done in exactly the same way, regardless
of how it was loaded.

There are a few different ways of loading a document file, depending on your use case:

The Client class provides overloaded loadDocument methods for these three input types. The loadDocument method returns an object of the DocumentClient class which can be used for further interactions with the API.

File Object

Load a java.io.File object. When using this option you do not need to pass in a file name - the API uses the file.getName() method to get the file name.

DocumentClient documentClient = client.loadDocument(
    new File("path/to/document/document.pdf"));

Base64

Load file contents from a base64-encoded string.

Note: The filename of the encoded file is required when calling the method.

String b64String = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLD....";
DocumentClient documentClient = client.loadDocument(b64String,"document.pdf");

Bytes

Load file contents from a byte array.

Note: The original filename of the encoded file is required when calling the method.

// Get Byte Array from a File, Multipart File, Input Stream, or as a method parameter
byte[] fileAsBytes = ....;
DocumentClient documentClient = client.loadDocument(fileAsBytes,"document.pdf");

Parsing a Document

Once a document has been loaded to the Client, it is available for parsing. The DocumentClient has multiple overloaded parse methods available for parsing the documents. The parse method needs to know the type of document - Invoice, Receipt, Passport, or FinancialDocument (either an Invoice or a Receipt) that is being parsed.

This can be done by implicitly by calling the parse(Class<T> type) method with the expected response type from the parse method (InvoiceResponse, ReceiptResponse, PassportResponse, FinancialDocumentResponse) and the argument or by explicitly passing in ParseParameters object to the parse(Class<T> type, ParseParameters params) method.
Each document type available in the library has its corresponding Response class.
This is detailed in each document-specific guide.

If you need some custom processing to be done on the response objects before being returned, you have the option of using other overloaded parse methods that allow a higher order Function<T,T> postProcessor to be passed as arguments. The postProcessor is applied to the response from the API before the Response object is returned to the caller.

Invoice, Receipt, Passport, FinancialDocument

Simply setting the correct class is enough:

// After the document has been loaded
ReceiptResponse receiptResponse = documentClient.parse(ReceiptResponse.class);

This code snippet calls the Mindee Receipts API and returns an object of the ReceiptResponse class. Similarly the following code snippet calls the Mindee Invoice API and returns an object of the InvoiceAPI class.

// After the document has been loaded
InvoiceResponse invoiceResponse = documentClient.parse(InvoiceResponse.class);

For more finer grained control over parsing the documents you may call the parse method wit ParseParameters set

// After the document has been loaded
ReceiptResponse receiptResponse = documentClient.parse(ReceiptResponse.class,
    ParseParameters.builder()
    .documentType("receipt")
    .accountName("mindee") // This is optional for receipt, invoice, financial_doc, and passport
    .cutMode(1) // Only used for pdf documents, defaulted to 1. [1,2,3]
    .includeWords(Boolean.FALSE) // defaulted to false
    .build());

Custom Documents

Not officially supported yet for the java helper library.

Processing the Response

The Response objects all have the following:

Document Level Prediction

The Response object for each document type has an attribute that represents data extracted from the entire document. It's possible to have the same field in various pages, but at the document level only the highest confidence field data will be shown (this is all done automatically at the API level).

The following table maps the document level attribute for different document types.

Document TypeResponse ClassDocument Level Prediction Attribute
InvoiceInvoiceResponse.classinvoice
ReceiptReceiptResponse.classreceipt
PassportPassportResponse.classpassport
Financial DocumentFinancialDocumentResponse.classfinancialDocument
InvoiceResponse invoiceResponse = documentClient.parse(InvoiceResponse.class);
// print the complete object
logger.info(invoiceResponse)

// print the document-level info
logger.info(invoiceResponse.getInvoice());

// print a summary of the document level
logger.info(invoiceResponse.documentSummary())

Each class will have its own specific attributes, which correspond to the various fields extracted from the document.

The various attributes are detailed in these document-specific guides:

Page Level Prediction

The Response object for each document types has a List of page level data. Each element in this list represents the data extracted for that particular page. the order of elements matches the order of pages in the document.

The following table maps the page level lists for different document types.

Document TypeResponse ClassPage Level Predictions
InvoiceInvoiceResponse.classinvoices
ReceiptReceiptResponse.classreceipts
PassportPassportResponse.classpassports
Financial DocumentFinancialDocumentResponse.classfinancialDocuments

All response objects have these lists, regardless of the number of pages.
Single page documents will have a single entry.

invoiceResponse.getInvoices()
    .forEach(System.out::println);

Raw HTTP Response

The rawResponse attribute contains the full Mindee API HTTP response object in a java.util.Map format.
It can be useful for debugging.

logger.info(invoiceResponse.getRawResponse());

 

Questions?
Slack Logo IconSlack Logo Icon  Join our Slack


Did this page help you?