Verify a User

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"
  }'

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",
    }
)

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",
    }),
  }
);

{
  "callback_url": "https://yourapp.com/webhooks/voxmind",
  "message": "Your request has been accepted and is being processed"
}

{
  "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"
}

{
  "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"
}

POST

organisations

{orgId}

verifications

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"
  }'

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",
    }
)

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",
    }),
  }
);

{
  "callback_url": "https://yourapp.com/webhooks/voxmind",
  "message": "Your request has been accepted and is being processed"
}

{
  "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"
}

{
  "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"
}

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.

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.

Path Parameters

string

required

Your organisation’s unique identifier.

Request Body

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.

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.

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.

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.

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.

integer

Optional. Same device type categories as enrollment. 0 = unknown, 1 = mobile, 2 = desktop, 3 = IP phone.

Webhook Result Payload

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

string

Always verification.completed for verification results.

string

The UUID you provided in the request body. Use this to correlate the result with the correct user session.

string

Your user’s identifier, as provided in the request.

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.

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.

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.

integer

Total processing time in milliseconds from request receipt to result generation. Useful for monitoring and SLA verification.

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"
  }'

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",
    }
)

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",
    }),
  }
);

{
  "callback_url": "https://yourapp.com/webhooks/voxmind",
  "message": "Your request has been accepted and is being processed"
}

{
  "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"
}

{
  "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"
}

Voice Core

API Tokens

Organisation

Users

Billing

Devices & Texts

Overview

Path Parameters

Request Body

Webhook Result Payload

​Overview

​Path Parameters

​Request Body

​Webhook Result Payload

Overview

Path Parameters

Request Body

Webhook Result Payload