Biometric Services 

Overview 

Biometric Services is intended to be used by service providers to build identity proofing services for their end-users.

  • Biometric Services exposes a simple REST API to detect and recognize faces from still images.
  • WebCapture SDK (Face Autocapture and Liveness) provides face and liveness detection from video streams.
Biometric Services diagram

Service Provider 

A service provider is an entity that develops apps and use cases on top of the BioServer.

The service provider:

  • Owns a client ID and a secret that gives access to Biometric Services for either the service provider itself or a third party
  • Can eventually be billed according to the use of Biometric Services (see: Billing System)

User 

The user is a person whose face images are sent to Biometric Services in the context of use cases that are implemented by the service provider.

Typical Use Cases 

The most common use cases are described below.

Reference Image Verification 

This use case flow allows the verification and storage of a user's face image.

Process Steps

The primary process steps are:

Note: The known user has already been authenticated by the Service Provider.

  1. The Service Provider (SP) app asks the known user for an image of their face,
  2. The face image is sent to the BioServer.
  3. The BioServer creates the face resource.
  4. An 'OK' notification is returned to the user.
  5. The SP app is notified that the operation is done.
  6. The SP app gets the face resource from the BioServer.
  7. The BioServer returns the face resource to the SP app.
  8. The face image is verified by Biometric Services and becomes a reference face image.
  9. The back end stores the user's reference image.
  10. The SP app notifies the user that registration is complete.

UML Diagram of Workflow

A diagram of the reference image verification process is shown below.

The reference image verification process

One-to-One Verification 

This use case allows one-to-one face image recognition. A user is asked for a face biometric authentication. Biometric Services checks it against a reference face (previously stored by the back end).

Process Steps

The primary process steps are:

  1. The Service Provider (SP) app asks the user for a face biometric authentication.
  2. The user sends their face image to the BioServer.
  3. The BioServer creates the face resource.
  4. The face resource is returned to the user who OKs it.
  5. The SP app is notified that the operation is complete.
  6. The SP app reads the reference face image.
  7. The SP app sends the reference face image to the BioServer.
  8. Biometric Services checks if a reference face matches another image of the user's face, and creates the face resource.
  9. 'OK' is returned to the SP app.
  10. The SP app returns the matches resource to the BioServer.
  11. The BioServer computes the matches.
  12. The matches resource is returned to the SP app.
  13. The SP app makes a decision about the match.
  14. The SP app notifies the user if the authentication is 'OK' or not.

Note: Only authentication via the APIkey is required. The Biometric Services session is not used. Images and verification results are not stored in the session.

Process Workflow Diagram

A diagram of the one-to-one verification process is shown below.

The one-to-one verification process

One-to-Few Identification 

This use-cases allows the service provider to find matches of a reference face among a small number of face images.

The primary process steps are:

  1. The Service Provider (SP) app sends the reference face image of a known user to the BioServer.
  2. The BioServer creates the face resource.
  3. An 'OK' notification is returned to the SP app.
  4. The face image is sent to the BioServer.
  5. The face resource is created.
  6. An 'OK' response is returned to the SP app.
  7. The SP app gets the matches resource from the BioServer.
  8. The BioServer computes matches.
  9. The BioServer returns the matches resource to the SP app.
  10. The SP app verifies that the faces match.

UML Workflow Diagram

A diagram of the one-to-few identification process is shown below.

The one-to-few identification process

API Diagrams 

This section discusses provides API UML diagrams for biometric services workflows.

One-to-One Verification 

This use case allows the service provider to match a known user's reference face to that specific user's face image.

Web Services

The following web services are involved in this scenario:

  • Direct Create Face: Returns the Face result in JSON format
  • Direct Match Image vs. Template: Returns the Match result in JSON format

API Workflow Diagram

A diagram of the one-to-one verification process is shown below.

Diagram of the one-to-one verification process

One-to-Few Identification 

This use case allows the service provider to find matches of a reference face among a small number of face images:

  • Biometric Services checks a face from a photo (“selfie”) and matches a face extracted from an identity document.
  • The result is signed by Biometric Services and can be added to the decision proof.

Note: All face images must be provided. No user database is involved.

Web Services

The following web services are involved in this scenario:

  • CreateBioSession: Returns a SESSION_ID
  • GetBioSession (Optional): Retrieves SESSION information.
  • CreateFaceFromImage (Multiple times): Encodes each face image and stores the template within distributed cache. Returns the faceid in response header(Location).
  • GetFace: (Optional): Retrieves each face information.
  • Matches: Retrieves a list of ordered matches (best scores come first) for a given face.

API Workflow Diagram

A diagram of the one-to-few verification process is shown below.

Diagram of the one-to-few verification process

Replay Challenge 

This feature allows you to replay data from smartphone Biometric Services that defines the challenge settings for the mobile device.

The mobile device uses these settings to:

  • Execute the liveness challenge
  • Send metadata to Biometric Services
  • Replay the liveness challenge from the given metadata via Faceflow.

Web Services

The following web services are involved in this scenario:

  • CreateBioSession: Returns SESSION_ID
  • GetBioSession (Optional): Retrieves SESSION information
  • initLivenessParameters: Posts liveness settings that will be used to run the challenge
  • getLivenessParameters (Optional): Retrieves liveness settings that will be used to run the challenge on the mobile side
Flow of replay data

API Errors 

Calls to the API may return errors. When this happens, an HTTP error code is returned along with an error object.

Error objects include the following:

  • An ID attribute which is used to identify the error
  • An optional message attribute which gives more information about the error

Sample Error Object 

The object containing the id error and the message describing the error are shown in the snippet:

JSON
1{
2 "id": "a52e98b4-b052-4289-b001-b53773ab656b",
3 "message": "morpho.rt.Exception: An operation has failed with error code=8 (Buffer has an unknown format)"
4}

REST APIs 

Overview 

This section provides details about the REST APIs used for user identity proofing in Biometric Services. These REST APIs accept JSON for the request payload, and send responses as JSON.

Bio-Sessions APIs 

This section describes the APIs used to create and retrieve bio-sessions.

A bio-session is a sequence of Biometric Services interactions related to the same user. A bio-session is explicitly created, but ends automatically after a configured number of seconds has elapsed.

CreateBioSession API

The CreateBioSession API creates a bio-session.

Method

