Skip to main content
POST
https://api.voxmind.ai
/
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"
  }'

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

​
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

​
orgId
string
required
Your organisation’s unique identifier.

​
Request Body

​
voice_data
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.
​
request_uuid
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.
​
external_id
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.
​
language
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.
​
device_fingerprint
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.
​
device_type
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:
​
event_type
string
Always verification.completed for verification results.
​
request_uuid
string
The UUID you provided in the request body. Use this to correlate the result with the correct user session.
​
external_id
string
Your user’s identifier, as provided in the request.
​
result
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.
​
match_score
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.
​
deepfake_detected
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.
​
latency_ms
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"
  }'

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