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.

HealthCheck / Monitoring / Capabilities API 

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.

Endpoint

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 Fields

The HTTP header fields 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.
currentModeArrayThe available modes used for face creation.
Response Example

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

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

JSON
1{
2 "currentMode": ["F5_1_VID60"],
3 "version": "3.21.0"
4}
HTTP Error Codes

Below are the status codes and descriptions that will be returned if the getCapabilities request generates an error.

Name
Description
401Authentication is required
404The instance is not working properly.
500The instance is not working properly.

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.

Endpoint

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": "891a6728-1ac4-11e7-93ae-92361f002671",
7"callbackURL": "https://service/callback"
8}]'
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

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
HTTP Error Codes

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
500Internal error

GetBioSession API

The GetBioSession API retrieves information about the bio-session.

Endpoint

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 Fields

The HTTP header fields 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
Response 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}
HTTP 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
500Internal error

DeleteBioSession API

This function deletes a session

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

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
URI Field
Field
Type
Description
bioSessionIdStringThe identifier of the bio-session
Response Example

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

Name
Description
204The session has been successfully deleted.

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

HTTP
1HTTP/1.1 204 No Content
HTTP Error Codes

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
401Authentication is required
404Unable to find a bio-session for the given identifier
409There is replay liveness in progress
500Internal error

Faces APIs 

This section describes the APIs that handle face functions.

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.
Endpoint

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]'

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
faceFaceFace details
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
Response Example

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

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
HTTP Error Codes

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
500Internal error

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.
Endpoint

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:

Shell
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"}'

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 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
faceFaceReference 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
Response Example

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": {
9 "eyes": {
10 "x1": 1220.5284,
11 "y1": 1891.722,
12 "x2": 1621.1726,
13 "y2": 1873.5762
14 }
15 },
16 "imageRotationEnabled": false,
17 "template": "EQAAAJQDAAACAAE09Uo_fRI...yJzdWIiOiJ0ZAEAAQDAAAC==",
18 "templateVersion": 113,
19 "created": "2018-10-25T14:32:48.863Z"
20}
HTTP Error Codes

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
500Internal error

CreateFaceFromJson API

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

Endpoint

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
faceFaceFace details.
Response Body Fields

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
Response Example

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
HTTP Error Codes

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
500Internal error

GetFace API

This function retrieves a face image.

Endpoint
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 Fields

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.
Response Body Fields

The 200 http code response indicates that the request is successful. 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.
Response Example

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}
HTTP Error Codes

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
500Internal error

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 Fields

The HTTP header fields 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.
compression (optional)BooleanTo enable image jpeg compression. Default value: false
Response Example

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

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

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

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

Name
Description
200The image has been successfully retrieved.
204Storage is not enabled for the bio-session.
HTTP Error Codes

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
500Internal error

GetFaces API

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

Endpoint
Shell
1curl -X GET \
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 Fields

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

Field
Description
apikeyAPIkey value
URI Field
Field
Type
Description
bioSessionIdStringThe identifier of the bio-session.
Response Example

The success status code 200 means the faces have been successfully retrieved.

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]
HTTP Error Codes
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
500Internal error

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

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
URI Field
Field
Type
Description
bioSessionIdStringThe identifier of the bio-session
Response Example

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

Name
Description
204The face has been successfully deleted.

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

HTTP
1HTTP/1.1 204 No Content
HTTP Error Codes

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
500Internal error

DeleteFaces API

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

Endpoint
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 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
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.
Response Example

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

Name
Description
204The face has been successfully deleted.

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

HTTP
1HTTP/1.1 204 No Content
HTTP Error Codes

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
500Internal error

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 3000.
  • Matching Selfie/Selfie: The recommended threshold is 3500.
Endpoint
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 Fields

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

Field
Description
apikeyAPIkey value
URI Field
Field
Type
Description
bioSessionIdStringThe identifier of the bio-session containing the faces.
referenceFaceIdStringThe identifier of the reference face.
Response Body Fields
Field
Type
Description
referenceFaceReference face.
candidateFaceCandidate face.
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

The success status code 200 means the match results have been successfully retrieved.

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]
HTTP Error Codes

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
500Internal error

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: The recommended threshold 3000.
  • Matching Selfie/Selfie: The recommended threshold is 3500.
Endpoint
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 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
Request Body Fields
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

The success status code 200 means the match results have been successfully retrieved.

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}
HTTP Error Codes

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
500Internal error

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 3000.
  • Matching Selfie/Selfie: The recommended threshold is 3500.
Endpoint
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="SELFIE"' \
7 --F 'referenceFace=@[ABSOLUTE_LOCAL_PATH_TO_referenceFace]' \
8 --F 'imageRotationEnabled="true"' \
9 --F 'correlationId="c5a0aec2-1262-41b6-82bd-e9d60da92ef2"
10 '
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
referenceFaceFaceReference face.
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

The success status code 200 means the match result has been successfully retrieved.

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}
HTTP Error Codes
Name
Description
400Something is wrong with the request
401Authentication is required
403Missing permissions to create the face
413The request was too big
500Internal error

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.

