Biometric Engine - API

System Information#

Get Logs#

GET {bioengine_url}/logs

Gets all biometric and plugin troubleshooting logs in a zip file.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Return Type

String

Example Request

curl --location --request GET 'http://localhost:8080/logs' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYm...' \
--data-raw ''

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/zip

Responses

200 Returned biometric logs zip file String.

500 Error obtaining biometric logs zip file String.

Get Template Types#

GET {bioengine_url}/template-types

Gets all system-installed biometric matchers

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Return Type

TemplateTypeResponse

Example Request

curl --location --request GET 'http://localhost:8080/template-types' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlv...'

Example Response

Content-Type: application/json

{
  "templateTypes" : [ {
    "templateType" : "templateType",
    "scoreThreshold" : 0.8008282,
    "isInstantiated" : true,
    "numSamplesForEnroll" : 6
  }, {
    "templateType" : "templateType",
    "scoreThreshold" : 0.8008282,
    "isInstantiated" : true,
    "numSamplesForEnroll" : 6
  } ]
}

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Returning Template Types TemplateTypeResponse

500 Error obtaining Template Types BioEngineError

Template Management#

Enroll Biometric samples#

POST {bioengine_url}/persons/{personid}/biometrics

Enrolls one or more biometric samples as a biometric template or directly enrolls a template. Either a list of samples, or a template must be provided.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)

Consumes

This API call consumes the following media types via the Content-Type request header:

application/json

Request Body

body BiometricEnrollRequest (required)

Return Type

BiometricEnrollResponse

Example Request

curl --location --request POST 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...' \
--header 'Content-Type: application/json' \
--data-raw '{
      "templateType": "Face:OpenDNN",
      "templateContext": "",
      "samples":["/9j/4RFiRXhpZgAATU0AKgAAAAgADAEAAAMAAAABA3MAAAEBAAMAAAABBKg..."
      ]
    }
 '

Example Response

Content-Type: application/json

{
  "quality" : 0.8008282
}

Produces

This API call produces the following media types according to Accept request header; the media type will be conveyed by the Content-Type response header.

application/json

Responses

201 Template created and enrolled BiometricEnrollResponse BiometricInfoResponse

400 Bad request BioEngineError

500 Enrollment error BioEngineError

Create Biometric Template#

POST {bioengine_url}/biometrics

Creates templates from one or more biometric samples or directly enroll a template. The template type is specified as a combination of a BioType, and a Biometric Plugin name.

A list of supported Template types can be obtained with the "Get Template Types" request.

A list of samples must be provided.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Consumes

This API call consumes the following media types via the Content-Type request header:

application/json

Request Body

body BiometricCreateRequest (required)

Return Type

BiometricCreateResponse

Example Request

curl --location --request POST 'http://localhost:8080/biometrics' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...' \
--header 'Content-Type: application/json' \
--data-raw '{
      "templateType": "Face:OpenDNN",      
      "samples":["/9j/4RFiRXhpZgAATU0AKgAAAAgADAEAAAMAAAABA3MAAAEBAAMAAAABBKg..."
      ]
    }
 '

Example Response

Content-Type: application/json

{
    "quality": 100.0,
    "templatedata": "b2cdvuX1QT7ouNI90Aa/uui3873ydVo8L8CrvIktgb0ygEo+wrDdvAHqlT7JRRO9R90uvqeisr1nK0w83AwXPgamMb5MInS9K+Mwvcv+..."
}

Produces

This API call produces the following media types according to Accept request header; the media type will be conveyed by the Content-Type response header.

application/json

Responses

201 Template created and returned BiometricCreateResponse (api.md#biometriccreateresponse)

400 Bad request BioEngineError

500 Create Template error BioEngineError

Get Person Details#

GET {bioengine_url}/persons/{personid}/biometrics

Gets the details for all enrolled biometric templates for a person.

note

If there are no templates for the given criteria found, 200 OK returned as a result but with an empty array.#

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)

Return Type

BiometricInfoResponse

Example Request

curl --location --request GET 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...'

Example Response

Content-Type: application/json

{
  "biometricInfos" : [ {
    "templateType" : "templateType",
    "templateContext" : "templateContext",
    "size" : 0,
    "timestamp" : 6
  }, {
    "templateType" : "templateType",
    "templateContext" : "templateContext",
    "size" : 0,
    "timestamp" : 6
  } ]
}

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Returning template information BiometricInfoResponse

500 Error obtaining biometric template information BioEngineError

Get Template Details#

GET {bioengine_url}/persons/{personid}/biometrics/{templatetype}

Gets the details about all enrolled biometric templates of the specified Template Type for a person.

note

If there are no templates for the given criteria found, 200 OK returned as a result but with an empty array.#

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)
templatetype (required)

Return Type

BiometricInfoResponse