A sample request to create the bio-session is shown in the snippet:

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions \
3 -H 'Content-Type: application/json' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -d '[{
6"correlationId",
7"imageStorageEnabled",
8"ttlSeconds"
9}]'
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields containing metadata associated with the API request and response fields are shown in the table.

Field
Description
apikey (optional)APIkey value
Content-TypeAllowed values: application/json
Request Body Fields

The request body is the data that you send to the server when you request the API. It is used to create the resource information returned by the API, and contains the representation of the resource to be created as shown in the following fields.

Field
Type
Description
correlationId (optional)stringThis specifies the custom identifier coming from the caller. The default value isnull
imageStorageEnabled (optional)booleanThis specifies if images need to be stored for this bio-session; if this parameter is set to true, then the image used to create a face resource can be retrieved using GetFaceImage. The default value is false.
ttlSeconds (optional)numberThis specifies a time-to-live value in seconds after which this bio-session is automatically ended. If it is not specified by CreateBioSession, the ttlSeconds will be set to the configured default. An error will occur if ttlSeconds is set higher than the configured max.
callbackURL (optional)stringThis specifies the URL used to notify a service provider that liveness check/replay-metadata results are available.
Response Example

This response sample shows a sample response from the request example.

The requested parameters are returned as specified with the -d option shown in the snippet:

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions \
3 -H 'Content-Type: application/json' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -d '[{
6"correlationId": "891a6728-1ac4-11e7-93ae-92361f002671",
7"imageStorageEnabled": false,
8"ttlSeconds": 300
9}]'
Success and Error Codes
Success Response 201

The 201 status code indicates that the bio-session was successfully created. It also contains the Location header string of the URI for the created face image, as shown in the table.

Field
Type
Description
LocationstringHeader containing the URI of the bio-session created

An example success snippet is shown below:

HTTP
1HTTP/1.1 201 Created
2get
3Location: /v2/bio-sessions/0991cedc-9111-4b9d-9e4e-8d6eb4db488f
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The status code indicates the specific error type and the issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the bio-session

GetBioSession API

The GetBioSession API retrieves information about the bio-session.

Endpoint
Shell
1https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId} \
Request Example

The requested bioSessionID field and apikey header value (specified with the -H option) are shown in the snippet:

Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId} \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Field

The HTTP header field containing metadata associated with the API request and response fields is shown below.

Field
Description
apikey (optional)APIkey value
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown below.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session resource to retrieve
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created, as shown in the fields below.

Field
Type
Description
idstringThe bio-session unique identifier generated by Biometric Services
correlationId (optional)stringThe custom identifier coming from the caller
imageStorageEnabled (optional)booleanIf images will be stored for this bio-session
createddatetimeThe date on which the bio-session is created
expiresdatetimeThe date after which the bio-session will expire and will be removed from the server
signature (optional)stringThe digital signature (JWS) of the response—authentication and integrity can be verified afterward using the Biometric Services public certificate
Response Example

This response sample returns the requested parameters with the bio-session information as shown in the snippet:

JSON
1{
2 "id": "0991cedc-9111-4b9d-9e4e-8d6eb4db488f",
3 "correlationId": "891a6728-1ac4-11e7-93ae-92361f002671",
4 "imageStorageEnabled": false,
5 "created": "2017-05-18T10:14:39.587Z",
6 "expires": "2017-05-18T10:19:39.587Z",
7 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAiaWQiIDogIjA5OTFjZ…vtmiJGc"
8}
Error Codes

The error status code indicates the specific error type and the error code issue. If an error occurs, one of the 4xx status codes will be returned as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to retrieve the bio-session
404Unable to find a bio-session for the given identifier

HealthCheck / Monitoring / Capabilities APIs 

This section describes the GetCapabilities API that requests some capabilities of the bio-session, along with the version number and the supported algorithm.

This API retrieves various capabilities of the bio-session, along with the algorithm used, the version used, and the supported algorithms.

Method

The GET and curl commands are used to make the HTTP request to the URL for the bio-session capabilities.

The header data is specified with the -H option as shown in the snippet:

Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/capabilities \
3 -H 'Authorization: [APIKEY_VALUE]' \
Header Field

The HTTP header field containing metadata associated with the API request and response fields is shown below.

Field
Description
apikey (optional)APIkey value
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields below.

Field
Type
Description
versionstringThe Biometric Services version.
modesstringThe available modes that can be used for face creation (see Create face).

####### Sample Code

The sample code response for the version and modes is shown in the snippet:

JSON
1{
2 "status": "ok",
3 "currentMode": [
4 "F5_1_VID60"
5 ],
6 "acceptedModes": [
7 "F5_2_VID75",
8 "F5_1_VID60",
9 "F5_5_VID60"
10 ],
11 "version": "3.8.1"
12}
Success Response 200

The 200 status code will be returned with a description in the event of success, as shown below.

Name
Description
200The instance is up.
Error Response 500

The 500 status code will be returned with an error description if there is an issue, as shown below.

Name
Description
500The instance is not working properly.

Faces APIs 

This section describes the APIs that handle face functions.

CreateFaceFromImage API

The CreateFaceFromImage function creates a face resource from a known user's image by processing the face image on the server.

Note: No more than one face can be detected per image.

Image Requirements

  • There should be at least 60 pixels between the eyes.
  • When an image is compressed using JPEG (.jpeg/.jpg), the image quality should be 80% or higher.
Method

The POST and curl commands are used to create the face image resource.

The header data is specified with the -H option, and the paths to the multi-form images are flagged with the -F option, as shown in the snippet:

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces \
3 -H 'Content-Type: multipart/mixed' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'face=@[ABSOLUTE_LOCAL_PATH_TO_face]' \
6 -F 'image=@[ABSOLUTE_LOCAL_PATH_TO_image]'
Sample Code

A JSON image object for the API is shown in the snippet:

JSON
1{
2 "imageType": "SELFIE",
3 "friendlyName": "Presidential portrait of Barack Obama",
4 "imageRotationEnabled": false
5}
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contain metadata associated with the API request and response fields are shown in the table.

Field
Description
apikeyThe APIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data
URI Field

