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.

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.

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.

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.

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.

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.

Web Services

The following web services are involved in this scenario:

• CreateBioSession: Contains a SESSION_ID inside location header.
• 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.

Replay Challenge using NativeSDK 

This functionality enables the service to confirm a user's liveness through a Biometric challenge, conducted on a user's mobile device via an iOS or Android app integrated with NativeSDK. Termed as hybrid liveness, this process unfolds in two separate stages: the initial phase takes place on the mobile device, while the validation phase proceeds on the backend.

The primary process steps are:

1. The Service Provider (SP) asks the enduser to proceed to an offline liveness check on iOS or Android App.
2. The NativeSDK integration within the app connects with Bioserver to retrieve capture parameters.
3. The enduser proceed to the offline check.
4. Result from the check is sent automatically to Bioserver.
5. Bioserver replays the liveness scenario on backend and validates the liveness.
6. The liveness response is returned to the SP app.

Web Services

The following web services are involved in this scenario:

• CreateBioSession: Contains a SESSION_ID inside location header
• 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

API Workflow Diagram

A diagram of the Replay challenge process is shown below.

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": "a5ac0455-8d99-4d73-835c-c656b5aba41e",
3    "message": "Session not found"
4}

Managing Backpressure During High Demand 

When our platform experiences peak traffic, attempts to process a replay liveness or coding/matching operation might result in a 429 Too Many Requests HTTP response. This indicates our current request volume exceeds the server's processing capacity. Our system automatically scales to increase capacity, but this scaling requires a brief period to complete.

Key Advice for Handling 429 Responses :

• Prompt User Notification: Inform users of the high demand affecting the system and suggest they retry their request after a brief interval.

Recommended Message for Users :

"We're currently managing increased traffic and are working to accommodate all requests. Please try again shortly. Thank you for your patience."

This approach helps navigate the challenges of backpressure, ensuring users are aware of the current state and know to retry their requests after a short pause.

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 'apikey: [APIKEY_VALUE]'

Header Fields

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

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.

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": ["F6_4_VID60X"],
3  "version": "3.32.0"
4}

HTTP Error Codes

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

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. This API will return a 201 HTTP code with a location header that contains the SESSION_ID to use in every requests related to this 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.

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.

Response Example

The 201 status code indicates that the bio-session was successfully created. It also return a Location header of the URI to use for future requests related to the created session. This URI contains the created SESSION_ID.

An example success snippet is shown below:

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

In order to extract SESSION_ID, we can use a regex to remove the everything before the uuid (example of regex : "^.*/(.*)").

On the previous example, we have SESSION_ID = 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.

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.

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.

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.

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.

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.

URI Field

Response Example

The 204 status code will be returned when the face image 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.

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.

URI Field

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

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.

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.

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.

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.

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.

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": 1202,
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.

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": "F6_4_VID60X",
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": 1202,
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.

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.

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.

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.

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.

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.

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.

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.

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": "F6_4_VID60X",
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": "EQAAAOwCAAACAAEAEAAAAAQAAABBTFAy",
17  "templateVersion": 1202,
18  "created": "2024-10-03T12:24:09.923Z",
19  "expires":  "2024-10-03T12:54:04.744Z",
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.

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.

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.

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.

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.

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.

URI Field

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": "F6_4_VID60X",
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": 1202,
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": "F6_4_VID60X",
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": 1202,
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

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.

URI Field

Response Example

The 204 status code will be returned when the face image 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.

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.

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.

Response Example

The 204 status code will be returned when the face image 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.

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

Recommended Threshold

• Matching Document/Selfie: The recommended threshold 3500 (ie FAR 0.01%).
• Matching Selfie/Selfie: The recommended threshold is 4000 (ie FAR 0.001%).

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

URI Field

Response Body Fields

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": "F6_4_VID60X",
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": "F6_4_VID60X",
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.

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

Thresholds

The recommended thresholds are the following:

• Matching Document/Selfie: The recommended threshold 3500 (ie FAR 0.01%).
• Matching Selfie/Selfie: The recommended threshold is 4000 (ie FAR 0.001%).

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.

Request Body Fields

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": "F6_4_VID60X",
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": "F6_4_VID60X",
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.

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.

Thresholds

The following thresholds are recommended:

• Matching Document/Selfie: The recommended threshold 3500 (ie FAR 0.01%).
• Matching Selfie/Selfie: The recommended threshold is 4000 (ie FAR 0.001%).

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

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.

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.

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": "F6_4_VID60X",
6        "imageType": "SELFIE"
7    },
8    "candidate": {
9        "id": "7d94bbfd-b779-44a3-a8fa-dfc20324fb2b",
10        "mode": "F6_4_VID60X",
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

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.

URI Field

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.

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

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  "imageRetrievalDisabled": false,
8  "seed": 1150867590,
9  "certificates": ["MIIEATCCAumgAwIBAgICC"],
10  "serverRandom": "avf0FHLahDrdfdseUI1fdfyo81HR4="
11}

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.

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.

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

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

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.

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.

Response Body Fields

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

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.

Ages APIs (Beta) 

This section discusses APIs for age estimation.

createDirectAgeFromImage

This function computes an estimation of the age of the person given as input. Under the response, it also indicates if the estimated age is above or equal to the input threshold

Endpoint

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/bioserver-app/v2/ages \
3  -H 'Content-Type: multipart/form-data' \
4  -H 'apikey: [APIKEY_VALUE]' \
5  -F 'image=@[ABSOLUTE_LOCAL_PATH_TO_image]' \
6  -F 'age=@[ABSOLUTE_LOCAL_PATH_TO_age_json]' \
7  -F 'correlationId="c5a0aec2-1262-41b6-82bd-e9d60da92ef2"'

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.

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.

Response Body Fields

Response Example

• Nominal output

JSON
1{
2  "id": "305e113e-b8cd-4d84-a43d-f3d2c79c22b3",
3  "aboveThreshold": true,
4  "ageEstimated": 23.1,
5  "threshold": 18,
6  "digest": "94d1b6ff2acf368c3e0ccaebe1d8e447ed1ccd7b596dc5cac3c13a4822b256c6",
7  "imageType": "SELFIE",
8  "quality": 212,
9  "created": "2024-06-24T14:38:17.972Z",
10  "signature": "eyJhbGciOiJFUzI1"
11}

• No person detected

JSON
1{
2  "id": "b6d18093-761a-41b8-8dd9-8e4268d1782e",
3  "threshold": 18,
4  "digest": "44ef3f8eac461453721b8463a9edaa37e77f5f2f421edd8a449d55119d76b6f2",
5  "imageType": "SELFIE",
6  "quality": -10000,
7  "created": "2024-06-24T14:37:23.801Z",
8  "signature": "eyJhbGciOiJFUzI1"
9}

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.

Objects 

Face

The Face object describes face characteristics.

Parameters

The parameters for Face are shown in the table.

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": "F6_4_VID60X",
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.

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.

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.

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.

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.

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.

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.

Example usage

An example usage for SdkInfo is shown in the snippet:

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

Age

The Age object describes age options for age estimation APIs.

Parameters

The parameters for Age are shown in the table.

Example usage

An example usage for Age is shown in the snippet:

JSON
1{
2  "threshold" : 18
3}

FAQ 

What are the recommended liveness settings? 

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

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