Overview

Learn API

Send corrected results back to bluDELTA Document API v2. bluDELTA uses them to recognize your next documents better.

At a glance

Before you start

Activation. Learning must be activated for each customer account. Please contact your account manager and bludelta-support@blumatix.com before the first upload. Without activation, bluDELTA stores your uploads but recognition does not change.

One API key per end customer. bluDELTA separates learning by API key and API identifier. Use a separate API key for each end customer, and always the same API identifier for the same end customer. Software vendors and partners: please request a separate API key for each end customer from your account manager.

Important: Data separation is your responsibility

Never send documents of different end customers with the same API key and API identifier. The corrections of one customer would change the results of the other customers. This mixes data of different companies and can cause a security incident.

The partner or customer who sends the data to the Learn API is responsible for a correct upload: the right documents with the right API key and API identifier.

How it works

1. Recognize. Send the document to the Document API. You get the result as bluDOC JSON.

2. Check. Your user checks the result in your system and corrects wrong values.

3. Send back. Mark every checked value with Confidence 1.0. Put the document and the bluDOC into a ZIP file and upload it.

4. Benefit. bluDELTA learns where and in which format each value appears on this layout (for example, the invoice template of a supplier). The next documents with the same or a very similar layout are recognized better.

bluDELTA learns the layout, not the values. A correction does not help for documents with a different layout.

Timing. A correction is visible about 30 minutes after the upload. We are working on reducing this time.

Prepare the bluDOC

Start with the result from the Document API. Change only what your user has checked.

Changed or added values: Text and Location

Never keep the old Text or Location with a new Value. They belong to the old, wrong value.

If Value, Text and Location do not match, bluDELTA always uses Value. It ignores a Text or Location that does not fit the value.

Rules:

• Only Confidence 1.0 counts. bluDELTA ignores all other values. The Document API always returns 0.85, so unchanged results have no effect.

• The value counts. Text and Location are optional. You can send changed or added values without them.

• Empty with 1.0 means “not on the document”. Use it only in this case. Otherwise bluDELTA learns to leave this field empty.

• Send the complete result. Send each document once, after your user has finished checking it. A later upload for the same document replaces the earlier one. It does not add to it.

Example of a changed value without position:

{
  "Label": "Invoice.Date",
  "Value": "2025-03-12",
  "Text": null,
  "Confidence": 1.0,
  "Location": null
}

bluDOC version. Send the bluDOC in the version that the Document API returned (property BluDoc.Version, currently 1.5.0). Schemas for all versions: github.com/blumatix/BluDoc/schema. Please validate your bluDOC against the schema before upload. The upload does not check the content of the bluDOC, and you do not get an error message later.

Build the ZIP file

• For each document, add the document file and its bluDOC with the same file name, for example:

  • Musterrechnung.pdf

  • Musterrechnung.json

• Link to samples: https://github.com/blumatix/BluDoc/tree/main/samples/invoice. The samples show a recognition result with Confidence 0.85. In your upload, set Confidence to 1.0 for every checked value.

• Supported document files: PDF, TIFF, JPG, PNG. Pure XML e-invoices are not used for learning.

• Send the document in the same form as you sent it to the Document API. If you use document splitting, send each split document as its own file with its own bluDOC.

• You can put several documents into one ZIP file. File names must be unique.

• Keep the ZIP file flat (no folders).

• Recommended size: up to 1,000 documents and less than 1 GB per ZIP file. Maximum: 2 GB.

Send the request

curl -X POST "https://learn.bludelta.ai/v1/Package" \
  -H "X-ApiKey: <your-api-key>" \
  -H "X-ApiIdentifier: <your-api-identifier>" \
  -F "Package=@corrections.zip;type=application/zip" \
  -F "Tags=my-erp-feedback"
 
using var form = new MultipartFormDataContent();
var zip = new ByteArrayContent(File.ReadAllBytes("corrections.zip"));
zip.Headers.ContentType = new MediaTypeHeaderValue("application/zip"); // required
form.Add(zip, "Package", "corrections.zip");
form.Add(new StringContent("my-erp-feedback"), "Tags");
 
client.DefaultRequestHeaders.Add("X-ApiKey", "<your-api-key>");
client.DefaultRequestHeaders.Add("X-ApiIdentifier", "<your-api-identifier>");
var response = await client.PostAsync("https://learn.bludelta.ai/v1/Package", form);

Response: 200 OK with {"packageId": "…"}. Please store the packageId. Our support needs it if you have questions about a package.

200 OK means that bluDELTA has received the package. bluDELTA processes the content later.

Test your integration

Use your test API key, the same one you use for the Document API. A correction uploaded with a test key only affects this test account. Your production customers do not see it.

To see the effect, wait about 30 minutes. Then recognize a document with the same layout again, with the same test key and API identifier.

Learning must also be activated for your test account. Please ask us before your first test.

Good practice

• Use the API key and API identifier that recognized the document. With another key or identifier, the correction goes to another account.

• Send only real documents that your customer processes with bluDELTA. Test documents, placeholders or incomplete corrections make results worse.

• The first correct document of a layout is the most important one. Quality is more important than quantity.

• Send packages one after another, not in parallel.

• Planning a large upload, for example older corrections? Please talk to us first.

Upload documents without bluDOC

You can also upload sample documents without results, for example for a new document type. In this case, set DocumentType (leave it empty for invoices). See the Online API Documentation for all values. These documents do not change recognition automatically. Our team uses them to improve bluDELTA. Please talk to your account manager first.

Manual upload

You can upload a package without code in the browser.

1. Go to https://learn.bludelta.ai/swagger/index.html. Under Package, open POST /v1/Package.

   

2. Click Try it out.

   

3. Enter your API key and your API identifier.

   

4. DocumentType: Leave it empty if your ZIP file contains bluDOC files or only invoices. For other documents without bluDOC, for example delivery notes, choose the type from the list. If a document type is missing, please contact your account manager.

   

5. Choose the ZIP file.

   

6. Optional: enter tags, separated by commas.

   

7. Click Execute.

   

8. If the upload works, you get 200 with the packageId. Please store it.

   

Checklist for go-live

• Each end customer has its own API key. Documents of different end customers are never sent with the same API key and API identifier.

• Learning is activated for every customer account (ask your account manager).

• Uploads use the same API key and API identifier as the recognition.

• Only values that a user has checked have Confidence 1.0.

• Changed values have no old Text or Location.

• Each document is sent once, with the complete checked result.

• bluDOC files are valid against the schema of their version.

• The packageId is stored.

• A test with the test key was successful.

Questions? Please contact your account manager or bludelta-support@blumatix.com.