Facial Extraction

Service that performs the facial detection and validation from an open or tokenized image.

Note that all returned values are estimates based on the provided facial image. The actual accuracy and reliability may vary depending on the quality and characteristics of the input image.

Endpoint

POST /extractFacial

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
tokenBuffer	string	Yes	Image encoded in Base64 or tokenized for facial detection.
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.

Request example

{
  "tokenBuffer": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "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 the service execution.
serviceResultLog	string	Descriptive field of the result or error message, if applicable.
serviceTime	string	Request processing time (milliseconds).
serviceFacialExtractionResult	string	JSON object representing the results of facial detection and validation. See Result fields.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.

Facial extraction result fields

Field	Type	Description
faceConfidence	float	Indicates the confidence level of the evaluated face.
age	integer	Indicates the possible age detected.
glasses	string	Indicates eyeglasses detection. Possible values: Eye (Glasses), None (None), Sun (Sunglasses)
gender	string	Returns the detected gender. Possible values: Male, Female, None (Undetermined)
iod	integer	Indicates the interpupillary distance.

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

Response example

{
  "serviceResultCode": 0,
  "serviceResultLog": "Service request successfully processed",
  "serviceTime": "864",
  "serviceFacialExtractionResult": "{\"faceConfidence\":0.9999948143959045,\"age\":30,\"glasses\":\"None\",\"gender\":\"Male\",\"iod\":154}",
  "serviceTransactionId": "b2f6297b-01ca-4aa3-afd7-6cb3c9d74141"
}

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