Speaker Services - Verifications
Perform synchronous 1:1 speaker verification and inspect retained verification records. Embedding model aliases are documented in Embedding Models, sentver model aliases are documented in Sentence Verification Models, voice prints are documented in Voice Prints, speaker identities are documented in Speakers, and enrollment workflows are documented in Enrollments.
Base path: /api/v1/speaker-services/speaker-verification/verifications
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/speaker-services/speaker-verification/verifications |
List Verifications |
POST |
/api/v1/speaker-services/speaker-verification/verifications |
Verify Speaker |
GET |
/api/v1/speaker-services/speaker-verification/verifications/{verificationId} |
Get Verification |
GET |
/api/v1/speaker-services/speaker-verification/verifications/{verificationId}/recording |
Download Verification Recording |
DELETE |
/api/v1/speaker-services/speaker-verification/verifications/{verificationId} |
Delete Verification |
POST |
/api/v1/speaker-services/speaker-verification/verifications/{verificationId}/purge |
Purge Verification |
List Verifications
GET /api/v1/speaker-services/speaker-verification/verifications
Requires Authentication - Scopes: speaker:verifications:read
List retained verification attempts for debugging, monitoring, and audit workflows.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
speakerId |
string (UUID) |
No | - | Filter by claimed speaker. |
decision |
string[] |
No | - | Filter by decision. Values: ACCEPT, REJECT, REVIEW. |
status |
string[] |
No | - | Filter by verification record status. Values: COMPLETED, FAILED. |
createdAfter |
string (ISO 8601) |
No | - | Return verification records created on or after this timestamp. |
createdBefore |
string (ISO 8601) |
No | - | Return verification records created on or before this timestamp. |
isDeleted |
boolean |
No | false |
Filter by deleted state. |
sort |
string |
No | createdAt,desc |
Sort field and direction. Allowed fields: createdAt, processedAt, speakerScore, decision. |
SpeakerServiceVerificationsListResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
verifications |
SpeakerServiceVerificationResponse[] |
No | Array of verification records. |
size |
integer |
No | Number of items returned. |
total |
long |
No | Total number of matching items. |
filters |
object |
No | Echo of applied filters. |
sort |
object |
No | Applied sort order. |
| Status | Description |
|---|---|
200 OK |
Verifications retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope. |
Verify Speaker
POST /api/v1/speaker-services/speaker-verification/verifications
Requires Authentication - Scopes: speaker:verifications:write
Rate Limited - This endpoint enforces stricter rate limits
Perform synchronous 1:1 speaker verification. The request blocks until the decision is available, stores the accepted verification attempt, and returns the verification record in the response body.
Content Type
This endpoint requires multipart/form-data.
Audio Format
Probe audio must be a WAV file (audio/wav, .wav).
Supported formats:
- PCM S16LE (16-bit, mono, 16 kHz) - Recommended
- PCM S16LE (16-bit, mono, 8 kHz)
- MU-LAW (8-bit, mono, 8/16 kHz)
- A-LAW (8-bit, mono, 8/16 kHz)
Audio Size Limit
Verification probe audio submitted through either file or uri must be at most 5 MB (5,242,880 bytes).
Multipart Form Parts
| Part | Type | Required | Description |
|---|---|---|---|
speakerId |
string (UUID) |
Yes | Claimed speaker identity to verify. |
file |
binary |
Conditional | WAV probe recording uploaded directly. Required if uri is not provided. |
uri |
string |
Conditional | Remote URI to import WAV PCM probe audio. Required if file is not provided. |
uriHeaders |
string (JSON) |
No | Optional HTTP headers to send when importing probe audio from uri. |
segment |
string (JSON) |
No | Segment selection JSON. See SpeakerServiceAudioSegmentSelection. |
thresholdPolicy |
string (JSON) |
No | Decision policy JSON. See SpeakerServiceThresholdPolicy. |
model |
string |
No | Embedding model alias. If omitted, uses the speaker default voice print. See Embedding Models. |
sentenceVerification |
string (JSON) |
No | Expected sentence validation JSON. See SpeakerServiceSentenceVerificationRequest. |
metadata |
string (JSON) |
No | Opaque client metadata stored with the retained verification record until retention cleanup. |
curl -X POST https://koldan.dixilang.com/api/v1/speaker-services/speaker-verification/verifications \
-H "X-API-Key: $KOLDAN_API_KEY" \
-F "speakerId=0d5b31f3-2d77-4b46-a7b0-0d22b9910d10" \
-F "file=@probe.wav;type=audio/wav" \
-F 'uriHeaders={"Authorization":"Bearer import-token"}' \
-F 'segment={"start":2.0,"end":10.5}' \
-F 'thresholdPolicy={"mode":"BALANCED"}' \
-F 'sentenceVerification={"expectedText":"my voice is my password","model":"sentver-default","locale":"en-US","policy":{"mode":"BALANCED"}}' \
-F 'metadata={"sessionId":"ivr-823741"}'
SpeakerServiceVerificationResponse
Returns the retained verification record.
| Status | Description |
|---|---|
201 Created |
Verification completed and retained. Response includes Location. |
400 Bad Request |
Invalid multipart payload, missing speakerId, or invalid threshold policy. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or selected sentver alias not found. |
409 Conflict |
Speaker is not verification-ready, has no usable voice print and on-the-fly generation is disabled or the speaker lacks sufficient enrollments, no tenant default sentver alias is configured when required, or the selected sentver model is not available (VOICE_PRINT_NOT_READY_FOR_MODEL, SENTVER_MODEL_NOT_CONFIGURED, SENTVER_MODEL_NOT_AVAILABLE). |
413 Payload Too Large |
Submitted probe audio exceeds the 5 MB per-upload limit, or monthly/storage quota would be exceeded. |
422 Unprocessable Entity |
Probe recording is too short, too noisy, contains no usable speech, has unsupported sentver locale, or fails verification quality checks. |
429 Too Many Requests |
Rate limit exceeded. |
Get Verification
GET /api/v1/speaker-services/speaker-verification/verifications/{verificationId}
Requires Authentication - Scopes: speaker:verifications:read
Retrieve a retained verification record.
| Status | Description |
|---|---|
200 OK |
Verification retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Verification not found. |
Download Verification Recording
GET /api/v1/speaker-services/speaker-verification/verifications/{verificationId}/recording
Requires Authentication - Scopes: speaker:verifications:read
Download the verification probe recording for debugging when the verification record is not deleted or purged and the probe recording is still retained.
Default Retention
By default, probe recordings are discarded after processing, so this endpoint commonly returns 410 Gone unless your retention policy is configured to keep verification recordings.
| Status | Description |
|---|---|
200 OK |
Recording returned as binary audio content. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Verification not found, or the verification record is deleted. |
410 Gone |
Verification exists, but the recording has been discarded or purged by retention policy. |
Delete Verification
DELETE /api/v1/speaker-services/speaker-verification/verifications/{verificationId}
Requires Authentication - Scopes: speaker:verifications:delete
Soft-delete a retained verification record.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
purge |
boolean |
No | false |
Immediately purge result data, probe recording references, quality score, errors, and client context. |
| Status | Description |
|---|---|
204 No Content |
Verification deleted successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Verification not found. |
Purge Verification
POST /api/v1/speaker-services/speaker-verification/verifications/{verificationId}/purge
Requires Authentication - Scopes: speaker:verifications:delete
Permanently purge a deleted verification record. Purge removes result data, probe recording references, quality score, errors, and client context while preserving minimal administrative metadata.
| Status | Description |
|---|---|
204 No Content |
Verification purged successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Verification not found. |
409 Conflict |
Verification is not deleted or is already purged. |
Data Types
SpeakerServiceVerificationResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Unique verification record identifier. |
speakerId |
string (UUID) |
No | Claimed speaker identity. |
speakerName |
string |
No | Speaker display name. |
speakerExternalRef |
string |
Yes | Client-defined external identifier. |
voicePrintId |
string (UUID) |
Yes | Voice print used for this verification. |
status |
string |
No | Verification record status. Values: COMPLETED, FAILED. |
source |
SpeakerServiceMediaSource |
Yes | Probe recording source metadata. |
segment |
SpeakerServiceAudioSegmentSelection |
Yes | Segment used for the probe recording. |
result |
SpeakerServiceVerificationResult |
Yes | Final verification decision after speaker and optional sentence gating. |
speakerMatch |
SpeakerServiceSpeakerMatchResult |
Yes | Speaker biometric match result before optional sentence gating. |
sentenceVerification |
SpeakerServiceSentenceVerificationResult |
Yes | Sentver result and model lineage when sentence verification was requested. |
qualityScore |
float |
Yes | Audio quality score of the probe recording. |
totalLatencyMs |
integer |
Yes | End-to-end processing latency in milliseconds. |
sentverLatencyMs |
integer |
Yes | Sentence verification inference latency in milliseconds. Null when sentence verification was not requested. |
speakerVerificationLatencyMs |
integer |
Yes | Speaker verification (embedding comparison) inference latency in milliseconds. |
context |
object |
Yes | Client context retained until verification data is purged. |
errorCode |
string |
Yes | Top-level error code for failed verification records. |
errors |
SpeakerServiceProcessingError[] |
Yes | Processing errors for failed verification records. |
isDeleted |
boolean |
No | Whether the verification record has been deleted. |
isPurged |
boolean |
No | Whether result/debug data has been permanently removed. |
createdAt |
string (ISO 8601) |
No | Timestamp when verification was accepted. |
processedAt |
string (ISO 8601) |
Yes | Timestamp when verification completed. |
deletedAt |
string (ISO 8601) |
Yes | Timestamp when verification was deleted. |
purgedAt |
string (ISO 8601) |
Yes | Timestamp when verification data was purged. |
purgeAt |
string (ISO 8601) |
Yes | Scheduled purge timestamp based on retention policy. |
SpeakerServiceVerificationResult
| Field | Type | Nullable | Description |
|---|---|---|---|
decision |
string |
No | Final verification decision after optional sentence gating. See SpeakerVerificationDecision. |
reason |
string |
Yes | Human-readable final decision summary. |
speakerDecision |
string |
Yes | Speaker biometric decision before sentence gating. |
sentenceDecision |
string |
Yes | Sentence verification decision when requested. |
SpeakerServiceSpeakerMatchResult
| Field | Type | Nullable | Description |
|---|---|---|---|
decision |
string |
No | Speaker match decision before sentence gating. |
score |
float |
No | Similarity score returned by the embedding model comparison (0.0-1.0). |
acceptThreshold |
float |
No | Threshold at or above which the speaker result is ACCEPT. |
reviewThreshold |
float |
Yes | Threshold at or above which the speaker result is REVIEW. |
SpeakerServiceThresholdPolicy
Threshold policy applied to the speaker biometric match. The default mode is BALANCED. When mode=CUSTOM, you must supply explicit threshold values.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
SpeakerThresholdMode |
No | Threshold preset. Default: BALANCED. |
reviewThreshold |
float |
No | Required when mode=CUSTOM and review outcomes are enabled. |
acceptThreshold |
float |
No | Required when mode=CUSTOM. Must be greater than or equal to reviewThreshold. |
SpeakerServiceSentenceVerificationPolicy
Optional threshold policy for sentence verification. Controls which decision is produced from the sentver score. Omit the policy field entirely to use the BALANCED defaults of the resolved sentver model.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
SentverThresholdMode |
No | Threshold preset. Default: BALANCED. |
acceptThreshold |
float |
Conditional | Required when mode=CUSTOM. Score ≥ this value → ACCEPT. |
reviewThreshold |
float |
No | Used only when mode=CUSTOM. Score in [reviewThreshold, acceptThreshold) → REVIEW. |
Enumerations
SpeakerVerificationDecision
| Value | Description |
|---|---|
ACCEPT |
Probe sample matches the claimed speaker above the accept threshold. |
REJECT |
Probe sample does not match the claimed speaker. |
REVIEW |
Probe sample is inconclusive and should be routed to a secondary verification flow. |
SentverThresholdMode
| Value | Description |
|---|---|
STRICT |
Tighter thresholds - minimises false accepts. |
BALANCED |
Default balance between security and convenience. |
LENIENT |
Lower thresholds - favours convenience over strictness. |
CUSTOM |
Caller supplies explicit acceptThreshold / reviewThreshold values. |
SpeakerThresholdMode
| Value | Description |
|---|---|
STRICT |
Minimize false accepts using tighter thresholds. |
BALANCED |
Default balance between security and convenience. |
LENIENT |
Favor convenience using lower thresholds. |
CUSTOM |
Client provides explicit thresholds. |