REST API Reference

General

Version of PreFace Services

GET /version

Version of PreFace Services

Returns the version of PreFace Services.

Status Codes:

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 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 resolutionPreview  
resolutionCapture resolutionCapture  
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 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 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 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:

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 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 resolutionPreview  
resolutionCapture resolutionCapture  
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