The URI field provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session in which to create the face.
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
faceobjectThe face JSON object
mode (optional)stringThe biometric algorithm used to create the face biometric template; allowed values: F5_2_VID75, F5_1_VID0, F5_3_VID60
imageTypestringThe kind of image; allowed values: ID_DOCUMENT, SELFIE, VIDEO_FRAME
friendlyName (optional)stringA friendly name for the face; default value: null
imageRotationEnabled (optional)BooleanThis enables image rotation for coding. Note: Do not use if the image is not rotated. For optimal performance, it's recommended to use images that are already correctly oriented rather than to use this parameter to rotate them; default value: null
imagebinaryThe face image to process
Success Response 201

If the bio-session was successful, then the response will return status code 201 and contain the Location header string of the URI for the created face image.

Field
Type
Description
LocationstringHeader containing the URI of the created face
Sample Code

The 201 Created response indicates that the bio-session was successfully created. This response also returns the Location string of the URI for the created bio-session as shown in the snippet:

HTTP
1HTTP/1.1 201 Created
2Location: /v2/bio-sessions/0991cedc-9111-4b9d-9e4e-8d6eb4db488f/faces/aa0bd6ca-1206-415b-af94-8d2c18aa9c70
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face
413The request was too big

CreateDirectFaceFromImage API

This function creates a face resource by processing a face image on the server. The face resource created is not associated with a session.

Note: No more than one face can be detected per image.

Image Requirements
  • There should be at least 60 pixels between the eyes.
  • When an image is compressed using JPEG (.jpeg/.jpg), the image quality should be 80% or higher.
Method

This method uses the POST command with curl to create the image resource on the BioServer.

The header data is specified with the -H option and the image paths are flagged with the -F option, as shown in the snippet:

1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/faces \
3 -H 'Content-Type: multipart/mixed' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'face=@[ABSOLUTE_LOCAL_PATH_TO_FACE]' \
6 -F 'image=@[ABSOLUTE_LOCAL_PATH_TO_image]' \
7 -d '{"correlationId": "891a6728-1ac4-11e7-93ae-92361f002671"}'
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyAPIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
faceobjectThe JSON object for a reference face
mode (optional)stringThe biometric algorithm used to create the face biometric template (currently the algorithm used is the one in the server configuration file) Allowed values: F5_2_VID75, F5_1_VID60, F5_3_VID60
imageTypestringThe kind of image. Allowed values: ID_DOCUMENT, SELFIE, VIDEO_FRAME
friendlyName (optional)stringA friendly name for the face. Default value: null
signatureDisabled (optional)stringDisable the signature of the result. Default value: false
imageRotationEnabled (optional)BooleanTo enable image rotation for coding. Do not use if the image is not rotated. For optimal performance, it is recommended to use images that are already correctly oriented rather than to use this parameter to rotate them. Default value: null
imagebinaryThe face image to process.
correlationId (optional)stringA custom identifier coming from the caller. Default value: null
Success Response Object 200

These fields are included in the JSON object (payload) when a success status code of 200 is returned after the face image has been successfully created.

Field
Type
Description
idstringThe face unique identifier generated by BioServer.
friendlyName (optional)stringA friendly name for the face
digest (optional)stringThe SHA-256 digest of the image file from which the face has been created for confidentiality and verification purposes
modestringThe biometric algorithm used to create the face biometric template
imageTypestringThe type of image
quality (optional)numberThe biometric template quality — a good quality template is a template with a quality superior to 100; if the quality is negative, then the face needs to be sent again
landmarks (optional)LandmarksLandmarks detected on the face
templatestringThe biometric template of the face
templateVersionnumberThe version of the biometric template; newer versions of biometric algorithms don't support the previous version of biometric templates
imageRotationEnabled (optional)BooleanImage rotation enabled; default value: null
createddatetimeThe date on which the face is created
Sample Response Payload

The following JSON object (with payload) is returned when the face image is successfully created, as shown in the snippet:

JSON
1{
2 "id": "3d069016-e66e-498e-af32-b930ba1c5067",
3 "friendlyName": "Presidential portrait of Barack Obama",
4 "digest": "8b11d3b37fcdb71da6b26d1c601c262a37b4c0f39edfbd51978cc46ace122862",
5 "mode": "F5_3_VID60",
6 "imageType": "SELFIE",
7 "quality": 295,
8 "landmarks": {"eyes": {
9 "x1": 1220.5284,
10 "y1": 1891.722,
11 "x2": 1621.1726,
12 "y2": 1873.5762
13 }},
14 "imageRotationEnabled":false,
15 "template": "EQAAAJQDAAACAAE09Uo_fRI...yJzdWIiOiJ0ZAEAAQDAAAC==",
16 "templateVersion": 113,
17 "created": "2018-10-25T14:32:48.863Z"
18}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face
413The request was too big

CreateFaceFromJson API

This function creates a face resource from a previous face JSON object by processing the face biometric template on the server.

Method

Note: This method is significantly faster than creating faces from images, but you must be careful as newer versions of biometric algorithms don't support the previous version of biometric templates.

This uses the POST and curl command to send data to the BioServer to create the face resource.

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces \
3 -H 'Content-Type: application/json' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -d '{{
6"id": "ee9b1742-06f4-4e22-8630-3852d55f314a",
7"friendlyName": "Official portrait of First Lady Michelle Obama in the Green Room of the White House",
8"digest": "20b4839d1da77fba4ed185e5a4649d1c514b101f823299c928dc43356f68b4df",
9"mode": "F5_1_VID60",
10"imageType": "SELFIE",
11"quality": 306,
12"landmarks": {
13"eyes": {
14"x1": 518.71204,
15"y1": 444.68396,
16"x2": 655.408,
17"y2": 446.599
18}
19},
20"template": "EQAAAMwDAAACA…AAAAAAAAAAAAyMIpAFAA",
21"templateVersion": 92,
22"created": "2017-11-13T13:28:24.098Z",
23"expires": "2017-11-13T13:33:24.108Z",
24"signature": "eyJhbGciOiJSUzI1NiJ9.ew0KogImFhMGJkNmNhL…ogIClbmRseU5hbWUoroAE_oxDF_ZtH-E"
25}}'
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyAPIkey value
Content-TypeAllowed values: application/json
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session in which to create the face.
Request Body Field

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
faceobjectA face JSON.
Success Response 201

If the bio-session was successfully created, then the response will return status code 201 and contain the Location header string of the URI for the created face image.

Field
Type
Description
LocationstringHeader containing the URI of the bio-session created
Sample Code

The 201 Created response indicates that the bio-session was successfully created. This response also returns the Location string of the URI for the created bio-session as shown in the snippet:

