README.md

Mindee API Helper Library for Python

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

Quick Start

Here's the TL;DR of getting started.

First, get an API Key

Then, install this library:

pip install mindee

Finally, Python away!

Loading a File and Parsing It

Global Documents

from mindee import Client, product

# Init a new client
mindee_client = Client(api_key="my-api-key")

# Load a file from disk
input_doc = mindee_client.source_from_path("/path/to/the/file.ext")

# Parse the document as an invoice by passing the appropriate type
result = mindee_client.parse(product.InvoiceV4, input_doc)

# Print a brief summary of the parsed data
print(result.document)

Note: Files can also be loaded from:

A python BinaryIO compatible file:

input_doc = mindee_client.source_from_file(my_file)

A URL (HTTPS only):

input_doc = mindee_client.source_from_url("https://files.readme.io/a74eaa5-c8e283b-sample_invoice.jpeg")

A base64-encoded string, making sure to specify the extension of the file name:

input_doc = mindee_client.source_from_b64string(my_input_string, "my-file-name.ext")

Raw bytes, making sure to specify the extension of the file name:

input_doc = mindee_client.source_from_bytes(my_raw_bytes_sequence, "my-file-name.ext")

Region-Specific Documents

from mindee import Client, product

# Init a new client
mindee_client = Client(api_key="my-api-key")

# Load a file from disk
input_doc = mindee_client.source_from_path("/path/to/the/file.ext")

# Parse the document as a USA bank check by passing the appropriate type
result = mindee_client.parse(product.us.BankCheckV1, input_doc)

# Print a brief summary of the parsed data
print(result.document)

Custom Documents (docTI & Custom APIs)

from mindee import Client, product

# Init a new client
mindee_client = Client(api_key="my-api-key")

# Add your custom endpoint (document)
my_endpoint = mindee_client.create_endpoint(
    account_name="my-account",
    endpoint_name="my-endpoint",
)

# Load a file from disk
input_doc = mindee_client.source_from_path("/path/to/the/file.ext")

# Parse the file.
# The endpoint must be specified since it cannot be determined from the class.
result = mindee_client.enqueue_and_parse(
    product.GeneratedV1,
    input_doc,
    endpoint=my_endpoint
)

# Print a brief summary of the parsed data
print(result.document)

# Iterate over all the fields in the document
for field_name, field_values in result.document.fields.items():
    print(field_name, "=", field_values)

Enqueue and Parse a Webhook Response

This is an optional way of handling asynchronous APIs.

Additional Options

Options to pass when sending a file.

from mindee import Client, product
from mindee.client import LocalResponse

# Init a new client
mindee_client = Client()

# Load a file from disk
input_source = mindee_client.source_from_path("/path/to/the/file.ext")

# Parse the file

enqueue_response = mindee_client.enqueue(
    product.InternationalIdV2,
    input_source,
)

# You can keep track of the job's ID for traceability concerns.
job_id = enqueue_response.job.id


# 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.

local_response = LocalResponse(request.body())

# You can also load the json from a local path.
# local_response = LocalResponse("path/to/my/file.ext")

# Optional: verify the HMAC signature
if not local_response.is_valid_hmac_signature(my_secret_key, "some signature"):
    raise Error("Invalid HMAC signature!")

# Deserialize the response

result = mindee_client.load_prediction(
    product.InternationalIdV2,
    local_response
)

# Print a full summary of the parsed data in RST format
print(result.document)

Page Options

Allows sending only certain pages in a PDF.

In this example we only send the first, penultimate and last pages:

from mindee import product, PageOptions

result = mindee_client.parse(
    product.InvoiceV4,
    input_source,
    page_options=PageOptions(
        page_indexes=[0, -2, -1],
        operation=PageOptions.KEEP_ONLY,
        on_min_pages=2
    )
)

Further Reading

Complete details on the working of the library are available in the following guides:

• Getting started
• Python Command Line Interface (CLI)
• Python Generated
• Python Custom APIs (Deprecated - API Builder)
• Python Invoice OCR
• Python International Id OCR
• Python Resume OCR
• Python Receipt OCR
• Python Financial Document OCR
• Python Passport OCR
• Python Proof of Address OCR
• Python EU License Plate OCR
• Python US Driver License OCR
• Python FR Bank Account Detail OCR
• Python FR Carte Grise OCR
• Python FR Health Card OCR
• Python FR ID Card OCR
• Python FR Petrol Receipts OCR
• Python US Bank Check OCR
• Python US W9 OCR
• Python US Driver License OCR
• Python Barcode Reader API
• Python Cropper API
• Python Invoice Splitter API
• Python Multi Receipts Detector API

You can view the source code on GitHub.

You can also take a look at the Reference Documentation.

License

Copyright © Mindee

Available as open source under the terms of the MIT License.

Questions?

Join our Slack