Get Inference Result (Async)

This endpoint allows you to retrieve the result of a previously requested asynchronous inference. When an async inference request is initiated, the system returns a resource ID that can be used to track and later retrieve the results of that operation.

Request

GET  '/inference/service/:service_id:/predicted-documents/:document_id:'

The API requires making a GET request by specifying the service_id and the document_id as parameters as the examples below shows.

curl --location 'https://platform.mybiros.com/api/v1/inference/service/:service_id:/predicted-documents/:document_id:?include=ocr&include=service_fields&document_details=pages \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Accept: application/json'

Parameters

Header Parameters

x-api-key (required)

Type: string

A valid API key for the service.

Path Parameters

service_id (required)

Type: string

The service ID of the service that processed the document.

document_id (required)

Type: string

The resource ID of the document returned by the async inference request.

Query Parameters

include (optional)

Default: []
Type: array[string]
Allowed values: ocr | service_fields | validation_errors

Repeated query parameter that specifies additional elements to include in the response. Each value corresponds to a specific data element that the endpoint can optionally return.

The elements that can be included are:

ocr which will include in each document page the text detected in the page, with bounding boxes.
service_fields which will include in the result the fields supported by the service.
validation_errors, which, if specified, will trigger validation policies execution and include in each document page eventual violations.

The default behaviour is to not include any of the additional elements and if a field is not included than will be set to his empty value.

Note

For more information about the objects that can be included in the result with the include parameter, please refer to the API response schema

document_details (optional)

Default: pages
Type: string
Allowed values: pages | summary

This parameter determines the level of details of the result.

if pages is selected the result will contain extracted data for each page in a document_pages object
if summary ( Experimental ) is selected the result will contain a document level summary of the extracted data in a document_summary object.

Note

For more information about the document_pages and document_summary objects, please refer to the API response schema

Responses

The service response provides the necessary values to understand the processing status of the resource and revision status of the document.

Successful Responses

The request was successful, and a JSON response is returned.

Status	Message	Description	Reference
200	OK	the request has succeeded.	Success Response 200
202	Accepted	the request has succeeded but the resource is not ready yet.	Success Response 202

Status 200 - OK

JSON Response Example

With document_details=pagesWith document_details=summary

{
    "service": "<service-id>",
    "service_name": "Example Service",
    "service_fields": {
        "surname_1": {
            "tag_alias": "Surname",
              "tag_multiple_values": true
        },
        "name_1": {
            "tag_alias": "Name",
              "tag_multiple_values": true
        },
        "fiscal_code_1": {
            "tag_alias": "FiscalCode",
              "tag_multiple_values": false
        }
    },
    "current_date": "2024-04-26T11:21:58+00:00",
    "document": {
        "id": "<document-id>",
        "status": "ACTIVE",
        "revision_status": "pending",
         "original_name": "health_card.jpg",
        "content_type": "image/jpeg",
        "page_count": 1
    },
    "document_summary": {},
    "document_pages": [
        {
            "page_index": 0,
            "page_layout": {
                "height": 600,
                "width": 1000,
                "rotation_angle": 0
             },
            "ocr": [...],
            "entities_index": 3,
            "entities": {
                "surname_1": [
                    {
                        "id": 0,
                        "text": "VERDI",
                        "confidence": 99.43,
                        "bounding_boxes": [...]
                    }
                ],
                "name_1": [
                    {
                        "id": 1,
                        "text": "GIUSEPPE",
                        "confidence": 99.47,
                        "bounding_boxes": [...]
                    }
                ],
                "fiscal_code_1": {
                    "id": 2,
                    "text": "VRDGPP13R10B293P",
                    "confidence": 90.97,
                    "bounding_boxes": [...]
                }
            },
            "aggregated_entities": {},
            "policy_violations": [],
            "errors": []
        }
    ]
}

{
    "service": "<service-id>",
    "service_name": "Example Service",
    "service_fields": {
        "surname_1": {
            "tag_alias": "Surname",
              "tag_multiple_values": true
        },
        "name_1": {
            "tag_alias": "Name",
              "tag_multiple_values": true
        },
        "fiscal_code_1": {
            "tag_alias": "FiscalCode",
              "tag_multiple_values": false
        }
    },
    "current_date": "2024-04-26T11:21:58+00:00",
    "document": {
        "id": "<document-id>",
        "status": "ACTIVE",
        "revision_status": "pending",
         "original_name": "health_card.jpg",
        "content_type": "image/jpeg",
        "page_count": 1
    },
    "document_summary": {
        "entities": {
            "surname_1": [
                {
                    "text": "VERDI",
                    "confidence": 99.43
                }
            ],
            "name_1": [
                {
                    "text": "GIUSEPPE",
                    "confidence": 99.47
                }
            ],
            "fiscal_code_1": {
                "text": "VRDGPP13R10B293P",
                "confidence": 90.97
            }
        },
        "aggregated_entities": {},
    },
    "document_pages": []
}

