# Tutorial: Intelligent Document Recognizer

This page describes the steps necessary to recognize and convert PDF, JPEG, PNG or TIFF purchase invoices to an e-invoice with the Intelligent Document Recognizer (IDR), using the RecognizePurchaseInvoice endpoint. The tutorial also applies to sales invoices. The only difference is the use of corresponding SalesInvoice endpoints instead.

# Set up hooks

To start recognizing purchase invoices you first need to subscribe to the "RecognizePurchaseInvoice" topic via the Subscribe endpoint. More information about hooks can be found here.

The hook's action consists of two parts: the IDR mode you use and party details.

# IDR mode

The IDR mode is an optional conversion mode to specify the quality of conversion needed. The default mode is IDR-Default which will do a standard quality conversion. If you need higher-quality conversions or enable low-quality conversions you can use this flag. Possible conversion modes are:

  • IDR-Default : Default mode which uses standard quality conversions. Not necessary to be submitted in the hook's action.
  • IDR-HQ : Use high quality conversions which will use a higher confidence level to PASS and higher priority in the processing queue.

# Features

The IDR offers some additional features to enhance the way documents are converted. To enable these features, add them to the features query parameter in the hook's action. The features are:

  • PO: Extract a mandatory order reference.
  • G-Account: Create a SI-UBL 2.0 G-Account extension document.

# Hook action

The action should be formatted like: "action":"recognize://idr?mode={IdrMode}&features=PO,G-Account&data={CompanyDetails}". The company details should contain a list of names you might use on your invoices, all identifiers your company uses (e.g. KVK and OINO), your emailaddress and the addresses that can be found on your invoices. These details should be combined into one JSON object. For example:

    "names": [
    "identifiers": [
    "emailAddress": "techsupport@econnect.eu",
    "addresses": [
            "street": "Pelmolenlaan 16A",
            "postalZone": "3447GW",
            "city": "Woerden",
            "country": "NL"

These company details must be encoded as a base64 string and should be added to the data parameter in the hook's action. The hook than looks like this:

    "id": "1",
    "name": "idr hook",
    "topics": [     
    "isActive": true,
    "createdOn": "2021-01-26T20:40:31"

# Callback hook

To know when the recognition process is finished a second hook is required that listens to the "PurchaseInvoiceRecognized" and "PurchaseInvoiceRecognizedError" topics. This can either be a mail hook, or a webhook. For example:

    "id": "2",
    "action": "mailto:techsupport@econnect.eu",
    "name": "mail hook",
    "topics": [
    "isActive": true

# Upload document

After the hooks are set up PDF purchase invoices can be uploaded to be recognized. Use the POST /api/v1/{partyId}/purchaseInvoice/recognize endpoint to upload documents. The {partyId} should be the receiver's partyId. The document to recognize should be added to the request body as a binary file with content type multipart/form-data.

The response will contain a documentId, which which will be used as reference in the upcoming events to your subscriber hooks.

# Download the result

When the recognition process is complete and the document is converted, a "PurchaseInvoiceRecognized" hook will trigger. In this hook you'll find the same documentId we saw earlier as the response of the upload request. With this documentId you can call GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download to download the UBL invoice. The partyId should be the same you used to upload the PDF.

When things go wrong the hook will have the "PurchaseInvoiceRecognizedError" topic instead. The hook's message will contain more information about what went wrong.

© 2022 eConnect International B.V.