Response Processing

Reference documentation on processing responses using the Mindee client libraries.

This is reference documentation.

Code samples shown are only examples, and will not work as-is. You'll need to copy-paste and modify according to your requirements.

Looking full code samples?

You can also use the "Ask" button at the top of any page in the documentation.

Requirements

You'll need to have already sent a file or URL as described in the Send a File or URL section.

Overview

Depending on how you've sent the file, there are two ways of obtaining the result.

If you've sent via polling (or polling and webhook) you'll get the response directly in your method call.

If you've sent only via webhook, you'll receive the response on your Web server.

Here we'll go over how you can best process the results.

Load From Webhook

If you're using the webhook pattern, you'll need to use the payload sent to your Web server.

Reading the callback data will vary greatly depending on your HTTP server. This is therefore beyond the scope of this example.

Regardless of how you access the JSON payload sent by the Mindee servers, loading this data is done by using a LocalResponse class.

Once it is loaded you can access the data in exactly the same way as a polling response.

To verify the HMAC signature, you'll need the Signing Secret from the webhook:

Remember to use the appropriate Product/Model class, examples use ExtractionResponse.

Python

Assuming you're able to get the raw HTTP request via the variable request .

from mindee.input import LocalResponse
from mindee.v2 import ExtractionResponse

# Load the JSON string sent by the Mindee webhook POST callback.
local_response = LocalResponse(request.body())

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

# Optionally: verify the HMAC signature
# You'll need to get the "X-Signature" custom HTTP header.
hmac_signature = request.headers.get("X-Signature")
is_valid = local_response.is_valid_hmac_signature(
    "obviously-fake-secret-key", hmac_signature
)
if not is_valid:
    raise Error("Bad HMAC signature! Is someone trying to do evil?")

# Deserialize the response into objects
response = local_response.deserialize_response(ExtractionResponse)

Node.js

Assuming you're able to get the raw HTTP request via the variable request .

async handleMindeeResponse(data, hmacSignature) {
  const localResponse = new mindee.LocalResponse(data);
  await localResponse.init();

  const isValid = localResponse.isValidHmacSignature(
      "obviously-fake-secret-key", hmacSignature
    );
  if (!isValid) {
    throw Error("Bad HMAC signature! Is someone trying to do evil?");
  }
  const response = await localResponse.deserializeResponse(
    mindee.ExtractionResponse
  );
}

// Load the JSON string sent by the Mindee webhook POST callback.
// Will vary depending on your implementation.
async handleMindeePost(request, response) {
  let body = "";
  request.on("data", function (data) {
    body += data;
  });
  req.on("end", function () {
    // Optionally: verify the HMAC signature
    // You'll need to get the "X-Signature" custom HTTP header.
    const hmacSignature = request.headers.get("X-Signature");
    
    // validate using the entire body of the response with the signature header
    await handleMindeeResponse(body, hmacSignature);
  });
}

Ruby

Assuming you're able to get the raw HTTP request via the variable request .

require 'mindee'

# Load the JSON string sent by the Mindee webhook POST callback.
local_response = Mindee::Input::LocalResponse.new(request.body.to_s)

# You can also use a File object as the input.
# FILE_PATH = File.join('path', 'to', 'file.json').freeze
# local_response = Mindee::Input::LocalResponse.new(FILE_PATH);

# Optional: verify the HMAC signature.
unless local_response.valid_hmac_signature?(my_secret_key, 'dummy signature')
  raise "Invalid HMAC signature!"
end

# Deserialize the response:
response = local_response.deserialize_response(
  Mindee::V2::Product::Extraction::ExtractionResponse
)

# Print a summary of the parsed data in RST format
puts response

PHP

Assuming you're able to get the raw HTTP request via the variable $requestBody .

<?php

use Mindee\Input\LocalResponse;
use Mindee\Error\MindeeException;
use Mindee\V2\Product\Extraction\ExtractionResponse;

// Load the JSON string sent by the Mindee webhook POST callback.
$localResponse = new LocalResponse($requestBody);

// Or load from a file path:
// $localResponse = new LocalResponse($filePath);

// Optional: verify the HMAC signature.
if (!$localResponse->isValidHmacSignature($mySecretKey, 'dummy signature')){
    throw new MindeeException("Invalid HMAC signature!");
}

// Deserialize the response:
$response = $localResponse->deserializeResponse(ExtractionResponse::class);

// Print a summary of the parsed data in RST format
echo $response->inference;

Java

Assuming you have a Web server instance myHttpServer .

import com.mindee.v2.parsing.LocalResponse;
import com.mindee.v2.product.extraction.ExtractionResponse;

// Load the JSON string sent by the Mindee webhook POST callback.
String jsonData = myHttpServer.getPostBodyAsString();
LocalResponse localResponse = new LocalResponse(jsonData);

