REST API Reference

General

Version of PreFace Services

GET /version

Version of PreFace Services

Returns the version of PreFace Services.

Status Codes:

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

200 Response schema:

string

Example response:

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

Aware Preface Library, version x.x.x.x

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Analyze Images with PreFace

POST /analyzeImage

Analyze Images with PreFace

Analyze each Face detected in one or more images according to the instructions specified with each image.

Request schema:

Name	Type	Description
images	(array of objects)
output	(array of objects)	List of requested output data from PreFace for each Face found in the input image.
performConstruction	boolean	(Optional) Specify if the Face should be Constructed or not before attempting to determine Compliance with the profileXml sent. When specified, all results for this output will be in relation to the Constructed Face. Requires the profileXml field.
profileXml	string	Contents of a PreFace 6 Profile XML File to be used in determining Compliance for each Face. Data for each Metric in the Profile will be returned.
id	string	ID descriptor for specific set of output data.
metrics	(array of string)	(Optional) Specify a list of Metrics to be analyzed. This list can be specified to obtain Metric data with or without the profileXml specified.
input	object	Parameters to use as inputs to PreFace for analysis.
imageData	string	Base64 Encoded Image to analyze.
rotation	number	(Optional) The angle of rotation to be applied to the image before analysis.
faceSensitivity	number	(Optional) The sensitivity used in detecting faces when analyzing the image.
faceGranularity	number	(Optional) The granularity used in detecting faces when analyzing the image.
faceMinimumSize	number	(Optional) The minimum face size used in detecting faces when analyzing the image.
faceDetectionMode	string	(Optional) The face detection mode used in detecting faces when analyzing the image. Values: FACE_ORDERING_BY_SIZE, FACE_ORDERING_BY_SCORE, DOMINANT_FACE_BY_SIZE, DOMINANT_FACE_BY_SCORE
faceMaximumSize	number	(Optional) The maximum face size used in detecting faces when analyzing the image.
id	string	ID descriptor for specific Image object.

Example request:

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

{
    "images": [
        {
            "id": "id1",
            "input": {
                "rotation": 0,
                "faceMinimumSize": 0.1,
                "faceMaximumSize": 1.0,
                "faceSensitivity": 0.7,
                "faceGranularity": 0.2,
                "faceDetectionMode": "FACE_ORDERING_BY_SIZE",
                "imageData": "<base64 encoded image>"
            },
            "output": [
                {
                    "id": "Foo.xml",
                    "profileXml": "<PreFace Profile XML File Contents>",
                    "performConstruction": true,
                    "metrics": [
                        "IMAGE_WIDTH",
                        "IMAGE_HEIGHT"
                    ]
                }
            ]
        }
    ]
}

Status Codes:

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
images	(array of objects)	Array of objects containing the requested image results.
id	string	ID descriptor corresponding to an Image object from the request.
faces	(array of objects)	Array of objects containing the requested output for each face in the image. Absent if there were no Faces detected in the image.
output	(array of objects)	Array of objects containing the output data related to the face.
features	(array of objects)	Array of Facial Feature related data for the Face.
name	string	Name of the Facial Feature Values: LEFT_EYE, RIGHT_EYE
x	number	X Value for the Coordinate of the Facial Feature.
y	number	Y Value for the Coordinate of the Facial Feature.
imageData	string	Base 64 Encoding of the Constructed Facial Image. Only present if performConstruction was True in the request.
id	string	ID descriptor corresponding to an Output object from the request.
metrics	(array of objects)	Array of objects describing Metric related data for the Face. Absent if no profileXml nor Metrics were specified in the request.
score	number	Score of the Metric.
name	string	Name of the Metric. Values: IMAGE_WIDTH, IMAGE_HEIGHT
complianceStatus	string	The Compliance Status for the Metric with relation to the Profile. Only present if the Metric was in the profileXml contents specified in the request. Values: OK, FAIL_HIGH, FAIL_LOW, FAIL_VALUE
category	string	Category the Metric belongs to. Values: FACE_CHARACTERISTICS, EYE_CHARACTERISTICS, IMAGE_CHARACTERISTICS, ANOMALIES, IMAGE_GEOMETRY, DEMOGRAPHICS, IMAGE_STORAGE
isCompliant	boolean	Indicates if the Face analyzed was Compliant with the Profile specified. Absent if there was no profileXml specified in the request.

