REST API Reference

Cache Information

Get the maximum number of allowed encounters in a cache

GET /maxEncounters/{cacheName}

Get the maximum number of allowed encounters in a cache

Get the maximum number of allowed encounters given the cache name

Parameters

cacheName (string) –

Status Codes

200 OK – OK
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

10000

500 Response schema:

Name	Type	Description
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": 1015,
        "description": "The cache is full."
    }
}

Get the list of enrolled encounter IDs in a cache

GET /encounterList/{cacheName}

Get the list of enrolled encounter IDs in a cache

Get the list of enrolled encounter IDs given the cache name

Parameters

cacheName (string) –

Status Codes

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

200 Response schema:

array of string

Example response:

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

[
    "encounter01",
    "encounter02",
    "encounter03",
    "encounter04"
]

500 Response schema:

Name	Type	Description
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": 1015,
        "description": "The cache is full."
    }
}

Enrollment

Add an image to the gallery cache

POST /add/{cacheName}

Add an image to the gallery cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
metadata	metadata
encounter	object

Example Request Face Image:

POST /add/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "encounter": {
        "VISIBLE_FRONTAL": "<base64 encoded face image>",
        "id": "encounter01"
    }
}

Example Request Template:

POST /add/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "encounter": {
        "import": "<base64 encoded template>",
        "id": "encounter01"
    }
}

Status Codes

200 OK – Encounter id of the enrollment
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
id	string	Encounter ID added

Example response:

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

{
    "id": "encounter01"
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Add multiple encounters to a cache at once

POST /addBatch/{cacheName}

Add multiple encounters to a cache at once

Add multiple encounter templates to the given cache at once

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
	array of objects
encounter	encounter

Example request:

POST /addBatch/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

[
    {
        "encounter": {
            "import": "<base64 encoded face template>",
            "id": "encounter01"
        }
    },
    {
        "encounter": {
            "import": "<base64 encoded face template>",
            "id": "encounter02"
        }
    }
]

Status Codes

200 OK – The list of encounters that added successfully
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
	array of objects
id	string	Encounter id added

Example response:

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

[
    {
        "id": "encounter01"
    },
    {
        "id": "encounter02"
    }
]

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Update an image to the gallery cache

POST /update/{cacheName}

Update an image to the gallery cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
metadata	metadata
encounter	object

Example Request Face Image:

POST /update/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "encounter": {
        "VISIBLE_FRONTAL": "<base64 encoded face image>",
        "id": "encounter01"
    }
}

Example Request Template:

POST /update/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "encounter": {
        "import": "<base64 encoded template>",
        "id": "encounter01"
    }
}

Status Codes

200 OK – Encounter has been successfully updated with the image
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:

string

Example response:

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

""

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Delete an encounter from a cache

POST /delete/{cacheName}

Delete an encounter from a cache

Delete an encounter from a given cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
id	string	Encounter id to delete

Example request:

POST /delete/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "id": "encounter01"
}

Status Codes

200 OK – Encounter has been successfully deleted
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:

string

Example response:

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

""

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Empty a cache

POST /drop/{cacheName}

Empty a cache

Empty a given cache

Parameters

cacheName (string) –

Status Codes

200 OK – Cache has been successfully emptied
500 Internal Server Error – Internal error. Please see Error Codes section for detailed information.

200 Response schema:

Name	Type	Description
confirm	integer

Example response:

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

{
    "confirm": 1
}

500 Response schema:

Name	Type	Description
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": 1015,
        "description": "The cache is full."
    }
}

General

Version of Knomi FaceMatcher. Check if the server is alive.

GET /version

Version of Knomi FaceMatcher. Check if the server is alive.

Returns the version of Knomi FaceMatcher

Status Codes

200 OK – OK
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 NexaFace Library, version x.x.x

500 Response schema:

Name	Type	Description
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": 1015,
        "description": "The cache is full."
    }
}

Identification

Identify a new encounter with all encounters enrolled in a cache

POST /identify/{cacheName}

Identify a new encounter with all encounters enrolled in a cache

Identify a new encounter with all encounters enrolled in a given cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
probe	probe
workflow	workflow
candidateListSize	integer	The number of candidates should be returned in the final candidate list

Example Request Face Image:

POST /identify/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "candidateListSize": 10000
}

Example Request Template:

POST /identify/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "import": "<base64 encoded template>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "candidateListSize": 10000
}

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
candidateList	(array of candidateList)	List of candidates being identified
recordErrors	(array of recordErrors)	List of record errors

Example response:

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

