REST API Reference¶

Analysis¶

Analyze the provided images to determine if each have the specified document and if that document is correctly positioned in the image.¶

POST /autocaptureDocument

Analyze the provided images to determine if each have the specified document and if that document is correctly positioned in the image.

The autocaptureDocument endpoint takes a Workflow and array of images. It will analyze each image to determine if it is the specified document type and that the document is positioned correctly. For autocapturing in real time it is recommended to send in one image per transaction.

Request schema:

Name	Type	Description
workflow	workflow
images	(array of objects)	An array of image objects that contain image data that has been base64 encoded.
data	string	A base64 encoded image.

Example request:

POST /autocaptureDocument HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "workflow": {
        "documentType": "CUSTOM",
        "aspectRatioWidth": 5,
        "aspectRatioHeight": 4,
        "imagePercentage": 0.52
    },
    "images": [
        {
            "data": "<base64 encoded image>"
        },
        {
            "data": "<base64 encoded image>"
        }
    ]
}

Status Codes:	200 OK – Success. 400 Bad Request – The request is malformed and invalid. 500 Internal Server Error – Internal error. Please see the Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
results	object	Autocapture results for the submitted images.
captured	boolean	True if the document has been found in one of the submitted images. False if the document was not found or was not correctly positioned.
capturedImageIndex	number	If the captured element is true, this will be the index of the image where the document was found. If the captured element is false, this will be -1.
imageResults	(array of objects)
imageIndex	integer	Index indicating which image submitted generated these results.
feedback	string	Feedback code generated by the analysis of the image. Values: DOCUMENT_FOUND - The document was found and is correctly positioned in this image., DOCUMENT_NOT_FOUND - No document was detected in this image., TOO_FAR - The document was too far from the camera. Move the document closer to the camera., TOO_CLOSE - The document was too close to the camera. Move the document further away from the camera., TOO_BLURRY - The image was too blurry to correctly read the document. Stop moving the camera and bring the document into focus., OFF_ANGLE - The document is at an off angle from the camera. Correct the document so it is parallel to the camera., WRONG_DOCUMENT - The document is the incorrect type. Present the correct document.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "results": {
        "captured": true,
        "capturedImageIndex": 1,
        "imageResults": [
            {
                "imageIndex": 0,
                "feedback": "TOO_BLURRY"
            },
            {
                "imageIndex": 1,
                "feedback": "DOCUMENT_FOUND"
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code indicating what is wrong with the submitted JSON. Values: -1 - Unknown Error, -2 - Invalid input JSON, -3 - Missing a mandatory field, -4 - Field has wrong type, -5 - Invalid base64 string, -6 - Invalid value, -7 - Invalid image data, -8 - Invalid image size
description	string	A description of the error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "The request was not a valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code. See table below.
description	string	Error description.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "-1",
        "description": "The functionality requested is not supported."
    }
}

Provides the same functionality as the autocaptureDocument endpoint but with an encrypted message.¶

POST /autocaptureDocumentEncrypted

Provides the same functionality as the autocaptureDocument endpoint but with an encrypted message.

Decrypts then analyzes the images according to the settings specified. It will analyze each image to determine if it is the specified document type and that the document is positioned correctly. Packages for this endpoint are generated by Knomi software such as Knomi Web.

Request schema:

Name	Type	Description
key	string	Encrypted request ‘key’ value.
iv	string	Encrypted request ‘iv’ value.
p	string	Encrypted request ‘p’ value.

Example request:

POST /autocaptureDocumentEncrypted HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "key": "string",
    "iv": "string",
    "p": "string"
}

