Identity Validation V2

This service performs both the liveness check and the facial comparison between two faces, whether provided as open images or as tokenized parameters. It supports two types of facial validations, depending on the integrated Widget.

Integration

• For the type 3 validation, an open-format image of the front of the identity card, where the face is located, is required.

• For the type 5 validation, it is necessary to implement the SelphID Mobile Widget to generate the property TokenFaceImage.

Endpoint

POST /onboarding/v2/identity

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. It can be a base64 image or TokenFaceImage, depending on the method.
bestImageToken	string	Yes	Property tokenized bestImage generated by the Selphi Widget and tokenized by the native function.
method	string	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
"3"	Facial authentication using an open image and tokenized bestImage (Base64 & bestImageToken)
"5"	Facial authentication using the token generated by cropping the document photo and tokenized bestImage (tokenFaceImage & bestImageToken)

Request example

{
  "token1": "/9j/4AAQSkZJRgABAQAASAB...",
  "bestImageToken": "BAMBAQLNHJoWGPj...",
  "method": "3",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceTransactionId	string	Transaction identifier associated with the API request.
serviceResultCode	integer	Code indicating the overall result of service execution. See Service Result Code
serviceResultLog	string	Descriptive field for the result of the service execution. Provides details of errors or exceptions when they occur.
serviceTime	string	Field indicating the processing time (milliseconds).
facialAuthenticationResult	integer	Code indicating the facial matching result. See Service Facial Authentication Result
facialAuthenticationLog	string	Descriptive field for the result of facial matching.
facialAuthenticationSimilarity	number	Value indicating the facial similarity between the photo on the document and the selfie taken by the user. 1.0 = 100%
passiveLivenessResult	integer	Code indicating the passive liveness check result. See Service Liveness Result
passiveLivenessLog	string	Descriptive field for the result of the passive liveness check.

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 Liveness Result

The serviceLivenessResult indicates the result of the passive liveness check evaluation:

Code	Result	Description
0	None	The liveness check could not be evaluated.
1	Spoof	DEPRECATED. Use 'NoLive' instead.
2	Uncertain	DEPRECATED
3	Live	The subject is assumed to be alive.
4	NoneBecauseBadQuality	The liveness check could not be evaluated due to poor image quality.
5	NoneBecauseFaceTooClose	The liveness check could not be evaluated because the detected faces are too close to the edges.
6	NoneBecauseFaceNotFound	The liveness check could not be evaluated because no faces were detected.
7	NoneBecauseFaceTooSmall	The liveness check could not be evaluated because the detected faces are too small.
8	NoneBecauseAngleTooLarge	The liveness check could not be evaluated because the angle between faces exceeds the allowed limit.
9	NoneBecauseImageDataError	The liveness check could not be evaluated due to errors in the image format.
10	NoneBecauseInternalError	The liveness check could not be evaluated due to an internal error.
11	NoneBecauseImagePreprocessError	The liveness check could not be evaluated due to an image preprocessing error.
12	NoneBecauseTooManyFaces	The liveness check could not be evaluated because too many faces were detected in the image.
13	NoneBecauseFaceTooCloseToBorder	The liveness check could not be evaluated because the face is too close to the edge.
14	NoneBecauseFaceCropped	The liveness check could not be evaluated because the face is cropped.
15	NoneBecauseLicenseError	The liveness check could not be evaluated due to a License error.
16	NoneBecauseFaceOccluded	The liveness check could not be evaluated because the face is occluded.
17	NoLive	No liveness detected.
18	NoneBecauseEyesClosed	The liveness check could not be evaluated because the person's eyes are closed.

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

{
  "serviceTransactionId": "2db602ee-3564-4304-af95-92a52eaae12d",
  "serviceResultCode": 0,
  "serviceResultLog": "[identity] Service executed ok",
  "serviceTime": "2235",
  "facialAuthenticationResult": 3,
  "facialAuthenticationLog": "Positive",
  "facialAuthenticationSimilarity": 0.99214232,
  "passiveLivenessResult": 3,
  "passiveLivenessLog": "Live"
}

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