HTTP
1HTTP/1.1 201 Created
2Location: /v2/bio-sessions/0991cedc-9111-4b9d-9e4e-8d6eb4db488f/faces/aa0bd6ca-1206-415b-af94-8d2c18aa9c70
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown below.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face

GetFace API

This function retrieves a face image.

Method
Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces/{faceId} \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Field

The HTTP header fields that contains metadata associated with the API request and response fields is shown below.

Field
Description
apikeyAPIkey value
URI Fields

The URI field and related field that provides the HTTP address for the bioSessionID string identifier and the bio-session face resource are shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session containing the face.
faceIdstringThe identifier of the face resource to retrieve.
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
idstringThe face unique identifier generated by BioServer.
friendlyName (optional)stringA friendly name for the face.
digest (optional)stringThe SHA-256 digest of the image file from which the face has been created for confidentiality and verification purposes.
modestringThe biometric algorithm used to create the face biometric template.
imageTypestringThe kind of image.
quality (optional)numberThe biometric template quality. A good quality template is a template with a quality superior to 100. If the quality is negative, then the face needs to be sent again.
landmarks (optional)LandmarksLandmarks detected on the face.
templatestringThe biometric template of the face.
templateVersionnumberThe version of the biometric template Note: Newer versions of biometric algorithms don't support the previous version of biometric templates.
imageRotationEnabled (optional)BooleanImage rotation enabled. Default value: null
createddatetimeThe date on which the face is created.
expiresdatetimeThe date after which the face will expire and will be removed from the server.
signature (optional)stringA digital signature (JWS) of the response. Authentication and integrity can be verified afterward using the Biometric Services public certificate.
Sample Response Object 200

A sample success object with payload is shown in the snippet:

JSON
1{
2 "id": "aa0bd6ca-1206-415b-af94-8d2c18aa9c70",
3 "friendlyName": "Presidential portrait of Barack Obama",
4 "digest": "39bd0d9606a772b1e7076401f32f14bdde403b9608e789e0771b90fb79b664a4",
5 "mode": "F5_1_VID60",
6 "imageType": "SELFIE",
7 "quality": 295,
8 "landmarks": {
9 "eyes": {
10 "x1": 1191.4584,
11 "y1": 582.79565,
12 "x2": 1477.8955,
13 "y2": 580.3324
14 }
15 },
16 "template": "EQAAAMwDAAACA…AAAAAAAAAAAAyMIpAFAA",
17 "templateVersion": 92,
18 "created": "2017-05-18T12:39:48.987Z",
19 "expires": "2017-05-18T12:40:48.988Z",
20 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KogImFhMGJkNmNhL…ogIClbmRseU5hbWUoroAE_oxDF_ZtH-E"
21}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown below.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to retrieve the face
404Unable to find a bio-session or a face for the given identifier

GetFaceImage API

Note: This function is only possible if image storage has been enabled for the bio-session.

This function retrieves the image that has been used to create a face resource as shown in the snippet.

Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces/{faceId}/image?compression=true \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

The APIkey is the API key unique identifier that is used to authenticate requests and track and control API usage.

Header Field

The HTTP header field that contains metadata associated with the API request and response fields is shown in the table.

Name
Description
apikeyTheAPIkey value
URI Fields

The URI field and related fields that provide the HTTP address for the bioSessionID string identifier and the bio-session face resource are shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session containing the face.
faceIdstringThe identifier of the face resource for which the image needs to be retrieved.09
compression (optional)BooleanTo enable image jpeg compression. Default value: false
Success Response 200

The success status code 200 will be generated when the face image is successfully retrieved as shown in the table.

Name
Description
200The image has been successfully retrieved.
Sample Code

The 200 success response status code is shown in the snippet:

HTTP
1HTTP/1.1 200 OK
2Content-Type: image/jpeg
3(image)
Error Response 204

The 204 status code will be generated when storage is not enabled for the bio-session as shown below.

Name
Description
204Storage is not enabled for the bio-session.
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown below.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to retrieve the face image
404Unable to find a bio-session or a face for the given identifier

GetFaces API

This function retrieves the list of faces that were created in a bio-session.

Method
Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions Field

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header

The HTTP header fields that contains metadata associated with the API request and response fields is shown below.

Field
Description
apikeyAPIkey value

URI

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session.

Response (example):

JSON
1[
2 {
3 "id": "3fd2bf77-244a-4563-a6ba-70abdc14b2ee",
4 "friendlyName": "Barack Obama's Columbia University Student ID",
5 "digest": "94d1b6ff2acf368c3e0ccaebe1d8e447ed1ccd7b596dc5cac3c13a4822b256c6",
6 "mode": "F5_1_VID60",
7 "imageType": "ID_DOCUMENT",
8 "quality": 186,
9 "landmarks": {
10 "eyes": {
11 "x1": 141.83296,
12 "y1": 217.47075,
13 "x2": 241.09653,
14 "y2": 216.0568
15 }
16 },
17 "template": "EQAAAMwDAAACA…AAAAAAAAAAAAyMIpAFAA",
18 "templateVersion": 92,
19 "created": "2017-05-18T12:43:05.373Z",
20 "expires": "2017-05-18T12:44:08.132Z",
21 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAiaWQiIDog…JPKaeptOVlY4_InM6HQOm9JzFBMnzajI"
22 },
23 {
24 "id": "aa0bd6ca-1206-415b-af94-8d2c18aa9c70",
25 "friendlyName": "Presidential portrait of Barack Obama",
26 "digest": "39bd0d9606a772b1e7076401f32f14bdde403b9608e789e0771b90fb79b664a4",
27 "mode": "F5_1_VID60",
28 "imageType": "SELFIE",
29 "quality": 295,
30 "landmarks": {
31 "eyes": {
32 "x1": 1191.4584,
33 "y1": 582.79565,
34 "x2": 1477.8955,
35 "y2": 580.3324
36 }
37 },
38 "template": "EQAAAMwDAAACA…AAAAAAAAAAAAyMIpAFAA",
39 "templateVersion": 92,
40 "created": "2017-05-18T12:43:06.945Z",
41 "expires": "2017-05-18T12:44:08.132Z",
42 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KogImFhMGJkNmNhL…ogIClbmRseU5hbWUoroAE_oxDF_ZtH-E"
43 }
44]

Success 200

Name
Description
200The faces have been successfully retrieved.

Error 4xx

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to retrieve the face list
404Unable to find a bio-session for the given identifier