Schema: Document Response

Key	Type	Description
service	string	the service identifier
service_name	string	the service name
service_fields	string	a JSON object containing info about service fields
current_date	object	datetime of when document has been created in ISO 8601 format
document	object	a JSON object containing info document
document_pages	list [object]	a JSON list containing document page objects
document_summary	object	a JSON object containing a summary of entities and aggregated entities at a document level

Service Fields Deep Dive

For more information about service_fields object visit Service Fields Object

Schema: Document Response > Document

Key	Type	Description
id	string	the ID of document
status	string	the processing status of document
revision_status	string	the revision status of document
original_name	string	the original name of document
content_type	string	the content-type of document
page_count	integer	the number of pages in document

Additional Information

status: more info on Document Status
revision_status: more info on Document Status

Schema: Sync Inference Response > Document Summary

Key	Type	Description
entities	object	a JSON object containing entities
aggregated_entities	object	a JSON object containing aggregated entities

Additional Information

entities: more info on Entities Object
aggregated_entities: more info on Aggregated Entities Object

For each entity_object or aggregated_entity_object in the summary will be reported only text and confidence.

If a field defined as multiple_values:false, has been extracted from multiple pages, will be picked then one with highest confidence.

Schema: Document Response > Document Page

Key	Type	Description
page_index	integer	the index if page (starts from 0)
page_layout	object	a JSON object containing layout info
ocr	list [object]	a list of ocr objects
entities_index	integer	the last ID assigned to an entity
entities	object	a JSON object containing entities
aggregated_entities	object	a JSON object containing aggregated entities
policy_violations	list [object]	a list of policy violation objects
errors	list	a list of non fatal errors occurred while processing

Additional Information

ocr: more info on Ocr Object
entities: more info on Entities Object
aggregated_entities: more info on Aggregated Entities Object

Status 202 - Accepted

The server accepted the request however the operation is still ongoing or an error occurred during document processing. To differentiate between these cases, status information contained within the document section of the response can be used. See Document Status.

JSON Response Example based on status

RUNNINGERROR

{
    "service": "<service-id>",
    "current_date": "2024-04-26T11:21:58+00:00",
    "document": {
        "status": "RUNNING",
        "message": "Currently processing the document. Please attempt again later."
    }
}

{
    "service": "<service-id>",
    "current_date": "2024-04-26T11:21:58+00:00",
    "document": {
        "status": "ERROR",
        "message": "An error occurred during document processing. Inference has been aborted."
    }
}

Schema: Document Response

Key	Type	Description
service	string	the service identifier
current_date	object	datetime of when document has been created in ISO 8601 format
document	object	a JSON object containing info document

Schema: Document Response > Document

Key	Type	Description
status	string	the processing status of document
message	string	message about document processing status

Error Responses

The request was unsuccessful, and a specific status code is returned to identify the error.

Status	Message	Description	Reference
401	Unauthorized	the server has not been able to authenticate the request.	Response 401
404	Not Found	the server could not locate the requested resource.	Response 404
422	Unprocessable Content	The server has not been able to process the content of the request.	Response 422
429	Too Many Requests	the client has sent too many requests in a short period, exceeding the rate limit. Please try again later.	Response 429


500	Internal Server Error	the server encountered an unexpected and unrecoverable error while processing the request.	Response 500
503	Service Unavailable	the server could be under maintenance for an update. Will be back soon.	Response 503

Status 401 - Unauthorized

The current endpoint is protected and requires an API key to be accessed. If sufficient privileges are not present, the request will not be authorized.

Tip

Double-check that the API Key is correct, valid and set using the x-api-key header in the request. Also make sure that you are using the right API key for the service you are requesting and that the service ID in it is correct and corresponds to the ID of an existing service in your account.

Status 404 - Not Found

The service ID provided does not exist or could not be found. Please verify the ID and try again. The document ID provided does not exist or could not be found. Please verify that the ID is valid and that it references a document processed with the service you specified.

Status 422 - Unprocessable content

This status code indicates that the server successfully received and understood the request, but it cannot process it due to errors in the provided data. These errors may include missing fields, invalid formats, or values that do not meet the endpoint requirements.

Tip

Double-check your request's payload format and parameters

Status 429 - Too Many Requests

This status code is returned when the client has made too many requests in a given timeframe, exceeding the rate limits set by the server. It indicates that the client needs to slow down and retry after a specified cooldown period. Rate limits are typically enforced to protect the server from being overwhelmed and to ensure fair use of resources.

Status 500 - Internal Server Error

This status code indicates that the server encountered an unexpected error or condition that prevented it from completing the request. It is a generic error message when no more specific message is suitable. The client cannot resolve the issue.

Status 503 - Service Unavailable

This status code indicates that the server is currently unavailable, typically due to ongoing maintenance or temporary overloading. The server is unable to handle the request at the moment, but the issue is expected to be resolved shortly. This status code signals that the downtime is temporary, and the service will be restored once maintenance is complete.