Skip to content

Speaker Services - Verifications

Perform synchronous 1:1 speaker verification and inspect retained verification records. Embedding models are documented in Embedding Models, sentver models 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: PROCESSING, 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.

The selected model is resolved once per request. Compatible evidence is reused by model version and the full usable enrollment set; otherwise embeddings are generated and retained automatically. Model changes apply to subsequent requests. A generation failure produces a failed verification with the selected model metadata and no partial evidence.

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 request headers for uri: at most 32 keys and 8,192 UTF-8 bytes per value. Keys must be allowed by server configuration.
segment string (JSON) No Segment selection JSON. See SpeakerServiceAudioSegmentSelection.
thresholdPolicy string (JSON) No Decision policy JSON. See SpeakerServiceThresholdPolicy.
model string No Embedding model. If omitted, resolves the current default model. 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. While inference is running, public reads may observe PROCESSING; completion records COMPLETED or FAILED.

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 model not found.
409 Conflict Speaker is unavailable, has insufficient usable enrollments, or its source set keeps changing during processing; a required default model is missing; or the selected sentver model is unavailable.
410 Gone The selected embedding model has reached its sunset date.
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.
503 Service Unavailable The selected embedding model version is unavailable.

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

Probe recordings are retained for seven days by default. The effective retention policy can change this duration; a value of 0 discards probe audio after processing. Once the recording has been discarded or purged, this endpoint returns 410 Gone.

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 Immutable evidence used for this verification.
requestedModelAlias string Yes Explicit request model; null for default selection or unknown legacy lineage.
modelAlias string Yes Effective model resolved for this request; unknown for legacy records.
resolvedModel string Yes model version resolved for this request.
modelHash string Yes Hash of the model used by the evidence.
status string No Verification record status. Values: PROCESSING, 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.