{
    "candidateList": [
        {
            "id": "string",
            "score": 1.0,
            "scoreFmr": 1.0,
            "scorePercent": 1.0
        }
    ],
    "recordErrors": [
        {
            "id": "string",
            "error": "string"
        }
    ]
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Identify a new encounter with selected encounters enrolled in a cache

POST /identifyPartial/{cacheName}

Identify a new encounter with selected encounters enrolled in a cache

Identify a new encounter with all encounters enrolled in a given cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
encounter	encounter
workflow	workflow
candidateListSize	integer	The number of candidates should be returned in the final candidate list
idList	(array of string)	The array of IDs to be used in the identify

Example Request Face Image:

POST /identifyPartial/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "candidateListSize": 10000,
    "idList": [
        "encounter01",
        "encounter02"
    ]
}

Example Request Template:

POST /identifyPartial/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "import": "<base64 encoded template>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "candidateListSize": 10000,
    "idList": [
        "encounter01",
        "encounter02"
    ]
}

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
candidateList	(array of candidateList)	List of candidates being identified
recordErrors	(array of recordErrors)	List of record errors

Example response:

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

{
    "candidateList": [
        {
            "id": "string",
            "score": 1.0,
            "scoreFmr": 1.0,
            "scorePercent": 1.0
        }
    ],
    "recordErrors": [
        {
            "id": "string",
            "error": "string"
        }
    ]
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Util

Generate the internal face template

POST /export

Generate the internal face template

Request schema:

Name	Type	Description
encounter	encounter

Example request:

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

{
    "encounter": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    }
}

Status Codes

200 OK – Generated face template
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:

string

Example response:

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

{
    "export": "<base64 encoded template>"
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Generate the raw algorithm template

POST /exportAlgorithmTemplate

Generate the raw algorithm template

Request schema:

Name	Type	Description
encounter	encounter

Example request:

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

{
    "encounter": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    }
}

Status Codes

200 OK – Generated algorithm template
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:

string

Example response:

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

