> For the complete documentation index, see [llms.txt](https://docs.mindee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mindee.com/v1/integration/java-ocr-sdk.md).

# Java OCR SDK

## Mindee API Helper Library for Java

Quickly and easily connect to Mindee's API services using Java.

### Quick Start

Here's the TL;DR of getting started.

First, get an [API Key](/v1/get-started/create-api-key.md)

Include the following maven dependency in your project to use the helper library:

```xml
<dependency>
  <artifactId>mindee-api-java</artifactId>
  <groupId>com.mindee.sdk</groupId>
  <version>${mindee.sdk.version}</version>
</dependency>
```

Where `${mindee.sdk.version}` is the version shown here:

![Version](https://img.shields.io/maven-central/v/com.mindee.sdk/mindee-api-java)

### Loading a File and Parsing It

The `MindeeClient` class is the entry point for most of the helper library features.

### Synchronously Parsing a File

This is the easiest and fastest way to integrate into the Mindee API.

However, not all products are available in synchronous mode.

#### Global Documents

These classes are available in the `com.mindee.product` package:

```java
import com.mindee.MindeeClient;
import com.mindee.input.LocalInputSource;
import com.mindee.parsing.common.PredictResponse;
import com.mindee.product.invoice.InvoiceV4;
import java.io.File;
import java.io.IOException;

public class SimpleMindeeClient {
  public static void main(String[] args) throws IOException {

    // Init a new client
    MindeeClient mindeeClient = new MindeeClient("my-api-key");

    // Load a file from disk
    LocalInputSource localInputSource = new LocalInputSource(
        "/path/to/the/file.ext"
    );
    // Parse the file
    Document<InvoiceV4> response = mindeeClient.parse(
        InvoiceV4.class,
        localInputSource
    );
    // Print a summary of the parsed data
    System.out.println(response.getDocument().toString());
  }
}
```

**Note for Region-Specific Documents:**

Each region will have its own package within the general `com.mindee.product` package.

For example USA-specific classes will be in the `com.mindee.product.us` package:

```java
import com.mindee.product.us.bankcheck.BankCheckV1;
```

#### Custom Documents (API Builder)

```java
import com.mindee.MindeeClient;
import com.mindee.input.LocalInputSource;
import com.mindee.parsing.common.PredictResponse;
import com.mindee.product.custom.CustomV1;
import com.mindee.http.Endpoint;
import java.io.File;
import java.io.IOException;

public class SimpleMindeeClient {
  public static void main(String[] args) throws IOException {

    // Init a new client
    MindeeClient mindeeClient = new MindeeClient("my-api-key");
    
    // Init the endpoint for the custom document
    Endpoint endpoint = new Endpoint("my-endpoint", "my-account");

    // Load a file from disk
    LocalInputSource localInputSource = new LocalInputSource(
        "src/main/resources/invoices/invoice1.pdf"
    );
    // Parse the file
    Document<CustomV1> customDocument = mindeeClient.parse(
        localInputSource,
        endpoint
    );
  }
}
```

### Synchronously Parsing a File

This allows for easier handling of bursts of documents sent.

Some products are only available asynchronously, check the example code\
directly on the Mindee platform.

#### Enqueue and Parse a File

The client library will take care of handling the polling requests for you.

This is the easiest way to get started.

```java
import com.mindee.MindeeClient;
import com.mindee.input.LocalInputSource;
import com.mindee.parsing.common.AsyncPredictResponse;
import com.mindee.product.internationalid.InternationalIdV2;
import java.io.File;
import java.io.IOException;

public class SimpleMindeeClient {

  public static void main(String[] args) throws IOException, InterruptedException {
    String apiKey = "my-api-key";
    String filePath = "/path/to/the/file.ext";

    // Init a new client
    MindeeClient mindeeClient = new MindeeClient(apiKey);

    // Load a file from disk
    LocalInputSource inputSource = new LocalInputSource(new File(filePath));

    // Parse the file asynchronously
    AsyncPredictResponse<InternationalIdV2> response = mindeeClient.enqueueAndParse(
        InternationalIdV2.class,
        inputSource
    );

    // Print a summary of the response
    System.out.println(response.toString());
  }
}
```

#### Enqueue and Parse a Webhook Response

This is an optional way of handling asynchronous APIs.

```java
import com.mindee.MindeeClient;
import com.mindee.input.LocalInputSource;
import com.mindee.input.LocalResponse;
import com.mindee.input.WebhookSource;
import com.mindee.product.internationalid.InternationalIdV2;
import java.io.IOException;

public class SimpleMindeeClient {
  public static void main(String[] args) throws IOException {

    // Init a new client
    MindeeClient mindeeClient = new MindeeClient("my-api-key");

    // Load a file from disk
    LocalInputSource localInputSource = new LocalInputSource(
      "/path/to/the/file.ext"
    );
    // Enqueue the file
    String jobId = client.enqueue(InternationalIdV2.class, localInputSource)
      .getJob().getId();

    // Load the JSON string sent by the Mindee webhook POST callback.
    //
    // Reading the callback data will vary greatly depending on your HTTP server.
    // This is therefore beyond the scope of this example.
    String jsonData = myHttpServer.getPostBodyAsString();
    LocalResponse localResponse = new LocalResponse(jsonData);

    // Verify the HMAC signature.
    // You'll need to get the "X-Mindee-Hmac-Signature" custom HTTP header.
    String hmacSignature = myHttpServer.getHeader("X-Mindee-Hmac-Signature");
    boolean isValid = localResponse.isValidHmacSignature(
        "obviously-fake-secret-key", hmacSignature
    );
    if (!isValid) {
      throw new MyException("Bad HMAC signature! Is someone trying to do evil?");
    }

    // You can also use a File object as the input.
    //LocalResponse localResponse = new LocalResponse(new File("/path/to/file.json"));

    // Deserialize the response into Java objects
    AsyncPredictResponse<InternationalIdV2> response = mindeeClient.loadPrediction(
      InternationalIdV2.class,
      localResponse
    );

    // Print a summary of the parsed data
    System.out.println(response.getDocument().toString());
  }
}
```

### Further Reading

You can view the source code on [GitHub](https://github.com/mindee/mindee-api-java).

You can also take a look at the [**Reference Documentation**](https://mindee.github.io/mindee-api-java/).

### License

Copyright © Mindee

Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mindee.com/v1/integration/java-ocr-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.