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

# Verify a User

> Verify a user's identity against their enrolled voiceprint, with automatic deepfake detection. Returns 202 immediately; result delivered via webhook.

## Overview

Verification compares a new voice recording against a user's stored voiceprint. Voxmind runs two parallel checks: a voiceprint match (returning a confidence score) and a deepfake detection check (identifying synthetic or replayed audio). Both results are included in the webhook payload.

Like enrollment, verification is **asynchronous**. You receive a 202 Accepted immediately and your webhook receives the full result within 1–2 seconds on average.

<Warning>
  **Always check `deepfake_detected` before granting access.** A voice clone may produce a non-trivial match score. The deepfake flag is your definitive signal — any result with `deepfake_detected: true` should be treated as a security event and logged, regardless of the `match_score`.
</Warning>

## Path Parameters

<ParamField path="orgId" type="string" required>
  Your organisation's unique identifier.
</ParamField>

## Request Body

<ParamField body="voice_data" type="string (binary)" required>
  The voice recording from the current authentication attempt, base64-encoded. Same format requirements as enrollment: WAV or MP3, minimum 16kHz, at least 3 seconds of speech.
</ParamField>

<ParamField body="request_uuid" type="string (UUID)" required>
  A unique identifier you generate for this verification request. Returned in the webhook payload so you can correlate the async result with the correct user session.
</ParamField>

<ParamField body="external_id" type="string">
  Your user's identifier — must exactly match the `external_id` used during their enrollment. Voxmind uses this to retrieve the correct voiceprint for comparison.
</ParamField>

<ParamField body="language" type="string" default="en-UK">
  The primary language of the verification audio. The user can speak a different language than they enrolled in — Voxmind handles this — but specifying the correct language improves accuracy.
</ParamField>

<ParamField body="device_fingerprint" type="string">
  Optional. The unique identifier of the device being used for this verification attempt. When provided, this is compared against the device fingerprint used at enrollment. Mismatches are flagged in analytics and can be used to detect account sharing or device-switching attacks.
</ParamField>

<ParamField body="device_type" type="integer">
  Optional. Same device type categories as enrollment. `0` = unknown, `1` = mobile, `2` = desktop, `3` = IP phone.
</ParamField>

## Webhook Result Payload

The following fields are included in the webhook result delivered to your callback URL:

<ResponseField name="event_type" type="string">
  Always `verification.completed` for verification results.
</ResponseField>

<ResponseField name="request_uuid" type="string">
  The UUID you provided in the request body. Use this to correlate the result with the correct user session.
</ResponseField>

<ResponseField name="external_id" type="string">
  Your user's identifier, as provided in the request.
</ResponseField>

<ResponseField name="result" type="string">
  The verification outcome. One of `verified`, `rejected`, or `inconclusive`. An `inconclusive` result means audio quality was insufficient for a reliable determination — treat it as a rejection and prompt the user to try again.
</ResponseField>

<ResponseField name="match_score" type="float">
  A confidence score between 0.0 and 1.0 representing how closely the submitted audio matches the enrolled voiceprint. Scores above 0.85 indicate a strong match. Your application should define a threshold appropriate to your security requirements — higher stakes use cases should use a higher threshold.
</ResponseField>

<ResponseField name="deepfake_detected" type="boolean">
  `true` if the audio was identified as AI-generated, synthetic, or replayed. This runs as a parallel check to voiceprint matching and is always present in the payload. A value of `true` should result in immediate rejection and fraud logging, regardless of `match_score`.
</ResponseField>

<ResponseField name="latency_ms" type="integer">
  Total processing time in milliseconds from request receipt to result generation. Useful for monitoring and SLA verification.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voxmind.ai/organisations/42/verifications \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "voice_data": "UklGRiQAAABXQVZFZm10IBAAAA...",
      "request_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "external_id": "user_98765",
      "language": "en-UK"
    }'
  ```

  ```python Python theme={null}
  import requests, base64, uuid

  with open("auth_attempt.wav", "rb") as f:
      voice_b64 = base64.b64encode(f.read()).decode("utf-8")

  resp = requests.post(
      "https://api.voxmind.ai/organisations/42/verifications",
      headers={"Authorization": "Bearer YOUR_API_TOKEN"},
      json={
          "voice_data": voice_b64,
          "request_uuid": str(uuid.uuid4()),
          "external_id": "user_98765",  # Must match enrollment external_id
          "language": "en-UK",
      }
  )
  ```

  ```javascript Node.js theme={null}
  const fs = require("fs");
  const { randomUUID } = require("crypto");

  const response = await fetch(
    "https://api.voxmind.ai/organisations/42/verifications",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        voice_data: fs.readFileSync("auth_attempt.wav").toString("base64"),
        request_uuid: randomUUID(),
        external_id: "user_98765",
        language: "en-UK",
      }),
    }
  );
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted (immediate response) theme={null}
  {
    "callback_url": "https://yourapp.com/webhooks/voxmind",
    "message": "Your request has been accepted and is being processed"
  }
  ```

  ```json Webhook payload — verified theme={null}
  {
    "event_type": "verification.completed",
    "request_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "external_id": "user_98765",
    "result": "verified",
    "match_score": 0.94,
    "deepfake_detected": false,
    "latency_ms": 1183,
    "created_at": "2025-03-15T14:25:08Z"
  }
  ```

  ```json Webhook payload — deepfake detected theme={null}
  {
    "event_type": "verification.completed",
    "request_uuid": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "external_id": "user_98765",
    "result": "rejected",
    "match_score": 0.71,
    "deepfake_detected": true,
    "latency_ms": 1402,
    "created_at": "2025-03-15T14:28:44Z"
  }
  ```
</ResponseExample>