> 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/authentication/voice-authentication.md).

# Voice Authentication

This service is used to authenticate a voice. It receives an audio file and a voice template, and returns a boolean indicating whether the voice belongs to the same person as the voice template, along with a probability score indicating the similarity between both voices.

The audio may be encrypted or not, and must be **Base64 encoded**. The voice template must be **encrypted and Base64 encoded** (obtained from the enrollment Endpoint).

### Endpoint

```
POST /voice/authentication
```

### Headers

| Name          | Type   | Required | Description                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | API Key for access authorization.                              |
| **family**    | string | No       | Value: **Authentication**. Required with the tracking service. |

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

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter  | Type   | Required | Description                                                                             |
| ---------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `audio`    | string | **Yes**  | Audio buffer **Base64 encoded** (RFC4648).                                              |
| `template` | string | **Yes**  | Biometric Template **encrypted and Base64 encoded** obtained from enrollment (RFC4648). |

#### Request example

```json
{
  "audio": "JVBERi0xLjQKJeLjz9MKNSAw IG9iago8P...",
  "template": "BgEBAQI+d368i49ITeoPlmCi5zbYp3kdvTsk6otTOl...."
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                        | Type    | Description                                                                              |
| -------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `serviceResultCode`              | integer | Result code indicating the status of the operation. **200** means success.               |
| `serviceResultLog`               | string  | Log message related to the result of the operation.                                      |
| `timestamp`                      | string  | Date and time when the operation was completed.                                          |
| `serviceTransactionId`           | string  | Unique transaction ID to track the operation.                                            |
| `serviceResult.liveness_score`   | number  | liveness detection score.                                                                |
| `serviceResult.match`            | boolean | Indicates whether the voice **matches** with the template.                               |
| `serviceResult.matching_score`   | number  | Probability score indicating the **similarity between the voices** (0-1). **1.0 = 100%** |
| `serviceResult.operation_result` | integer | Authentication operation result code.                                                    |
| `serviceResult.tracking_message` | string  | Operation tracking message.                                                              |
| `serviceResult.tracking_status`  | integer | Tracking status code.                                                                    |
| `serviceTime`                    | string  | Total service execution time **(milliseconds)**.                                         |

#### 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

```json
{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "timestamp": "2024-07-13T19:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "liveness_score": 0,
    "match": true,
    "matching_score": 1,
    "operation_result": 3,
    "tracking_message": "",
    "tracking_status": -1
  },
  "serviceTime": "1708"
}
```

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