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

# POST /verify

> Verify a voice recording and return an ephemeral token.

Verifies a voice recording. Returns an ephemeral JWT token (60s TTL) and both VoiceMark visual outputs. The token is the credential — pass it to your backend for authorisation decisions.

## Request

`POST /v1/verify`

**Content-Type:** `multipart/form-data`

| Field | Type | Required | Notes |
| - | - | - | - |
| `audio` | File | Yes | WAV, WebM, MP3 or M4A |
| `voiceprint_id` | string | No | Enables identity check against enrolled embedding |
| `challenge_id` | string | No | Enables anti-replay check; expires 120s after issue |

> [!NOTE]
>
> Omitting `voiceprint_id` runs liveness-only verification. Omitting `challenge_id` skips anti-replay. For highest security, always pass both.

## Response

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_id": "tok_9a2b3c4d5e6f",
  "authorized": true,
  "liveness_score": 0.91,
  "transcription": "Wild roses grew beside the wooden fence.",
  "pii": null,
  "expires_in": 60,
  "cloud_data": {
    "words": [
      { "word": "Wild", "f0": 142.3, "rms": 0.08, "bands": [0.4, 0.6, 0.3, 0.2] },
      { "word": "roses", "f0": 128.1, "rms": 0.11, "bands": [0.5, 0.7, 0.4, 0.3] }
    ],
    "glyph_params": {
      "hue": 0.61,
      "shapeStretch": 0.44,
      "shellDensity": 0.73
    }
  }
}
```

| Field | Description |
| - | - |
| `token` | 60s JWT — pass to your backend via header |
| `token_id` | Use with `/v1/token/{id}/validate` |
| `authorized` | Whether voice matched. Do not trust this alone — validate the token server-side for privileged actions. |
| `liveness_score` | 0–1 liveness confidence (f0 variation analysis) |
| `transcription` | Whisper transcription of the recording |
| `pii` | Always null — no personal data returned |
| `cloud_data.words` | Per-word acoustic data for [Cloud VoiceMark](https://docs.voicemark.dev/concepts/cloud-voicemark) rendering |
| `cloud_data.glyph_params` | Stable identity params for [Glyph VoiceMark](https://docs.voicemark.dev/concepts/glyph-voicemark) rendering |

## Error codes

| Code | Status | Cause |
| - | - | - |
| `VOICE_MISMATCH` | 400 | Speaker match score below threshold |
| `CHALLENGE_EXPIRED` | 400 | `challenge_id` unknown or expired |
| `AUDIO_TOO_SHORT` | 400 | Clip too short |
| `UNAUTHORIZED` | 401 | Missing or invalid API key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.