> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Biometrics

> Verify caller identity using voiceprint analysis — internal phrase matching or external providers like Pindrop and Nuance.

# Voice Biometrics

The **Voice Biometrics** tool verifies caller identity using voiceprint analysis. The agent asks the caller to speak a specific phrase, then compares it against stored voiceprint data. Supports both internal phrase matching and external providers (Pindrop, Nuance).

## How It Works

```
Agent: "For security, please say the phrase: 'My voice is my password.'"
Caller: "My voice is my password."
-> Agent calls verify_voice_identity with the spoken phrase
-> Voiceprint comparison runs (internal or external API)
Agent: "Voice identity verified successfully. How can I help you today?"
```

## Configuration

```json theme={null}
{
  "voiceBiometricsEnabled": true,
  "voiceBiometricsProvider": "internal",
  "voiceBiometricsAction": "verify",
  "voiceBiometricsEnrollPhrase": "My voice is my password",
  "voiceBiometricsConfidenceThreshold": 0.7,
  "voiceBiometricsFailAction": "end_call",
  "voiceBiometricsTransferTarget": "+14155551234"
}
```

| Setting                              | Type    | Default    | Description                                                       |
| ------------------------------------ | ------- | ---------- | ----------------------------------------------------------------- |
| `voiceBiometricsEnabled`             | boolean | `false`    | Enable voice biometrics                                           |
| `voiceBiometricsProvider`            | string  | `internal` | Provider: `internal`, `pindrop`, `nuance`, or custom              |
| `voiceBiometricsAction`              | string  | `verify`   | `verify` (existing users) or `enroll_and_verify` (new + existing) |
| `voiceBiometricsEnrollPhrase`        | string  | —          | Phrase the caller must speak                                      |
| `voiceBiometricsConfidenceThreshold` | float   | `0.7`      | Minimum confidence for verification (0.0-1.0)                     |
| `voiceBiometricsFailAction`          | string  | `end_call` | On failure: `end_call`, `transfer`, `continue`                    |
| `voiceBiometricsTransferTarget`      | string  | —          | Transfer number on failure                                        |

### External Provider Settings

For external providers (Pindrop, Nuance, etc.):

| Setting                      | Type   | Description                         |
| ---------------------------- | ------ | ----------------------------------- |
| `voiceBiometricsApiKey`      | string | API key for the biometrics provider |
| `voiceBiometricsApiSecret`   | string | API secret                          |
| `voiceBiometricsApiEndpoint` | string | Provider API endpoint URL           |

## LLM Tool

**Tool name:** `verify_voice_identity`

```
Parameters:
  spoken_phrase: string (what the caller said)

Returns:
  Success: "Voice identity verified successfully (confidence: 85%). The caller is authenticated."
  Failure: "Voice verification failed (confidence: 40%, threshold: 70%). The caller could not be authenticated."
```

## Providers

| Provider   | How It Works                                                                            |
| ---------- | --------------------------------------------------------------------------------------- |
| `internal` | Fuzzy word matching against the enrollment phrase. Good for demos and simple use cases. |
| `pindrop`  | External API call to Pindrop's voiceprint service                                       |
| `nuance`   | External API call to Nuance's voice biometrics                                          |
| Custom     | Any provider with a REST API                                                            |

## Failure Actions

| Action     | Behavior                                                      |
| ---------- | ------------------------------------------------------------- |
| `end_call` | Agent apologizes and ends the call                            |
| `transfer` | Agent transfers to the configured number                      |
| `continue` | Agent continues with limited access (no sensitive operations) |

## Example — Create Agent with Voice Biometrics

```bash theme={null}
curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure Banking Agent",
    "model": "gpt-4o",
    "instructions": "You are a secure banking agent. Before accessing any account information, verify the caller identity using voice biometrics. Ask them to say the enrollment phrase.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "voiceBiometricsEnabled": true,
    "voiceBiometricsProvider": "internal",
    "voiceBiometricsAction": "verify",
    "voiceBiometricsEnrollPhrase": "My voice is my password",
    "voiceBiometricsConfidenceThreshold": 0.7,
    "voiceBiometricsFailAction": "transfer",
    "voiceBiometricsTransferTarget": "+14155551234"
  }'
```