Example Request

curl --location --request GET 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics/Face:OpenDNN' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...'

Example Response

Content-Type: application/json

{
"biometricInfos" : [ {
"templateType" : "templateType",
"templateContext" : "templateContext",
"size" : 0,
"timestamp" : 6
}, {
"templateType" : "templateType",
"templateContext" : "templateContext",
"size" : 0,
"timestamp" : 6
} ]
}

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Returning template information BiometricInfoResponse

500 Error obtaining biometric template information BioEngineError

Delete Biometrics#

DELETE {bioengine_url}/persons/{personid}/biometrics

Deletes all enrolled biometric templates for a person. 200 OK returned even if there were no templates to delete.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)

Example Request

curl --location --request DELETE 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...'

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Template(s) deleted

500 Error deleting biometric templates BioEngineError

Delete Template#

DELETE {bioengine_url}/persons/{personid}/biometrics/{templatetype}/{templatecontext}

Deletes the enrolled biometric template of the specified Template Type and Template Context for a person. 200 OK returned even if there was no template to delete.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)
templatetype (required)
templatecontext (required)

Example Request

curl --location --request DELETE 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics/Face:OpenDNN/test/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...'

Produces

This API call produces the following media types according to Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Template deleted

500 Error deleting biometric template BioEngineError

Delete All Templates#

DELETE {bioengine_url}/persons/{personid}/biometrics/{templatetype}

Deletes all enrolled biometric templates of the specified Template Type for a person. 200 OK returned even if there were no templates to delete.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)
templatetype (required)

Example Request

curl --location --request DELETE 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/biometrics/Face:OpenDNN' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...'

Produces

This API call produces the following media types according to Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Template(s) deleted

500 Error deleting biometric templates BioEngineError

Matching#

Identify#

POST {bioengine_url}/identify

Performs fast identification searches (1:N) against biometric templates pre-loaded into a cache based on multiple biometric samples and/or templates. If identification fails for a specific biometric sample or template, error details are returned along with the return code "200 OK". If templates are missing, empty placeholders will be returned in their place.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Consumes

This API call consumes the following media types via the Content-Type request header:

application/json

Request Body

body IdentifyRequest (required)

Return Type

IdentifyResponse

Example Request

curl --location --request POST 'http://localhost:8080/identify' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1........' \
--header 'Content-Type: application/json' \
--data-raw '{"identifyInputs": [{"templateType": "Face:OpenDNN",
    "sample": "/9j/4RFiRXhpZgAATU0AKgAAAAgADAEAAAMAAAABA3MAAAEBAAMAAAABBKgAA......"}]}'

Example Response

Content-Type: application/json

{
    "allIdentifyResults": [
        {
            "targetId": 0,
            "templateType": "LeftIris:IrisID",
            "totalDurationMS": 1054,
            "identifyDetails": [],
            "identifyMatchResults": [
                {
                    "personID": 45601,
                    "personUUID": "4f8c4e0a-ca36-45c7-ac52-2e3ffb9dc3b2",
                    "score": 97.760284,
                    "errorCode": 0
                },
                {
                    "personID": 45603,
                    "personUUID": "fb521903-4537-45b0-b252-906f2c2209d8",
                    "score": 97.760284,
                    "errorCode": 0
                }
            ],
            "errorCode": 0,
            "errorMessage": null
        }
    ]
}

Produces

This API call produces the following media types according to Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Returning identification results IdentifyResponse

400 Bad request BioEngineError

500 Error obtaining identification results BioEngineError

Verify#

POST {bioengine_url}/persons/{personid}/verify

Performs verification of multiple biometric samples and/or templates against a person's enrolled templates. If individual verifications fail, error details are returned along with the return code "200 OK". If templates are missing, empty placeholders will be returned in their place.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

personid (required)

Consumes

This API call consumes the following media types via the Content-Type request header:

application/json

Request Body

body VerifyRequest (required)

Return Type

VerifyResponse

Example Request

curl --location --request POST 'http://localhost:8080/persons/9ed24f50-3662-11eb-b01a-adada03b6af2/verify' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1........' \
--header 'Content-Type: application/json' \
--data-raw '{"verifyInputs": [{"templateType": "Face:OpenDNN",
    "sample": "/9j/4RFiRXhpZgAATU0AKgAAAAgADAEAAAMAAAABA3MAAAEBAAMAAAABBKgAA......"}]}'

Example Response

Content-Type: application/json

{
  "allMatchResults" : [ {
    "matchResults" : [ {
      "score" : 0.8008282,
      "errorMessage" : "errorMessage",
      "errorCode" : 6,
      "personId" : "personId"
    }, {
      "score" : 0.8008282,
      "errorMessage" : "errorMessage",
      "errorCode" : 6,
      "personId" : "personId"
    } ]
  }, {
    "matchResults" : [ {
      "score" : 0.8008282,
      "errorMessage" : "errorMessage",
      "errorCode" : 6,
      "personId" : "personId"
    }, {
      "score" : 0.8008282,
      "errorMessage" : "errorMessage",
      "errorCode" : 6,
      "personId" : "personId"
    } ]
  } ]
}

