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

# Voice Enrollment

This Endpoint is used to register a new voice. It receives one or more audio files and returns a **voice template** (voice template). The voice template is a string that contains the **biometric information of the voice**. This template can be used to **authenticate voices in the future**. The audio files can be encrypted or not, and **encoded in Base64**. The returned template is always **encrypted and encoded in Base64**. It accepts 1 audio file, or 3 to 5 audio files, to perform text-independent or text-dependent enrollment, respectively:

* **1 audio file** for text-independent enrollment (text-independent).
* **3 to 5 audio files** for text-dependent enrollment (text-dependent).

#### Supported audio formats

| Format             |
| ------------------ |
| WAV                |
| MP3                |
| Opus/OGG           |
| AAC                |
| WMA                |
| PCM ulaw and mulaw |
| FLAC               |
| ALAC (mov)         |
| MP4                |
| AIFF               |

### Endpoint

```
POST /voice/enrollment
```

### 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                                                                                                                                                                    |
| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `audio files` | string\[] | **Yes**  | Array of strings. Each position in the array is a raw audio buffer **encoded in Base64** (RFC4648). Maximum two files. It accepts **1 audio file**, or **3 to 5 audio files**. |

#### Request example

```json
{
  "audios": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."]
}
```

### 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.operation_result`                                          | integer | Result code of the enrollment operation.                                        |
| `serviceResult.template`                                                  | string  | Biometric Template **encrypted and encoded in Base64**.                         |
| `serviceResult.template_type`                                             | string  | Type of generated template: `text-dependent` or `text-independent`.             |
| `serviceResult.validate_audios_result`                                    | array   | Array with the results of **validation of each sent audio file** .              |
| `serviceResult.validate_audios_result[].audio_position`                   | integer | Position of the audio file in the sent array.                                   |
| `serviceResult.validate_audios_result[].matching_score`                   | number  | Matching score of **Matching** of the audio (0-1). **1.0 = 100%**.              |
| `serviceResult.validate_audios_result[].multiple_speakers_score_detected` | number  | Multiple speakers detection score **multiple speakers**.                        |
| `serviceResult.validate_audios_result[].result_code`                      | integer | Individual result code for the audio.                                           |
| `serviceResult.validate_audios_result[].snr_db_detected`                  | number  | Signal **to-noise ratio** detected in the audio **(dB)**.                       |
| `serviceResult.validate_audios_result[].speech_length_ms_detected`        | integer | Speech duration detected in **milliseconds**.                                   |
| `serviceResult.validate_audios_result[].speech_relative_length_detected`  | number  | Relative speech proportion with respect to the **total duration** of the audio. |
| `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-12T09:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "operation_result": 3,
    "template": "BgEBAQIvimhg/Th98mTNID4BPHKsJsf...",
    "template_type": "text-dependent",
    "validate_audios_result": [
      {
        "audio_position": 0,
        "matching_score": 0.9999997019767761,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 18.781143188476562,
        "speech_length_ms_detected": 4200,
        "speech_relative_length_detected": 0.65625
      },
      {
        "audio_position": 1,
        "matching_score": 1,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 17.34685707092285,
        "speech_length_ms_detected": 5000,
        "speech_relative_length_detected": 0.6868131756782532
      },
      {
        "audio_position": 2,
        "matching_score": 1,
        "multiple_speakers_score_detected": -3.4028234663852886e+38,
        "result_code": 3,
        "snr_db_detected": 17.34685707092285,
        "speech_length_ms_detected": 5000,
        "speech_relative_length_detected": 0.6868131756782532
      }
    ]
  },
  "serviceTime": "638"
}
```

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