DeleteFace API

This function deletes a face image.

Shell
1curl -X DELETE \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces/{faceId} \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions Field

APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Field

The HTTP header field that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value

URI

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session
' / 'stringThe identifier of the face resource to delete
Success Response 204

The 204 status code will be returned when the face image has been successfully deleted.

Name
Description
204The face has been successfully deleted.
Sample Code

The sample response for the 204 status code is shown in the snippet:

HTTP
1HTTP/1.1 204 No Content
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to delete the face list
404Unable to find a bio-session or a face for the given identifier

DeleteFaces API

This function deletes the entire collection of faces in the current bio-session.

Method
Shell
1curl -X DELETE \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Field

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session.
Success Response 204

The 204 status code will be returned when the face image has been successfully deleted.

Name
Description
204The face has been successfully deleted.
Sample Code

The sample response for the 204 status code is shown in the snippet:

HTTP
1HTTP/1.1 204 No Content
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown below.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to delete the face list
404Unable to find a bio-session for the given identifier

Matches APIs 

This section discusses how to perform face image matching.

GetMatches API

This function retrieves a list of ordered matches (best scores come first) for a given face.

The reference face is compared to all the faces created in the bio-session. The result of each comparison is called a “match”. Each match is composed of the reference face, a candidate face, a matching score, and a false acceptance rate.

False Acceptance Rate

The threshold you want to avoid using is driven by the expected FAR (False Acceptance Rate).

FAR
Matching threshold
0.0001%4500
0.001%4000
0.01%3500
0.1%3000
1%2500
  • Matching Document/Selfie: The recommended threshold is 2500 or 3000.
  • Matching Selfie/Selfie: The recommended threshold is 3000, 3500, or higher depending on the use case.
Method
Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/faces/{referenceFaceId}/matches \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header

The HTTP header field that contains metadata associated with the API request and response fields is shown “.

Field
Description
apikeyAPIkey value

URI

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session containing the faces.
referenceFaceIdstringThe identifier of the reference face.

Success 200

Field
Type
Description
referenceobjectThe reference face JSON.
candidateobjectA candidate face JSON.
scorenumberThe matching score.
falseAcceptanceRatenumberThe false acceptance rate, or FAR: measure of the likelihood that the Biometric Services will incorrectly return a match when the faces do not actually belong to the same person. For instance, "100" means there is no chance the two faces belong to the same person, "0.000000000028650475" means there is almost no chance Biometric Services can be wrong.
correlationId (optional)stringA custom identifier coming from the caller and currently associated with the bio-session.
createddatetimeThe date on which the match has been created.
expiresdatetimeThe date after which the match will expire and will be removed from the server.
signature (optional)stringA digital signature (JWS) of the response. Authentication and integrity can be verified afterward using the Biometric Services public certificate.

Response (example):

JSON
1[
2 {
3 "reference": {
4 "id": "aa0bd6ca-1206-415b-af94-8d2c18aa9c70",
5 "friendlyName": "Presidential portrait of Barack Obama",
6 "digest": "39bd0d9606a772b1e7076401f32f14bdde403b9608e789e0771b90fb79b664a4",
7 "mode": "F5_1_VID60",
8 "imageType": "SELFIE",
9 "quality": 295,
10 "landmarks": {
11 "eyes": {
12 "x1": 1191.4584,
13 "y1": 582.79565,
14 "x2": 1477.8955,
15 "y2": 580.3324
16 }
17 }
18 },
19 "candidate": {
20 "id": "6e1741f1-3715-416a-bfc6-4fc381d228a3",
21 "friendlyName": "Barack Obama's Columbia University Student ID",
22 "digest": "94d1b6ff2acf368c3e0ccaebe1d8e447ed1ccd7b596dc5cac3c13a4822b256c6",
23 "mode": "F5_1_VID60",
24 "imageType": "ID_DOCUMENT",
25 "quality": 186,
26 "landmarks": {
27 "eyes": {
28 "x1": 141.83296,
29 "y1": 217.47075,
30 "x2": 241.09653,
31 "y2": 216.0568
32 }
33 }
34 },
35 "score": 7771.43408203125,
36 "falseAcceptanceRate": 0.000000000028650475616752694,
37 "correlationId": "891a6728-1ac4-11e7-93ae-92361f002671",
38 "created": "2017-05-18T12:41:09.58Z",
39 "expires": "2017-05-18T12:42:00.844Z",
40 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAicm…0NCiAgICB9DQHSQfU7Q"
41 }
42]
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to retrieve the matches
404Unable to find a bio-session or a face for the given identifier

Images Match API

This function serves a direct image match by returning a single matched object (see Get images matches) computed by two images: a reference image and a candidate image.

False Acceptance Rate

The threshold you want to avoid using is driven by the expected FAR (False Acceptance Rate).

FAR
Matching threshold
0.0001%4500
0.001%4000
0.01%3500
0.1%3000
1%2500
Thresholds

The recommended thresholds are the following:

  • Matching Document/Selfie: 2500 or 3000
  • Matching Selfie/Selfie: 3000, 3500, or higher depending on the use case
Method
Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/match/images \
3 -H 'Content-Type: multipart/form-data' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'referenceImage=@[ABSOLUTE_LOCAL_PATH_TO_referenceImage]' \
6 -F 'candidateImage=@[ABSOLUTE_LOCAL_PATH_TO_candidateImage]' \
7 -F 'referenceImageType=@[ABSOLUTE_LOCAL_PATH_TO_referenceImageType]' \
8 -F 'candidateImageType=@[ABSOLUTE_LOCAL_PATH_TO_candidateImageType]'

Permissions:

APIkey - (the API key unique identifier) - API key used to authenticate requests and track and control API usage.

Header

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data

Body

Field
Type
Description
referenceImagebinaryA reference face image to process.
candidateImagebinaryA candidate face image to process.
referenceImageTypeStringThe kind of image for the reference face. Allowed values: ID_DOCUMENT, SELFIE, VIDEO_FRAME
candidateImageTypeStringThe kind of image for the candidate face. Allowed values: ID_DOCUMENT, SELFIE, VIDEO_FRAME
correlationId (optional)stringA custom identifier coming from the caller. Default value: null
imageRotationEnabled (optional)booleanEnables image rotation for coding. Do not use if the image is not rotated. For best performance, use images that are already correctly oriented instead of using this parameter to rotate incorrectly oriented images. Default value: null

