> 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/shared-biometric-components/facial-extraction.md).

# Facial Extraction

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

{% hint style="warning" %}
Please note that all returned values are estimates based on the provided facial image. Actual accuracy and reliability may vary depending on the quality and characteristics of the input image.
{% endhint %}

### Endpoint

```
POST /extractFacial
```

### Headers

| Name          | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | API key for access authorization.                         |
| **family**    | string | No       | Value: **Onboarding**. Required for the Tracking service. |

{% hint style="info" %}
All calls to Tracking Endpoints with **Identity Platform** must include the header `family`.
{% endhint %}

### 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 representing the required tracking information.                                            |
| `tracking.extraData`   | string | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform. |
| `tracking.operationId` | string | No       | Operation identifier generated by the SDK Mobile/Web.                                             |

#### Request example

```json
{
  "tokenBuffer": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% hint style="warning" %}
**Maximum request size: 6 MB.** The Base64-encoded or tokenized image (`tokenBuffer`) and the remaining fields count toward this limit, with \~33% overhead compared to the original file (maximum original file size of \~4.5 MB). Compressed JPEG images of 1–2 MB at most are recommended. If the limit is exceeded, the gateway responds `413` without processing the request. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Responses

#### `200` Success

#### Response parameters

| Parameter                       | Type    | Description                                                                                                                                   |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Code indicating the **overall result** of the service execution.                                                                              |
| `serviceResultLog`              | string  | Descriptive result field 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](#campos-del-resultado-de-extracción-facial). |
| `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 glasses 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       |

#### Example response

```json
{
  "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

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

#### `413` Payload Too Large

The request exceeds the maximum allowed size. The gateway rejects it **without processing it**: the response does not include `serviceResultCode` or `serviceTransactionId`. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Request larger than 6 MB and up to 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Request larger than 10 MB (10,485,760 bytes) (`Content-Type: text; charset=utf-8`, plain text, not JSON):

```
HTTP content length exceeded 10485760 bytes.
```

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