// Verify the HMAC signature.
// You'll need to get the "X-Signature" custom HTTP header.
String hmacSignature = myHttpServer.getHeader("X-Signature");
boolean isValid = localResponse.isValidHmacSignature(
    "obviously-fake-secret-key", hmacSignature
);
if (!isValid) {
    throw new Exception("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 objects
ExtractionResponse response = localResponse.deserializeResponse(
    ExtractionResponse.class
);

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

.NET

Assuming you're able to get the raw HTTP request via the variable request .

using Mindee.V2.Parsing;
using Mindee.V2.Product.Extraction;

public void HandleMindeeCallback(HttpRequest request)
{
    LocalResponse localResponse;

    using (var reader = new StreamReader(request.Body))
    {
        localResponse = new LocalResponse(reader.ReadToEnd());
    }
    
    // Verify the HMAC signature.
    // You'll need to get the "X-Signature" custom HTTP header.
    string hmacSignature = request.Headers.get("X-Signature");
    bool isValid = localResponse.IsValidHmacSignature(
         "obviously-fake-secret-key", hmacSignature);
    if (!isValid)
        throw new Exception("Bad HMAC signature! Is someone trying to do evil?");

    // Deserialize the response into objects
    var response = localResponse.DeserializeResponse<ExtractionResponse>();
    
    // Print a summary of the parsed data
    System.Console.WriteLine(response.Inference);
}

The Response Object

This is the base object of the response.

It doesn't do much on its own except allow you to access the Inference object.

Remember to use the appropriate Product/Model class, examples use ExtractionResponse.

The response object can be used to retrieve the raw response from the server, as a JSON string:

Python

from mindee.v2 import ExtractionResponse

def handle_response(response: ExtractionResponse):
    response_json = response.raw_http

Node.js

handleResponse(response) {
  const responseJson = response.getRawHttp();
}

PHP

use Mindee\V2\Product\Extraction\ExtractionResponse;

public function handleResponse(ExtractionResponse $response)
{
    $responseJson = $response->getRawHttp();
}

Ruby

require 'mindee'

def handle_response(response)
  response_json = response.raw_http
end

Java

import com.mindee.v2.product.extraction.ExtractionResponse;

public void handleResponse(ExtractionResponse response) {
    String responseJSON = response.getRawResponse();
}

.NET

using Mindee.V2.Product.Extraction;

public void HandleResponse(ExtractionResponse response)
{
    string responseJson = response.RawResponse;
}

The Inference Object

This is the top-level object in the response.

It contains the following attributes:

• id UUID of the inference
• model Model used for the inference
• file Metadata concerning the file used for the inference
• result Result of inference processing, the most important portion of the response.

  • Fields: For handling the extracted fields, see the Extraction Result section.
  • Raw Text: For using the extracted text, see the Response Processing section.

File Metadata

You can access various metadata concerning the file sent for processing:

• name name of the file as sent in the initial request.
• alias alias as sent in the initial request.
• page_count number of pages in the file as determined during processing.
• mime_type MIME / media type of the file as determined during processing.

Access using the response object from either a polling response or a webhook payload.

Python

from mindee.v2 import ExtractionResponse

def handle_response(response: ExtractionResponse):
    inference_file = response.inference.file

    # various attributes are available, such as:
    filename: str = inference_file.name
    page_count: int = file.page_count
    mime_type: str = file.mine_type

Node.js

handleResponse(response) {
  const file = response.inference.file;

  // various attributes are available, such as:
  const filename = file.name;
  const pageCount = file.pageCount;
  const mimeType = file.mimeType;
}

PHP

use Mindee\V2\Product\Extraction\ExtractionResponse;

public function handleResponse(ExtractionResponse $response)
{
    $file = $response->inference->file;

    // various attributes are available, such as:
    $filename = $file->name;
    $pageCount = $file->pageCount;
    $mimeType = $file->mimeType;
}

Ruby

require 'mindee'

def handle_response(response)
  file = response.inference.file

  # various attributes are available, such as:
  filename = inference_file.name
  page_count = file.page_count
  mime_type = file.mime_type
end

Java

import com.mindee.v2.product.extraction.ExtractionResponse;

public void handleResponse(ExtractionResponse response) {
    var file = response.inference.getFile();

    // various attributes are available, such as:
    String filename = file.getName();
    int pageCount = file.getPageCount();
    String mimeType = file.getMimeType();
}

.NET

using Mindee.V2.Product.Extraction;

public void HandleResponse(ExtractionResponse response)
{
    var file = response.Inference.File;

    // various attributes are available, such as:
    string filename = file.Name;
    int pageCount = file.PageCount;
    string mimeType = file.MimeType;
}