Response (example):

JSON
1{
2 "reference": {
3 "id": "31214b58-9edc-425b-9436-60dcd94fbc3a",
4 "mode": "F5_1_VID60",
5 "imageType": "SELFIE",
6 "quality": 306,
7 "landmarks": {
8 "eyes": {
9 "x1": 518.71204,
10 "y1": 444.68396,
11 "x2": 655.408,
12 "y2": 446.599
13 }
14 }
15 },
16 "candidate": {
17 "id": "7d94bbfd-b779-44a3-a8fa-dfc20324fb2b",
18 "mode": "F5_1_VID60",
19 "imageType": "SELFIE",
20 "quality": 306,
21 "landmarks": {
22 "eyes": {
23 "x1": 518.71204,
24 "y1": 444.68396,
25 "x2": 655.408,
26 "y2": 446.599
27 }
28 }
29 },
30 "score": 10269.438178710938,
31 "falseAcceptanceRate": 0.000000000000001,
32 "correlationId": "c5a0aec2-1262-41b6-82bd-e9d60da92ef2",
33 "created": "2017-11-14T14:31:42.228Z",
34 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAicmV…jQvj1G8qNqhOTbg8cWMQ1k_5F-GQTnco"
35}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face
413The request was too big

Match API

This function returns a direct match by returning a single match object (see ) that was computed from a reference face (i.e., a previous face JSON) and a candidate's face image.

False Acceptance Rate

The threshold you should avoid using is driven by the expected FAR (False Acceptance Rate) as shown in the table.

FAR
Matching threshold
0.0001%4500
0.001%4000
0.01%3500
0.1%3000
1%2500
Thresholds

The following thresholds are recommended:

  • Matching Document/Selfie: The recommended threshold is 2500 or 3000.
  • Matching Selfie/Selfie: The recommended threshold is 3000, 3500, or higher depending on the use case.
Method

This command uses POST and curl to….

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/match \
3 -H 'Content-Type: multipart/form-data' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'candidateImage=@[ABSOLUTE_LOCAL_PATH_TO_candidateImage]' \
6 -F 'candidateImageType=@[ABSOLUTE_LOCAL_PATH_TO_candidateImageType]' \
7 -d '[{
8 "id": "ee9b1742-06f4-4e22-8630-3852d55f314a",
9 "friendlyName": "Official portrait of First Lady Michelle Obama in the Green Room of the White House",
10 "digest": "20b4839d1da77fba4ed185e5a4649d1c514b101f823299c928dc43356f68b4df",
11 "mode": "F5_1_VID60",
12 "imageType": "SELFIE",
13 "quality": 306,
14 "landmarks": {
15 "eyes": {
16 "x1": 518.71204,
17 "y1": 444.68396,
18 "x2": 655.408,
19 "y2": 446.599
20 }
21 },
22 "template": "EQAAAMwDAAACA…AAAAAAAAAAAAyMIpAFAA",
23 "templateVersion": 92,
24 "created": "2017-11-13T13:28:24.098Z",
25 "expires": "2017-11-13T13:33:24.108Z",
26 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KogImFhMGJkNmNhL…ogIClbmRseU5hbWUoroAE_oxDF_ZtH-E"
27 }]'
Permissions

TheAPIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyAPIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
candidateImagebinaryA candidate face image to process.
candidateImageTypeStringThe kind of image for the candidate face. Allowed values: ID_DOCUMENT, SELFIE, VIDEO_FRAME
referenceFaceobjectA reference face JSON.
imageRotationEnabled (optional)booleanTo enable image rotation for coding. Do not use if the image is not rotated. For best performance, use images that are already correctly oriented instead of using this parameter to rotate incorrectly oriented images. Default value: null
correlationId (optional)stringA custom identifier coming from the caller. Default value: null

Response (example):

JSON
1{
2 "reference": {
3 "id": "31214b58-9edc-425b-9436-60dcd94fbc3a",
4 "friendlyName": "Official portrait of First Lady Michelle Obama in the Green Room of the White House",
5 "mode": "F5_1_VID60",
6 "imageType": "SELFIE"
7 },
8 "candidate": {
9 "id": "7d94bbfd-b779-44a3-a8fa-dfc20324fb2b",
10 "mode": "F5_1_VID60",
11 "imageType": "SELFIE",
12 "quality": 306,
13 "imageRotationEnabled":false
14 "landmarks": {
15 "eyes": {
16 "x1": 518.71204,
17 "y1": 444.68396,
18 "x2": 655.408,
19 "y2": 446.599
20 }
21 }
22 },
23 "score": 10269.438178710938,
24 "falseAcceptanceRate": 0.000000000000001,
25 "correlationId": "c5a0aec2-1262-41b6-82bd-e9d60da92ef2",
26 "created": "2017-11-14T14:31:42.228Z",
27 "signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAicmV…jQvj1G8qNqhOTbg8cWMQ1k_5F-GQTnco"
28}

Error 4xx

Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face
413The request was too big

Replay Liveness APIs 

This section discusses APIs for replaying liveness.

initLivenessParameters

This function posts the liveness parameter(s) that will be used to run the challenge.

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v2/bio-sessions/{bioSessionId}/init-liveness-parameters \
3 -H 'Content-Type: application/json' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -d '[{
6 "type": "LIVENESS_PASSIVE"
7 }]'
Permissions

The APIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
Content-TypeAllowed values: application/json

URI

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session containing the livenessParameter.
Request Body Fields

The request body is used to create the resource information returned by the API. It contains the representation of the resource to be created as shown in the fields in the table.

