The Intelligent Document Recognizer (IDR) automatically converts PDF invoices into structured e-invoices. Through the PSB API you control the IDR with recognize hooks, which let you configure the recognition process: quality level, priority, extraction features and party details. This article describes how to use the IDR via the API.

The IDR operates as a hook in the PSB hook system. You register a recognize hook that listens on a topic (e.g. InvoiceReceived). When a PDF document arrives via that topic, the PSB automatically forwards it to the IDR for recognition. After processing, the IDR publishes the result on a callback topic.

The hook action for IDR has the following format:

recognize://idr?quality={quality}&priority={priority}&features={features}&data={base64-data}

The quality level determines how strictly the IDR evaluates the recognition result:

The priority determines the processing order in the IDR queue:

Features activate additional extraction capabilities. You can combine multiple features (comma-separated):

Example: features=iban,g-account,order-reference

The data field contains base64-encoded JSON with details of the receiving organisation. The IDR uses this information to enrich and validate the recognition result. The JSON contains names, identifiers, email address and addresses of the organisation.

Example of the JSON before base64 encoding:

{
  "names": ["Company Name B.V."],
  "identifiers": [
    { "type": "KVK", "value": "12345678" }
  ],
  "email": "invoices@company.nl",
  "addresses": [
    {
      "street": "Example Street 1",
      "postcode": "1234 AB",
      "city": "Utrecht",
      "country": "NL"
    }
  ]
}

During PDF conversion, the name of the receiving organization in the XML does not come from the text on the PDF. That name comes from the conversion request: the platform organization name (from the trade register) or, when using this API, the names field in the data/party details described above. The IDR uses that for enrichment and validation and puts the result in AccountingCustomerParty. A spelling difference (for example an abbreviation like "Gebr" versus "Gebrs") therefore sits in the submitted party data, not in an OCR error on the buyer party.

VAL-003: validation message stating that the party name on the document differs from the name in the conversion request. This is not an OCR error on the buyer party; the comparison concerns the document name versus the request name.

Changing the spelling: there is no route via XML or a free-text field. The correct route: change the name first at the trade register (statutory name or trade name), then use Refresh details on the platform (select the correct name from the dropdown if there are multiple trade names), and when using this API also update the names field in the conversion request. See Changing your organization's address details, name or logo for the full procedure.

A complete recognize hook looks like this:

{
  "action": "recognize://idr?quality=default&priority=medium&features=iban,order-reference&data={base64-encoded-party-details}",
  "topics": ["InvoiceReceived"]
}

Register this hook via the Hook endpoint:

POST /api/v1/hook

Or include the hook directly in an Enrollment request.

After processing, the IDR publishes the result on one of the following topics:

Set up a webhook or mail hook on these topics to receive the result. For example:

{
  "action": "https://api.company.nl/idr/callback",
  "topics": ["PurchaseInvoiceRecognized", "PurchaseInvoiceRecognizedError"]
}

The maximum file size for IDR uploads is 15 MB. Files larger than 15 MB return an HTTP 413 (Content Too Large) error code.

The IDR supports the following file types:

Other file types (Word, Excel, HTML) are not supported and result in an IDR422 Invalid PDF Content error. Password-protected or DRM-secured PDFs produce a similar error message.

The complete IDR process via the API follows four steps:

1. A PDF document arrives via the PSB (upload or receipt via Peppol/SFTP/email)
2. The recognize hook sends the document to the IDR with the configured parameters
3. The IDR processes the document and publishes the result on the appropriate callback topic
4. You receive the recognised document via your webhook or retrieve it via the PurchaseInvoice endpoints

Want to learn more about the PSB hook architecture? Read the article on configuring and securing webhooks.