Endpoint
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
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: LIVENESS_ACTIVE, LIVENESS_PASSIVE, LIVENESS_PASSIVE_VIDEO. NO_LIVENESS and LIVENESS_MEDIUM are not supported anymore. LIVENESS_HIGH is now deprecated, please use LIVENESS_ACTIVE instead. Recommendation: LIVENESS_PASSIVE_VIDEO mode.
securityLevel (optional)StringThe security level applied on fraud detection. The higher the level, the stricter the fraud verification. Allowed values: LOW, MEDIUM,HIGH. Recommendation: HIGHlevel for all liveness modes. By default value is set to HIGH
nbChallenge (optional)NumberNumber of challenges to ask. Must be one or greater. Only used with LIVENESS_ACTIVE
imageRetrievalDisabled (optional)BooleanRetrieve the best image with the liveness result. By default value is true.
id (optional)StringThe replay liveness identifier used to correlate responses of the replay liveness process

Examples :

  • Passive video liveness
JSON
1{
2 "type": "LIVENESS_PASSIVE_VIDEO",
3 "securityLevel": "HIGH",
4 "id": "replay-id"
5}
  • Active liveness
JSON
1{
2 "type": "LIVENESS_ACTIVE",
3 "securityLevel": "HIGH",
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
idStringThe replay liveness identifier (automatically generated if not provided in the request)
typeStringLiveness type. Allowed values: LIVENESS_ACTIVE, LIVENESS_PASSIVE, LIVENESS_PASSIVE_VIDEO. NO_LIVENESS and LIVENESS_MEDIUM are not supported anymore. LIVENESS_HIGH is now deprecated, please use LIVENESS_ACTIVE instead. Recommendation: LIVENESS_PASSIVE_VIDEO mode.
securityLevelStringThe security level applied on fraud detection. The higher the level, the stricter the fraud verification. Allowed values: LOW, MEDIUM,HIGH. Recommendation: HIGHlevel for all liveness modes. By default value is set to HIGH
nbChallengeIntegerNumber of challenges to ask. Must be one or greater. Only used with LIVENESS_ACTIVE
useAccurateMatchBooleanDeprecated.
matchThresholdIntegerDeprecated.
logLevelStringDeprecated.
imageRetrievalDisabledBooleanRetrieve 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
Response Example
  • Passive video liveness
JSON
1{
2 "signature": "eyJl5V1E5Tm1TS21",
3 "id": "replay-id",
4 "type": "LIVENESS_PASSIVE_VIDEO",
5 "securityLevel": "HIGH",
6 "seed": 1150867590,
7 "certificates": ["MIIEATCCAumgAwIBAgICC"],
8 "serverRandom": "avf0FHLahDrdfdseUI1fdfyo81HR4="
9}
  • Active liveness
JSON
1{
2 "signature": "eyJl5V1E5Tm1TS21",
3 "id": "c672be72-89c1-4035-b0b6-9e9afa6bc85b",
4 "type": "LIVENESS_ACTIVE",
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}
HTTP Error Codes

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
500Internal error

getReplayStatus (v2) - Deprecated

Deprecated

replayLivenessCallback

WebCapture SDK uses the callbackURL, if provided, within [CreateBioSession API](#createbiosession API) to POST sessionId to the Service Provider (SP), as shown in the snippet:

Endpoint
HTTP
1POST https://service-provider-domain/callback-url
Request Body Fields

The parameters for are shown in the table.

Name
Type
Description
sessionIdStringThe identifier of the session
Request Example
JSON
1{
2 "sessionId": "7b4e38f6-de53-4dd5-a8b8-985833f771d2"
3}
Response Example

The success HTTP code expected from the backend is 200 :

HTTP Code
Description
200Request sent to the service provider
HTTP Error Codes

The error response codes for CallbackSP are shown in the table.

Code
Description
404Unable to reach the endpoint
500Server error

getReplayStatus (v3)

This function retrieves a challenge replay response.

Endpoint
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 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
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.
Response Body Fields

The success status code 200 means the results have been successfully retrieved.

Field
Type
Description
idStringThe replay liveness identifier as returned in response of /init-liveness-parameters
statusStringLiveness challenge response. Allowed values: INITIALIZED, IN_PROGRESS, ERROR, SUCCESS, FAILED, SPOOF, TIMEOUT
image (optional)StringBest image from replay liveness (Base64-encoded).
landmarks (optional)LandmarksLandmarks detected on the face.
signature (optional)StringA digital signature (JWS) of the response. If the image field is present, the payload is detached; the JWS payload has to be reconstructed from the trimmed JSON response (without the signature field). Authentication and integrity can be verified afterward using the Biometric Services public certificate.
deviceInfo (optional)DeviceInfoMobile information from nativeSDK.
sdkInfo (optional)SdkInfoSDK information from nativeSDK.
imageStorage (optional)ImageStorageStorage information regarding the best image. This field is not linked to imageRetrievalDisabled field.
videoStorage (optional)VideoStorageIf the video recording is enabled on AWS S3, storage information regarding the video generated is available only if the feature is enabled on the backend configuration
Response Example

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

JSON
1{
2 "signature": "eyJhbGciOiJSUzI1NiJ9..ciOeyJhiJSmRseU5hbWogIClbmRseU5hbWUoroAE_oxDF_ZtH-E",
3 "id": "c672be72-89c1-4035-b0b6-9e9afa6bc85b",
4 "status": "IN_PROGRESS"
5}

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

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

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

JSON
1{
2 "signature": "eyJhbGciOiJSUzI1NiJ9..ciOeyJhiJSmRseU5hbWogIClbmRseU5hbWUoroAE_oxDF_ZtH-E",
3 "id": "c672be72-89c1-4035-b0b6-9e9afa6bc85b",
4 "status": "SPOOF"
5}
HTTP Error Codes

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
500Internal error

Objects

Face

The Face object describes face characteristics.

Parameters

The parameters for Face are shown in the table.

Field
Type
Description
idStringThe face unique identifier generated
friendlyName (optional)StringFriendly name for the face
digest (optional)StringSHA-256 digest of the image file from which the face has been created for confidentiality and verification purposes
modeStringBiometric algorithm used to create the face biometric template
imageTypeStringImage type
quality (optional)NumberBiometric 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
template (optional)StringBiometric template of the face
templateVersion (optional)NumberVersion 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
created (optional)DatetimeThe date on which the face is created
Example usage

An example usage for Landmarks is shown in the snippet"

JSON
1{
2 "id": "6e1741f1-3715-416a-bfc6-4fc381d228a3",
3 "friendlyName": "Barack Obama's Columbia University Student ID",
4 "digest": "94d1b6ff2acf368c3e0ccaebe1d8e447ed1ccd7b596dc5cac3c13a4822b256c6",
5 "mode": "F5_1_VID60",
6 "imageType": "ID_DOCUMENT",
7 "quality": 186,
8 "landmarks": {
9 "eyes": {
10 "x1": 141.83296,
11 "y1": 217.47075,
12 "x2": 241.09653,
13 "y2": 216.0568
14 }
15 }
16}

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 Landmarks 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}

VideoStorage

The VideoStorage object describes the storage information of the recorded video of the document captured if the video recording is enabled on AWS S3, as shown in the snippet:

Parameters

The parameters for VideoStorage are shown in the table.

Name
Type
Description
regionStringRegion (S3, Minio) where the media is stored.
keyStringPath (S3, Minio) where the media is storied.
bucketNameStringBucket (S3, Minio) where the media is stored.
hashStringHash of the stored media.
hashAlgorithmStringHash algorithm used to hash the data.
contentTypeStringContent type of the media.
Example usage

An example usage for VideoStorage is shown in the snippet:

JSON
1{
2 "region": "eu-central-1",
3 "bucketName": "wbs-video-storage",
4 "key": "doc-dev/11b57ca2-7798-4c9d-8ab9-3099506d221e/0dec15a2-0ea1-49b2-baf0-812048f9e6da.webm",
5 "hash": "d32c4ff2770a4f9d4d10d048492dbb456fb153153db5ae5f1454d1442d488093",
6 "hashAlgorithm": "SHA_256",
7 "contentType": "video/webm"
8}

ImageStorage

The ImageStorage object describes the storage information of the best image of a document side.

Parameters

The parameters for ImageStorage are shown in the table.

Name
Type
Description
regionStringRegion (S3, Minio) where the media is stored.
keyStringPath (S3, Minio) where the media is storied.
bucketNameStringBucket (S3, Minio) where the media is stored.
hashStringHash of the stored media.
hashAlgorithmStringHash algorithm used to hash the data. Available value is : SHA_256
contentTypeStringContent type of the media.
Example usage

An example usage for ImageStorage is shown in the snippet:

JSON
1{
2 "region": "eu-central-1",
3 "bucketName": "wbs-video-storage",
4 "key": "doc-dev/11b57ca2-7798-4c9d-8ab9-3099506d221e/0dec15a2-0ea1-49b2-baf0-812048f9e6da.png",
5 "hash": "ff2c4ff2770a4f004dffd048492dbb_ç6fb153153db5ae5f1454d1442d4880(è",
6 "hashAlgorithm": "SHA_256",
7 "contentType": "image/png"
8}

DeviceInfo

The DeviceInfo object describes device information.

Parameters

The parameters for DeviceInfo are shown in the table.

Name
Type
Description
deviceModel (optional)StringPhone model.
osType (optional)StringMobile OS type (Android or iOS).
osVersion (optional)StringVersion of phone OS.
Example usage

An example usage for DeviceInfo is shown in the snippet:

JSON
1{
2 "deviceModel": "SM-G935F",
3 "osType": "Android",
4 "osVersion": "7.0"
5}

SdkInfo

The SdkInfo object describes sdk information.

Parameters

The parameters for SdkInfo are shown in the table.

Name
Type
Description
sdkVersion (optional)StringNative SDK version
Example usage

An example usage for SdkInfo is shown in the snippet:

JSON
1{
2 "sdkVersion": "1.0.0"
3}

FAQ 

Recommended liveness settings are :

  • Mode : LIVENESS_PASSIVE_VIDEO
  • Security level : HIGH

How do I verify 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.