Field
Type
Description
typestringLiveness type. Allowed values: NO_LIVENESS, LIVENESS_MEDIUM, LIVENESS_HIGH, LIVENESS_PASSIVE, LIVENESS_PASSIVE_VIDEO.
securityLevel (optional)stringSpecify the level of security. Higher level makes a smaller target. Allowed values: LOW, MEDIUM,HIGH. By default value is set to HIGH.
nbChallenge (optional)numberNumber of challenges to ask. Must be one or greater. Only used with LIVENESS_HIGH
imageRetrievalDisabled (optional)booleanRetrieve the best image with the liveness result. By default value is true. Images are not available
Sample Request
JSON
1{
2 "type": "LIVENESS_PASSIVE_VIDEO",
3 "securityLevel": "HIGH"
4}
JSON
1{
2 "type": "LIVENESS_HIGH",
3 "securityLevel": "MEDIUM",
4 "nbChallenge": 2,
5 "imageRetrievalDisabled": false
6}
Response Body Fields
Field
Type
Description
signature (optional)stringA digital signature (JWS) of the response. Authentication and integrity can be verified afterward using the BioServer public certificate
id (optional)stringOperation identifier
type (optional)stringLiveness type. Allowed values: NO_LIVENESS, LIVENESS_MEDIUM, LIVENESS_HIGH, LIVENESS_PASSIVE, LIVENESS_PASSIVE_VIDEO
securityLevel (optional)stringSpecify the level of security. Higher level makes a smaller target. Allowed values: LOW, MEDIUM,HIGH. By default value is set to HIGH.
nbChallenge (optional)integerNumber of challenges to ask. Must be one or greater. Only used with LIVENESS_HIGH
useAccurateMatch (optional)booleanDeprecated.
matchThreshold (optional)integerDeprecated.
logLevel (optional)stringDeprecated.
imageRetrievalDisabled (optional)booleanRetrieve the best image with the liveness result.
seedintergerSeed generated by the server used to run the challenge
certificatearrayList of Base64 encoded certificates in DER format. It is used to encrypt data sent to the server
serverRandomstringRandom 32 bytes string generated by the server. It is used to check the encrypted data sent to the server
Sample Response
JSON
1{
2 "signature": "eyJl5V1E5Tm1TS21",
3 "id": "c672be72-89c1-4035-b0b6-9e9afa6bc85b",
4 "type": "LIVENESS_PASSIVE_VIDEO",
5 "securityLevel": "HIGH",
6 "seed": 1150867590,
7 "certificates": ["MIIEATCCAumgAwIBAgICC"],
8 "serverRandom": "avf0FHLahDrdfdseUI1fdfyo81HR4="
9}
JSON
1{
2 "signature": "eyJl5V1E5Tm1TS21",
3 "id": "c672be72-89c1-4035-b0b6-9e9afa6bc85b",
4 "type": "LIVENESS_HIGH",
5 "securityLevel": "HIGH",
6 "nbChallenge": 2,
7 "useAccurateMatch": true,
8 "matchThreshold": 2500,
9 "logLevel": "DEBUG",
10 "imageRetrievalDisabled": false,
11 "seed": 1150867590,
12 "certificates": ["MIIEATCCAumgAwIBAgICC"],
13 "serverRandom": "avf0FHLahDrdfdseUI1fdfyo81HR4="
14}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Forbidden
404Unable to find a bio-session for the given identifier

replayLivenessMetadata (v2) - Deprecated

Deprecated

getReplayStatus (v2) - Deprecated

Deprecated

prepareLivenessMetadata (v3)

This function will post replay liveness from the mobile challenge metadata.

Method

This function uses the POST and curl commands to create the resource on the server.

The header is flagged with -H, along with the -F flag for the input form data that contains the path to the encrypted data, as shown in the snippet:

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v3/bio-sessions/{bioSessionId}/prepare-liveness-metadata \
3 -H 'Content-Type: multipart/form-data' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'encryptedDeviceId=@[ABSOLUTE_LOCAL_PATH_TO_encryptedDeviceId]' \
6 -F 'encryptedMasterSecret=@[ABSOLUTE_LOCAL_PATH_TO_encryptedMasterSecret]' \
7 -F 'livenessDeviceInfo=@[ABSOLUTE_LOCAL_PATH_TO_livenessDeviceInfo]'

The sample code for the device information is shown in the snippet:

Language not specified
1{"deviceModel" : "Samsung GS7 SM-G930F","osType" : "Android","osVersion": "7.1"}
Permissions

The APIkey is the the API key unique identifier) used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session in which to create the face.
Request Body Fields

The API request body fields containing the body parameter fields are shown in the table.

Field
Type
Description
encryptedDeviceIdbinaryThe encrypted device id. Must be different than NULL.
encryptedMasterSecretbinaryThe client-side key encrypted with the Biometric Services public key provided with the liveness parameters. This key is used on the client side to encrypt the challenge metadata.
livenessDeviceInfoobjectMobile information JSON.

Here the details for 'livenessDeviceInfo' :

Field
Type
Description
osTypestringMobile OS type (Android or iOS).
osVersionstringVersion of phone OS, for example: 7.0.
deviceModelstringThe phone model, for example: Samsung Galaxy S7 Edge SM-G935F, iPhone 7 A1778
Success Response 200

If the replay liveness preparation was successfully, then the response will return status code 200.

Field
Type
Description
deviceIdSignaturestringThe is a HMAC of the (decrypted) deviceId field. It proves to the mobile SDK that the server knows the session keys, and the request has not been tampered by an attacker. It is strongly recommended to check the deviceIdSignature. If the signature could not be verified, the mobile SDK must abort the process without calling 'replay-liveness-metadata' API.
signature (optional)stringSignature of the response. It can be disabled by configuration. Standard mechanism returned by server responses
HTTP
1HTTP/1.1 200 OK
2{
3"deviceIdSignature": "w0KICAiaWQiIeyJhbGciOiJSUzI1NiJ9",
4"signature": "eyJhbGciOiJSUzI1NiJ9.ew0KICAiaWQiIDogIjA5OTFjZ…vtmiJGc"
5}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Forbidden
404Unable to find a bio-session for the given identifier
413The request was too big
429User is blocked because of max attempts reached

Error detail is described in the body response :

Field
Type
Description
idstringError identifier
messagestringMessage description
HTTP
1HTTP/1.1 4xx
2{
3 "id": "{id}",
4 "message": "Error message",
5}
Error Responses 429

If User is blocked because of max attempts reached, then the response will return code 429.

Field
Type
Description
idstringError identifier
messagestringMessage description
unlockDateTimedateDate when user will be unlocked. During this period of time, user cannot process ‘prepare-liveness-metadata’ or 'replay-liveness-metadata'.
HTTP
1HTTP/1.1 429 Too Many Requests
2{
3 "id": "{id}",
4 "message": "Maximum attempts reached",
5 "unlockDateTime": "2021-01-14T14:30:05.643Z"
6}

replayLivenessMetadata (v3)

This function will post replay liveness from the mobile challenge metadata.

Method

This function uses the POST and curl commands to create the resource on the server.