Status Codes:	200 OK – Success. 400 Bad Request – The request is malformed and invalid. 500 Internal Server Error – Internal error. Please see the Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
results	object	Autocapture results for the submitted images.
captured	boolean	True if the document has been found in one of the submitted images. False if the document was not found or was not correctly positioned.
capturedImageIndex	number	If the captured element is true, this will be the index of the image where the document was found. If the captured element is false, this will be -1.
imageResults	(array of objects)
imageIndex	integer	Index indicating which image submitted generated these results.
feedback	string	Feedback code generated by the analysis of the image. Values: DOCUMENT_FOUND - The document was found and is correctly positioned in this image., DOCUMENT_NOT_FOUND - No document was detected in this image., TOO_FAR - The document was too far from the camera. Move the document closer to the camera., TOO_CLOSE - The document was too close to the camera. Move the document further away from the camera., TOO_BLURRY - The image was too blurry to correctly read the document. Stop moving the camera and bring the document into focus., OFF_ANGLE - The document is at an off angle from the camera. Correct the document so it is parallel to the camera., WRONG_DOCUMENT - The document is the incorrect type. Present the correct document.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "results": {
        "captured": true,
        "capturedImageIndex": 1,
        "imageResults": [
            {
                "imageIndex": 0,
                "feedback": "TOO_BLURRY"
            },
            {
                "imageIndex": 1,
                "feedback": "DOCUMENT_FOUND"
            }
        ]
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code indicating what is wrong with the submitted JSON. Values: -1 - Unknown Error, -2 - Invalid input JSON, -3 - Missing a mandatory field, -4 - Field has wrong type, -5 - Invalid base64 string, -6 - Invalid value, -7 - Invalid image data, -8 - Invalid image size
description	string	A description of the error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "The request was not a valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code. See table below.
description	string	Error description.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "-1",
        "description": "The functionality requested is not supported."
    }
}

Get client parameters needed to capture a document.¶

POST /getCaptureParameters

Get client parameters needed to capture a document.

Given a workflow the getCaptureParameters endpoint will provide the minimum resolution required to capture the document specified.

Request schema:

Name	Type	Description
workflow	workflow

Example request:

POST /getCaptureParameters HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "workflow": {
        "documentType": "PASSPORT"
    }
}

Status Codes:	200 OK – Success. 400 Bad Request – The request is malformed and invalid. 500 Internal Server Error – Internal error. Please see the Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
minimumResolution	object
width	number	Minimum width necessary for submitted images to capture the specified document.
height	number	Minimum height necessary for submitted images to capture the specifed document.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "minimumResolution": {
        "width": 1920,
        "height": 1080
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code indicating what is wrong with the submitted JSON. Values: -1 - Unknown Error, -2 - Invalid input JSON, -3 - Missing a mandatory field, -4 - Field has wrong type, -5 - Invalid base64 string, -6 - Invalid value, -7 - Invalid image data, -8 - Invalid image size
description	string	A description of the error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "The request was not a valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code. See table below.
description	string	Error description.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "-1",
        "description": "The functionality requested is not supported."
    }
}

Get a rectangle describing where in the image the document is expected.¶

POST /getCaptureRegion

Get a rectangle describing where in the image the document is expected.

Given a workflow and a resolution for incoming images the getCaptureRegion endpoint will provide a rectangle that describes the ideal positioning for the document specified at that resolution.

Request schema:

Name	Type	Description
workflow	workflow
captureResolution	object
width	number	Width of the incoming images to be used in autocapture.
height	number	Height of the incoming images to be used in autocapture.

Example request:

POST /getCaptureRegion HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "workflow": {
        "documentType": "CUSTOM",
        "aspectRatioWidth": 5,
        "aspectRatioHeight": 4,
        "imagePercentage": 0.52
    },
    "captureResolution": {
        "width": 1280,
        "height": 720
    }
}

Status Codes:	200 OK – Success. 400 Bad Request – The request is malformed and invalid. 500 Internal Server Error – Internal error. Please see the Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
x	number	X coordinate for the upper left corner of the rectangle.
y	number	Y coordinate for the upper left corner of the rectangle.
width	number	Width of the rectangle.
height	number	Height of the rectangle.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