{
    "export": {
        "VISIBLE_FRONTAL": {
            "F500": "<base64 encoded template>"
        }
    }
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Fuse 1:1 FMR match scores from multiple modalities

POST /fuseScores

Fuse 1:1 FMR match scores from multiple modalities

Fuse 1:1 FMR match scores from multiple modalities

Request schema:

Name	Type	Description
scores	(array of number)	List of scores to fuse

Example request:

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

{
    "scores": [
        2.89,
        3.89
    ]
}

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
scoreFused	number	Fused score

Example response:

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

{
    "scoreFused": 5.559590816497803
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Fuse 1:N FMR scores from multiple modalities.

POST /fuseScoresForIdentification

Fuse 1:N FMR scores from multiple modalities.

Fuse 1:N FMR scores from multiple modalities.

Request schema:

Name	Type	Description
scores	(array of scores)	An array of multi-modal match sets.

Example request:

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

{
    "scores": [
        [
            {
                "scoreFmr": 6.0,
                "encounterCount": 10000
            },
            {
                "scoreFmr": 4.3,
                "encounterCount": 10000
            }
        ],
        [
            {
                "scoreFmr": 2.2,
                "encounterCount": 10000
            },
            {
                "scoreFmr": 3.1,
                "encounterCount": 10000
            }
        ]
    ]
}

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
scoresFused	(array of objects)	An array of
fusedScoreFpir	float	Score3
fusedScoreFpirPercent	float	Score4

Example response:

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

{
    "scoresFused": [
        {
            "fusedScoreFpir": 6.543163299560547,
            "fusedScoreFpirPercent": 78.09599304199219
        },
        {
            "fusedScoreFpir": 1.0215317010879517,
            "fusedScoreFpirPercent": 8.726956367492676
        }
    ]
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Verification

1-to-1 matching given two images or templates

POST /compare

1-to-1 matching given two images or templates

Request schema:

Name	Type	Description
metadata	metadata
probe	probe
gallery	gallery
workflow	workflow

Example Request Face Image:

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

{
    "metadata": {
        "value": {
            "client_device_brand": "Apple",
            "client_device_model": "iPhone 8",
            "client_os_version": "11.0.3",
            "client_version": "KnomiSLive_v:2.4.1_b:0.0.0_sdk_v:2.4.1_b:0.0.0",
            "localization": "en-US",
            "programming_language_version": "Swift 4.1",
            "username": "test"
        }
    },
    "probe": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    },
    "gallery": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    }
}

Example Request Template:

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

{
    "metadata": {
        "value": {
            "client_device_brand": "Apple",
            "client_device_model": "iPhone 8",
            "client_os_version": "11.0.3",
            "client_version": "KnomiSLive_v:2.4.1_b:0.0.0_sdk_v:2.4.1_b:0.0.0",
            "localization": "en-US",
            "programming_language_version": "Swift 4.1",
            "username": "test"
        }
    },
    "probe": {
        "import": "<base64 encoded template>"
    },
    "gallery": {
        "import": "<base64 encoded template>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    }
}

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
score	number	Matching score
scorePercent	number	0-100 representation of the score.

Example response:

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

{
    "score": 13.9989,
    "scorePercent": 98.02
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Verify against an encounter enrolled in the cache

POST /verify/{cacheName}

Verify against an encounter enrolled in the cache

Parameters

cacheName (string) –

Request schema:

Name	Type	Description
metadata	metadata
probe	probe
workflow	workflow
id	string	Encounter ID in a cache to compare with the new encounter

Example Request Face Image:

POST /verify/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "VISIBLE_FRONTAL": "<base64 encoded face sample>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "id": "test"
}

Example Request Template:

POST /verify/{cacheName} HTTP/1.1
Host: example.com
Content-Type: text/plain

{
    "probe": {
        "import": "<base64 encoded template>"
    },
    "workflow": {
        "comparator": {
            "algorithm": "F500",
            "faceTypes": [
                "VISIBLE_FRONTAL"
            ]
        }
    },
    "id": "test"
}

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
score	number	Matching score
scorePercent	number	0-100 representation of the score.

Example response:

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

{
    "score": 13.9989,
    "scorePercent": 98.02
}

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
code	integer	Error code
description	string	Error description

Example response:

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

{
    "error": {
        "code": 1015,
        "description": "The cache is full."
    }
}

Structure Reference

addRequest Model Structure

Name

Type

Description

metadata

metadata

encounter

object

addResponse Model Structure

Name

Type

Description

id

string

Encounter ID added

addBatchRequest Model Structure

Name

Type

Description

addBatchRequest

(array of objects)

encounter

encounter

addBatchResponse Model Structure

Name

Type

Description

addBatchResponse

(array of objects)

id

string

Encounter id added

deleteRequest Model Structure

Name

Type

Description

id

string

Encounter id to delete

compareRequest Model Structure

Name

Type

Description

metadata

metadata

probe

probe

gallery

gallery

workflow

workflow

verifyRequest Model Structure

Name

Type

Description

metadata

metadata

probe

probe

workflow

workflow

id

string

Encounter ID in a cache to compare with the new encounter

verifyResponse Model Structure

Name

Type

Description

score

number

Matching score

scorePercent

number

0-100 representation of the score.

identifyRequest Model Structure

Name

Type

Description

probe

probe

workflow

workflow

candidateListSize

integer

The number of candidates should be returned in the final candidate list

identifyResponse Model Structure

Name

Type

Description

candidateList

(array of candidateList)

List of candidates being identified

recordErrors

(array of recordErrors)

List of record errors

identifyPartialRequest Model Structure

Name

Type

Description

encounter

encounter

workflow

workflow

candidateListSize

integer

The number of candidates should be returned in the final candidate list

idList

(array of string)

The array of IDs to be used in the identify

faceComparator Model Structure

Face comparator object

Name

Type

Description

algorithm

string

Matching algorithm Values: F200, F500

faceTypes

(array of string)

Face type

visibleFrontal Model Structure

Encounter

Name

Type

Description

VISIBLE_FRONTAL

string

Base64 encoded face sample

import Model Structure

Encounter

Name

Type

Description

import

string

Base64 encoded template

encounterTemplate Model Structure

Encounter template

Name

Type

Description

import

string

Base64 encoded template

id

string

Encounter id

encounterVisibleFrontal Model Structure

Encounter object

Name

Type

Description

VISIBLE_FRONTAL

VISIBLE_FRONTAL

id

string

Encounter id

identifyCandidate Model Structure

Name

Type

Description

id

string

The ID of a subject in a cache

score

number

Matching score comparing the submitted subject with the entry in a cache

scoreFmr

number

The score is used for special use cases.

scorePercent

number

0-100 representation of the score.

identifyRecordError Model Structure

Name

Type

Description

id

string

ID for a subject

error

string

Error description with the subject

metadata Model Structure

(Optional) metadata assocated with the transaction

Name

Type

Description

username

string

(Optional) Username associated with the transaction

client_device_brand

string

(Optional) Client’s device brand

client_device_model

string

(Optional) Client’s device model

client_os_version

string

(Optional) Client’s os version

client_version

string

(Optional) Client’s application version

localization

string

(Optional) Client’s localization

programming_language_version

string

(Optional) Client’s programming language version

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

500Error Model Structure

Name

Type

Description

code

integer

Error code

description

string

Error description

fuseScoresForIdentificationParameter Model Structure

Name

Type

Description

fuseScoresForIdentificationParameter

(array of objects)

An array that is used to create a single fused score from a multi-modal 1:N identification search. Each entry in the array contains a result for a single candidate from a multi-modal 1:N identifications earch.

scoreFmr

float

scoreFmr returned from a 1:N identification for a single modality (such as face, fingerprint, or iris). It is important to note that this must be the scoreFmr value and not the score value.

encounterCount

integer

encounterCount for the gallery used for the 1:N identification.