The header is flagged with -H, along with the -F flag for the input form data that contains the path to the encrypted data, as shown in the snippet:

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/bioserver-app/v3/bio-sessions/{bioSessionId}/replay-liveness-metadata \
3 -H 'Content-Type: multipart/form-data' \
4 -H 'apikey: [APIKEY_VALUE]' \
5 -F 'encryptedMetaData=@[ABSOLUTE_LOCAL_PATH_TO_encryptedMetaData]'
Permissions

The APIkey is the the API key unique identifier) used to authenticate requests and track and control API usage.

Header Fields

The HTTP header fields that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
Content-TypeAllowed values: multipart/mixed, multipart/form-data
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session in which to create the face.
Request Body Fields

The API request body fields containing the body parameter fields are shown in the table.

Field
Type
Description
encryptedMetaDatabinaryThe encrypted challenge metadata binary. Must be different than NULL.
Success Response 202

If the bio-session was successfully created, then the response will return status code 202.

Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Forbidden
404Unable to find a bio-session for the given identifier
413The request was too big

Error detail is described in the body response :

Field
Type
Description
idstringError identifier
messagestringMessage description
HTTP
1HTTP/1.1 4xx
2{
3 "id": "{id}",
4 "message": "Error message",
5}

getReplayStatus (v3)

This function retrieves a challenge replay response.

Method
Shell
1curl -X GET \
2 https://[URL_MAIN_PART]/bioserver-app/v3/bio-sessions/{bioSessionId}/replay-liveness-metadata \
3 -H 'apikey: [APIKEY_VALUE]' \
Permissions

TheAPIkey is the API key unique identifier used to authenticate requests and track and control API usage.

Header Field

The HTTP header field that contains metadata associated with the API request and response fields is shown in the table.

Field
Description
apikeyThe APIkey value
URI Field

The URI field that provides the HTTP address where the bioSessionID string identifier for the bio-session resource can be retrieved is shown in the table.

Field
Type
Description
bioSessionIdstringThe identifier of the bio-session resource to retrieve.
Success Response Object 200
Field
Type
Description
statusstringLiveness challenge response. Allowed values: INITIALIZED, IN_PROGRESS, ERROR, SUCCESS, FAILED, SPOOF, TIMEOUT
signature (optional)stringA digital signature (JWS) of the response with detached payload to avoid duplication of the image. Authentication and integrity can be verified afterward using the Biometric Services public certificate JWS = HEADER.PAYLOAD.SIGNATURE. The JWS payload has to be reconstructed from the trimmed response (without signature filed).
image (optional)stringBest image from replay liveness (Base64-encoded).
landmarks (optional)LandmarksLandmarks detected on the face.
Sample Response Payload

The following JSON payload is an example reponse when the liveness is still in processing.

JSON
1{
2 "signature": "eyJhbGciOiJSUzI1NiJ9..ciOeyJhiJSmRseU5hbWogIClbmRseU5hbWUoroAE_oxDF_ZtH-E",
3 "status": "IN_PROGRESS"
4}

The following JSON payload is an example reponse when the face image is successfully created.

JSON
1{
2 "signature": "eyJhbGciOiJSUzI1NiJ9..ciOeyJhiJSmRseU5hbWogIClbmRseU5hbWUoroAE_oxDF_ZtH-E",
3 "status": "SUCCESS",
4 "image":"F401MTb6QMNy8VFDMYDJ0dBQZepKDeHbTTCXRGaL+gFOCAomRITeZeJoQG3+CU2YNT2JXVzVgcZWD5LQNASqJA==",
5 "landmarks": {
6 "eyes": {
7 "x1": 581.0,
8 "y1": 270.0,
9 "x2": 695.0,
10 "y2": 266.0
11 },
12 "box": {
13 "x": 465,
14 "y": 149,
15 "width": 348,
16 "height": 348
17 }
18 }
19}

The following JSON payload is an example reponse when the liveness returns a SPOOF.

JSON
1{
2 "signature": "eyJhbGciOiJSUzI1NiJ9..ciOeyJhiJSmRseU5hbWogIClbmRseU5hbWUoroAE_oxDF_ZtH-E",
3 "status": "SPOOF"
4}
Error Responses 4xx

If an error occurs, one of the 4xx status codes will be generated. The error response code indicates the specific error type and the error code issue as shown in the table.

Name
Description
400Something is wrong with the request
401Authentication is required
403Forbidden
404Unable to find a bio-session for the given identifier

Objects

Landmarks

The Landmarks object describes the Landmarks detected on the face.

Parameters

The parameters for Landmarks are shown in the table.

Name
Type
Description
eyes (optional)LandmarksEyesEye detection information
box (optional)LandmarksBoxFace position inside a box
Example usage

An example usage for DocumentSideRules is shown in the snippet"

JSON
1{
2 "eyes": {
3 "x1": 581.0,
4 "y1": 270.0,
5 "x2": 695.0,
6 "y2": 266.0
7 },
8 "box": {
9 "x": 465,
10 "y": 149,
11 "width": 348,
12 "height": 348
13 }
14}

LandmarksEyes

The LandmarksEyes object describes the eye detection information

Parameters

The parameters for LandmarksEyes are shown in the table.

Name
Type
Description
x1numberThe x-coordinate of the first eye
y1numberThe y-coordinate of the first eye
x2numberThe x-coordinate of the second eye
y2numberThe y-coordinate of the second eye
Example usage

An example usage for LandmarksEyes is shown in the snippet"

JSON
1{
2 "x1": 581.0,
3 "y1": 270.0,
4 "x2": 695.0,
5 "y2": 266.0
6}

LandmarksBox

The LandmarksBox object describes the face position inside a box

Parameters

The parameters for LandmarksBox are shown in the table.

Name
Type
Description
xnumberThe x-coordinate of the left corner
ynumberThe y-coordinate of the left corner
widthnumberThe width of the box
heightnumberThe height of the box
Example usage

An example usage for LandmarksBox is shown in the snippet"

JSON
1{
2 "x": 465,
3 "y": 149,
4 "width": 348,
5 "height": 348
6}

FAQ 

How do I validate a signature from JSON responses ? 

Signatures are JWT signatures.

As an example you can use an online tool to verify the signature from JSON response: https://jwt.io/ There are two inputs required:

  • The content of the signature attribute
  • The public key from Biometric service
APIGuide SignatureValidation

Note: Also, you can verify the signature of JSON response programmatically according to the technology you use.