Authenticate Facial

Service that performs facial validation between two faces, including both open images and biometric templates.

This service can be used to perform the following validations:

1. Facial authentication between two open images, generated or not by FacePhi Widgets.

2. Facial authentication between two biometric templates, requires Integration of the FacePhi Selphi Mobile or Web Widget.

3. Facial authentication between an open image and a biometric template, requires Integration of the FacePhi Selphi Mobile or Web Widget.

4. Facial authentication between the face present in the identity document photo (TokenFaceImage) and a open image, requires Integration of the FacePhi SelphID Mobile Widget.

5. Facial authentication between the face present in the identity document photo (TokenFaceImage) and a biometric template, requires Integration of the FacePhi Selphi Mobile and SelphID Mobile Widgets.

Integration

• For the type 4 and 5 validations, the implementation of the SelphID Mobile Widget is required to generate the property TokenFaceImage.

• For the type 2, 3 and 5 validations, the implementation of the Selphi Mobile or Web Widget is required to generate the biometric template property (TemplateRaw).

Endpoint

POST /services/authenticateFacial

Headers

Name	Type	Required	Description
x-api-key	string	Yes	Access authorization API key.
family	string	No	Value: Onboarding. Required with the tracking service.

All calls to the Endpoints for Tracking with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
token1	string	Yes	Image used as reference for facial comparison. Depending on the invoked method, it can be the token generated by the SelphID Widgets (document photo token), an open image, or a tokenized biometric template.
token2	string	Yes	Image used for the comparison. It can be an open image or a tokenized biometric template.
method	integer	Yes	Indicates the comparison method invoked. See Method Specification.
tracking	object	No	Object that represents the necessary tracking information.
tracking.extraData	string	No	Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the Mobile/Web SDK.

Method Specification

Method	Description	Input
1	Facial authentication using open images	token1: Base64, token2: Base64
2	Facial authentication using biometric templates	token1: templateRaw, token2: templateRaw
3	Facial authentication using an open image and a biometric template	token1: Base64, token2: templateRaw
4	Facial authentication using the token generated by cropping the document photo and an open image	token1: tokenFaceImage, token2: Base64
5	Facial authentication using the token generated by cropping the document photo and a biometric template	token1: tokenFaceImage, token2: templateRaw

Request example

{
  "token1": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "token2": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "method": 1,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of service execution. See Service Result Code
serviceResultLog	string	Descriptive field of the service execution result. Includes details when there is an error or exception in the module.
serviceTime	string	Total processing time (milliseconds).
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
serviceFacialAuthenticationHash	string	Integrity hash of the biometric template used in a positive or uncertain facial authentication. Only applicable in methods 2, 3 and 5.
serviceFacialAuthenticationResult	integer	Code indicating the facial matching result. See Service Facial Authentication Result
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the face in the identity document photo and the selfie taken by the user. 1.0 = 100%

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP code
0	The service execution was successful, the module processed the request correctly.	200

Service Facial Authentication Result

The serviceFacialAuthenticationResult indicates the result of the facial matching operations:

Code	Result	Description
0	NONE	Facial verification could not be performed.
1	NEGATIVE	The process was executed correctly. The facial pattern comparison of the faces does not match.
3	POSITIVE	The process was executed correctly. The facial pattern comparison of the faces is positive. The value of serviceFacialSimilarityResult indicates the % of similarity between the compared images.
4	NONE BECAUSE POSE EXCEED	Facial verification could not be performed due to the position of the face.
5	NONE BECAUSE INVALID EXTRACTIONS	Facial verification could not be performed due to problems extracting the facial pattern.

Response example: Positive

{
  "serviceResultCode": 0,
  "serviceResultLog": "Positive",
  "serviceTime": "516",
  "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "serviceFacialAuthenticationHash": "47D0ACDCF08C348469C2F512BB59216B46DCD9B253822ED0E4EEAFCEB76AADD5AEF20CA31EC52D03EB290EBC91A6AD65FB0416F9EB2164D3854932153074289E",
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.99153554
}

Response example: Negative

{
  "serviceResultCode": 0,
  "serviceResultLog": "Negative",
  "serviceTime": "502",
  "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "serviceFacialAuthenticationHash": "09B9A4097E3642ADEDB665BA2E15B096FFB65A039E0D7137D0AD38666F90A010624C26867E6A7DB8346385610CC9FEDE435C3CC6A2AC9B008DD98C6EFE8C42E7",
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.01190000
}

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}