Produces

This API call produces the following media types according to Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Responses

200 Returning verification results VerifyResponse

400 Bad request BioEngineError

500 Error obtaining verification results BioEngineError

Face Match#

Simple Face Match#

POST {bioengine_url}/match

Performs a biometric match comparison between two faces images using Imageware's patented algorithms and returns a pass or fail flag and confidence score: PASS ≥ 48.

The request MUST contain two image files uploaded as multipart/form-data

Image Requirements

Attached image files must adhere to the following parameters:

Format: JPG / JPEG or PNG
Dimensions: Minimum 150x150; Maximum 1024x1024px
File size: Maximum 2MB

Example Request

curl --location --request POST 'http://localhost:8080/match' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiYmlvZ...' \
--form 'Image1=@"/home/user/FaceA1.jpg"' \
--form 'Image2=@"/home/user/FaceA1.jpg"'

Example Response

{
  "Status" : "Status",
  "score" : 1.4658129,
  "Score" : 0.8008282,
  "DurationMS" : 6,
  "Pass" : true,
  "pass" : true,
  "durationMS" : 5,
  "status" : "status"
}

Produces

This API call produces the following media types according to the Accept request header (the media type will be conveyed by the Content-Type response header).

application/json

Response Codes

200 Returning match score FaceMatchResponse

400 Bad request BioEngineError

500 Error performing match BioEngineError

Cache Management#

Create Cache for All Plugins#

POST {bioengine_url}/createcache

Recreates cache files from a database for installed plugins.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Example Request

curl --location --request POST 'http://localhost:8080/createcache' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOls...'

Example Response

Returns empty body

Response Codes

201 Empty body

400 Bad request BioEngineError

500 Error BioEngineError

Create Cache for a Specific Plugin#

POST {bioengine_url}/createplugincache/{pluginName}

Recreates a cache file from a database for a specific plugin.

The request MUST include an Authorization header type Bearer Token where the token is a valid JWT.

Path Parameters

pluginName (required)

Example Request

curl --location --request POST 'http://localhost:8080/createplugincache/OpenDNN' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOls...'

Example Response

Returns empty body

Response Codes

201 Empty Body

400 Bad request BioEngineError

500 Error BioEngineError

Models#

BioEngineError#

code Integer format: int32
message String

BiometricEnrollRequest#

templateType String
templateContext String
samples (optional) array[String]
template (optional) String

BiometricEnrollResponse#

quality Float format: float

BiometricInfo#

templateType String
templateContext String
size Integer format: int32
timestamp Long format: int64

BiometricInfoResponse#

biometricInfos array[BiometricInfo]

FaceMatchResponse#

Status (optional) String
Pass (optional) Boolean
Score (optional) Float format: float
DurationMS (optional) Integer format: int32
status String
score Float format: float
pass Boolean
durationMS Integer format: int32

IdentifyInput#

templateType String
sample (optional) String
template (optional) String
thresholdValue (optional) Float format: float
maxResults (optional) Integer format: int32

IdentifyRequest#

identifyInputs array[IdentifyInput]

IdentifyResponse#

allIdentifyResults array[IdentifyResults]

IdentifyResult#

targetId Integer format: int32
templateType String
totalDurationMS Integer format: int32
identifyMatchResults array[IdentifyMatchResult]
errorCode (optional) Integer format: int32
errorMessage (optional) String

IdentifyResults#

identifyResults array[IdentifyResult]

IdentifyMatchResult#

personId (optional) String
personUUID (optional) String
score (optional) Float format: float
errorCode (optional) Integer format: int32
errorMessage (optional) String

MatchResult#

personId (optional) String
score (optional) Float format: float
errorCode (optional) Integer format: int32
errorMessage (optional) String

MatchResults#

matchResults array[MatchResult]

TemplateTypeInfo#

templateType String
scoreThreshold Float format: float
numSamplesForEnroll Integer format: int32
isInstantiated Boolean

TemplateTypeResponse#

templateTypes array[TemplateTypeInfo]

VerifyInput#

templateType String
sample (optional) String
template (optional) String
thresholdValue (optional) Float format: float

VerifyRequest#

verifyInputs array[VerifyInput]

VerifyResponse#

allMatchResults array[MatchResults]

match_body#

Image1 (optional) byte[] format: binary
Image2 (optional) byte[] format: binary

BiometricCreateRequest#

templateType String
samples array[String]

BiometricCreateResponse#

quality Float format: float
templatedata String