> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/identity-validation-v2.md). # 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. | {% hint style="info" %} All calls to the Endpoints for Tracking with **Identity Platform** must contain the header `family`. {% endhint %} ### 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](#especificacion-de-metodo). | | `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 ```json { "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](#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](#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](#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 ```json { "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 ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "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 ```json { "message": "Endpoint request timed out" } ```