Example response:

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

{
    "images": [
        {
            "id": "id1",
            "faces": [
                {
                    "output": [
                        {
                            "id": "Foo.xml",
                            "isCompliant": false,
                            "imageData": "<base64 encoded image>",
                            "features": [
                                {
                                    "name": "Feature1",
                                    "x": 140.2,
                                    "y": 345.1
                                }
                            ],
                            "metrics": [
                                {
                                    "name": "IMAGE_WIDTH",
                                    "score": 1840.0,
                                    "complianceStatus": "OK",
                                    "category": "IMAGE_GEOMETRY"
                                },
                                {
                                    "name": "IMAGE_HEIGHT",
                                    "score": 920.0,
                                    "category": "IMAGE_GEOMETRY"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)
description	string	Error description

Example response:

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

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Perform autocapture with Preface.

POST /autocaptureVideo

Perform autocapture with Preface.

Request schema:

Name	Type	Description
frames	(array of objects)
data	string	Base64 encoded image.
timestamp	number	Time stamp in seconds. Timestamps for frames are relative to eachother.
resolutionPreview	resolution
resolutionCapture	resolution
profile	object
xml	string	PreFace Profile XML file contents.
faceDetectionMinSize	number	(Optional) The minimum face size used in detecting faces when analyzing the image.
faceDetectionMaxSize	number	(Optional) The maximum face size used in detecting faces when analyzing the image.
faceDetectionSensitivity	number	(Optional) The sensitivity used in detecting faces when analyzing the image.
faceDetectionGranularity	number	(Optional) The granularity used in detecting faces when analyzing the image.
faceDetectionMode	string	(Optional) The face detection mode used in detecting faces when analyzing the image. Values: FACE_ORDERING_BY_SIZE, FACE_ORDERING_BY_SCORE, DOMINANT_FACE_BY_SIZE, DOMINANT_FACE_BY_SCORE
autocaptureMinimumFrameCount	number	(Optional) The number of consecutive, compliant frames necessary to return a successful capture.

Example request:

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

{
    "profile": {
        "name": "profile.xml",
        "xml": "<profile content>"
    },
    "rotation": "0,",
    "frames": [
        {
            "data": "<base64 encoded image>",
            "tags": [],
            "timestamp": 1565891124780.0334
        }
    ],
    "resolutionPreview": {
        "width": 240,
        "height": 320
    },
    "resolutionCapture": {
        "width": 480,
        "height": 640
    }
}

Status Codes:

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
frameResults	(array of objects)	Autocapture results for each frame from the request.
feedback	(array of string)	Array of feedback codes indicating why the frame was non-compliant. Empty if the frame was compliant.
compliant	boolean	True if the frame was compliant with the Profile specified.
results	object
capturedFrameIndex	number	Frame index for the captured frame result.
captured	boolean	True if a capture signal was detected when processing the frames. False if all frames were not able to fulfill capture conditions.

Example response:

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

{
    "frameResults": [
        {
            "compliant": false,
            "feedback": [
                "NO_FACE_DETECTED"
            ]
        }
    ],
    "results": {
        "captured": false,
        "capturedFrameIndex": -1
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)
description	string	Error description

Example response:

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

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Encrypted version of autocaptureVideo endpoint.

POST /autocaptureVideoEncrypted

Encrypted version of autocaptureVideo endpoint.

Please Note:

Encrypted request data is generated by Knomi software.

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 /autocaptureVideoEncrypted 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 not valid
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
frameResults	(array of objects)	Autocapture results for each frame from the request.
feedback	(array of string)	Array of feedback codes indicating why the frame was non-compliant. Empty if the frame was compliant.
compliant	boolean	True if the frame was compliant with the Profile specified.
results	object
capturedFrameIndex	number	Frame index for the captured frame result.
captured	boolean	True if a capture signal was detected when processing the frames. False if all frames were not able to fulfill capture conditions.

Example response:

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

{
    "frameResults": [
        {
            "compliant": false,
            "feedback": [
                "NO_FACE_DETECTED"
            ]
        }
    ],
    "results": {
        "captured": false,
        "capturedFrameIndex": -1
    }
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)
description	string	Error description

Example response:

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

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Calculate Region of Interest with Preface.

POST /calculateROI

Calculate Region of Interest with Preface.

Request schema:

Name	Type	Description
profile	object	Profile object
xml	string	PreFace Profile XML file contents.
resolution	resolution

Example request:

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

{
    "profile": {
        "xml": "<profile content>"
    },
    "resolution": {
        "width": 480,
        "height": 640
    }
}

Status Codes:

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
x	number	X Value for the Coordinate of ROI Origin.
width	number	Width of ROI measured in pixel.
y	number	Y Value for the Coordinate of ROI Oorigin.
height	number	Height of ROI measured in pixel.

Example response:

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

{
    "height": 512,
    "width": 356,
    "x": 62,
    "y": 0
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)
description	string	Error description

Example response:

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

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Shut down the PreFace REST Service.

POST /shutdown

Shut down the PreFace REST Service.

Shut down the PreFace REST Service.

Status Codes:

200 OK – Success

Validate profile with Preface.

POST /validateProfile

Validate profile with Preface.

Request schema:

Name	Type	Description
profile	object
xml	string	PreFace Profile XML file contents.

Example request:

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

{
    "profile": {
        "xml": "<profile content>"
    }
}

Status Codes:

200 OK – Success
400 Bad Request – The request is not valid
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
profileErrors	(array of string)

Example response:

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

{
    "profileErrors": []
}

400 Response schema:

Name	Type	Description
error	object
code	integer	Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)
description	string	Error description

Example response:

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

{
    "error": {
        "code": -2,
        "description": "Request was not valid JSON."
    }
}

500 Response schema:

Name	Type	Description
error	object	Error object
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1,
        "description": "string"
    }
}

Structure Reference

faceAnalyzerRequestEncrypted Model Structure

Name

Type

Description

key

string

Encrypted request ‘key’ value

iv

string

Encrypted request ‘iv’ value

p

string

Encrypted request ‘p’ value

autocaptureVideoRequest Model Structure

Name

Type

Description

frames

(array of objects)

   data

string

Base64 encoded image.

   timestamp

number

Time stamp in seconds. Timestamps for frames are relative to eachother.

resolutionPreview

resolution

resolutionCapture

resolution

profile

object

   xml

string

PreFace Profile XML file contents.

faceDetectionMinSize

number

(Optional) The minimum face size used in detecting faces when analyzing the image.

faceDetectionMaxSize

number

(Optional) The maximum face size used in detecting faces when analyzing the image.

faceDetectionSensitivity

number

(Optional) The sensitivity used in detecting faces when analyzing the image.

faceDetectionGranularity

number

(Optional) The granularity used in detecting faces when analyzing the image.

faceDetectionMode

string

(Optional) The face detection mode used in detecting faces when analyzing the image. Values: FACE_ORDERING_BY_SIZE, FACE_ORDERING_BY_SCORE, DOMINANT_FACE_BY_SIZE, DOMINANT_FACE_BY_SCORE

autocaptureMinimumFrameCount

number

(Optional) The number of consecutive, compliant frames necessary to return a successful capture.

autocaptureVideoResponse Model Structure

Name

Type

Description

frameResults

(array of objects)

Autocapture results for each frame from the request.

   feedback

(array of string)

Array of feedback codes indicating why the frame was non-compliant. Empty if the frame was compliant.

   compliant

boolean

True if the frame was compliant with the Profile specified.

results

object

   capturedFrameIndex

number

Frame index for the captured frame result.

   captured

boolean

True if a capture signal was detected when processing the frames. False if all frames were not able to fulfill capture conditions.

resolution Model Structure

Resolution in pixels

Name

Type

Description

width

number

Width of resolution measured in pixels.

height

number

Height of resolution measured in pixels.

400Error Model Structure

Name

Type

Description

code

integer

Error code Values: -1 (Unknown Error), -2 (Invalid Input JSON), -3 (Missing Mandatory Field), -4 (Field Has Wrong Type), -5 (Invalid Base64 String), -6 (Invalid Value)

description

string

Error description