{
    "x": 253,
    "y": 50,
    "width": 773,
    "height": 619
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code indicating what is wrong with the submitted JSON. Values: -1 - Unknown Error, -2 - Invalid input JSON, -3 - Missing a mandatory field, -4 - Field has wrong type, -5 - Invalid base64 string, -6 - Invalid value, -7 - Invalid image data, -8 - Invalid image size
description	string	A description of the error.

Example response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

{
    "error": {
        "code": -2,
        "description": "The request was not a valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code. See table below.
description	string	Error description.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "-1",
        "description": "The functionality requested is not supported."
    }
}

General¶

Version of the Knomi DocumentAnalyzer Server¶

GET /version

Version of the Knomi DocumentAnalyzer Server

Retrieve the version of the Knomi DocumentAnalyzer server.

Status Codes:	200 OK – Success. 500 Internal Server Error – Internal error. Please see the Error Codes section for detailed information.

200 Response schema:

string

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

Aware KnomiDocumentAnalyzer Library, version 1.0 r170000

500 Response schema:

Name	Type	Description
error	object
code	integer	Error code. See table below.
description	string	Error description.

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

{
    "error": {
        "code": "-1",
        "description": "The functionality requested is not supported."
    }
}

Structure Reference¶

autocaptureDocumentRequest Model Structure¶

Name Type Description

workflow workflow

images (array of objects) An array of image objects that contain image data that has been base64 encoded.

data string A base64 encoded image.

autocaptureDocumentEncryptedRequest Model Structure¶

Name Type Description

key string Encrypted request ‘key’ value.

iv string Encrypted request ‘iv’ value.

p string Encrypted request ‘p’ value.

autocaptureDocumentResponse Model Structure¶

Name Type Description

results object Autocapture results for the submitted images.

   captured boolean True if the document has been found in one of the submitted images. False if the document was not found or was not correctly positioned.

   capturedImageIndex number If the captured element is true, this will be the index of the image where the document was found. If the captured element is false, this will be -1.

   imageResults (array of objects)

      imageIndex integer Index indicating which image submitted generated these results.

      feedback string Feedback code generated by the analysis of the image. Values: DOCUMENT_FOUND - The document was found and is correctly positioned in this image., DOCUMENT_NOT_FOUND - No document was detected in this image., TOO_FAR - The document was too far from the camera. Move the document closer to the camera., TOO_CLOSE - The document was too close to the camera. Move the document further away from the camera., TOO_BLURRY - The image was too blurry to correctly read the document. Stop moving the camera and bring the document into focus., OFF_ANGLE - The document is at an off angle from the camera. Correct the document so it is parallel to the camera., WRONG_DOCUMENT - The document is the incorrect type. Present the correct document.

getCaptureParametersRequest Model Structure¶

Name Type Description

workflow workflow

getCaptureParametersResponse Model Structure¶

Name Type Description

minimumResolution object

width number Minimum width necessary for submitted images to capture the specified document.

height number Minimum height necessary for submitted images to capture the specifed document.

getCaptureRegionRequest Model Structure¶

Name Type Description

workflow workflow

captureResolution object

width number Width of the incoming images to be used in autocapture.

height number Height of the incoming images to be used in autocapture.

getCaptureRegionResponse Model Structure¶

Name Type Description

x number X coordinate for the upper left corner of the rectangle.

y number Y coordinate for the upper left corner of the rectangle.

width number Width of the rectangle.

height number Height of the rectangle.

workflow Model Structure¶

Settings for how to capture the document.

Name Type Description

documentType string Type of document to capture. Values: DRIVERS_LICENSE - A driver’s license, PASSPORT - A passport, TURKISH_TITLE_DEED - A Turkish Title Deed, CUSTOM - A custom document specified by the aspectRatioWidth, aspectRatioHeight, and imagePercentage parameters.

aspectRatioWidth integer The width portion of the desired document’s aspect ratio. Only usable with the CUSTOM document type.

aspectRatioHeight integer The height portion of the desired document’s aspect ratio. Only usable with the CUSTOM document type.

imagePercentage number The percentage of the image that the document needs to occupy to be captured. Specified as a double between 0.0 and 1.0. When specifying large percentages, the aspect ratio specified will be maintained within the bounds of the image. Only usable with the CUSTOM document type.

400Error Model Structure¶

Name Type Description

code integer Error code indicating what is wrong with the submitted JSON. Values: -1 - Unknown Error, -2 - Invalid input JSON, -3 - Missing a mandatory field, -4 - Field has wrong type, -5 - Invalid base64 string, -6 - Invalid value, -7 - Invalid image data, -8 - Invalid image size

description string A description of the error.

500Error Model Structure¶

Name Type Description

code integer Error code. See table below.

description string Error description.