Speaker Services - Enrollments
Manage speaker enrollments, enrollment reset, and retained enrollment recordings used for debugging. Enrollments are model-agnostic audio samples - embedding extraction happens automatically when verification needs new evidence. Sentver models are documented in Sentence Verification Models, voice prints are documented in Voice Prints, speaker identities are documented in Speakers, and 1:1 verification is documented in Verifications.
Base path: /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments |
List Enrollments |
POST |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments |
Create Enrollment |
GET |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId} |
Get Enrollment |
GET |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/recording |
Download Enrollment Recording |
GET |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings |
List Enrollment Embeddings |
GET |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings/{embeddingId} |
Get Enrollment Embedding |
DELETE |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId} |
Delete Enrollment |
POST |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/purge |
Purge Enrollment |
POST |
/api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/reset |
Reset Speaker Enrollments |
List Enrollments
GET /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments
Requires Authentication - Scopes: speaker:enrollments:read
Retrieve enrollment records for a speaker.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
speakerId |
string (UUID) |
Yes | Unique identifier of the speaker. |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page |
integer |
No | 0 |
Page number (zero-based). |
size |
integer |
No | 20 |
Page size (max 100). |
status |
SpeakerEnrollmentStatus[] |
No | - | Filter by enrollment status. Values: READY, REJECTED, FAILED. |
isDeleted |
boolean |
No | false |
Filter by deleted state. |
sort |
string |
No | creationDate,desc |
Sort field and direction. Allowed fields: creationDate, qualityScore, status. |
SpeakerServiceEnrollmentsListResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
speakerId |
string (UUID) |
No | Parent speaker identifier. |
enrollments |
SpeakerServiceEnrollmentResponse[] |
No | Array of enrollment 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 |
Enrollments retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker not found. |
Create Enrollment
POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments
Requires Authentication - Scopes: speaker:enrollments:write
Rate Limited - This endpoint enforces stricter rate limits
Create a new enrollment from media submitted directly to Speaker Services. Provide exactly one of file or uri. Enrollment creation is synchronous - the response contains the final enrollment status (READY, REJECTED, or FAILED).
Content Type
This endpoint requires multipart/form-data.
Audio Format
Enrollment 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
Enrollment audio submitted through either file or uri must be at most 5 MB (5,242,880 bytes).
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
speakerId |
string (UUID) |
Yes | Unique identifier of the speaker. |
Multipart Form Parts
| Part | Type | Required | Description |
|---|---|---|---|
file |
binary |
Conditional | WAV enrollment audio uploaded directly. Required if uri is not provided. |
uri |
string |
Conditional | Remote URI to import WAV PCM enrollment 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. |
label |
string |
No | Client-defined sample label such as office-headset-1. |
segment |
string (JSON) |
No | Segment selection JSON. See SpeakerServiceAudioSegmentSelection. |
sentenceVerification |
string (JSON) |
No | Expected sentence validation JSON. See SpeakerServiceSentenceVerificationRequest. |
webhook |
string (JSON) |
No | Webhook configuration JSON. See CommonWebhook. |
curl -X POST "https://koldan.dixilang.com/api/v1/speaker-services/speaker-verification/speakers/0d5b31f3-2d77-4b46-a7b0-0d22b9910d10/enrollments" \
-H "X-API-Key: $KOLDAN_API_KEY" \
-F "file=@speaker-enrollment.wav;type=audio/wav" \
-F "label=office-headset-1" \
-F 'segment={"start":3.5,"end":21.4}' \
-F 'sentenceVerification={"expectedText":"my voice is my password","model":"sentver-default","locale":"en-US"}' \
-F 'webhook={"url":"https://example.com/koldan/enrollments","secret":"shared-secret"}'
SpeakerServiceEnrollmentResponse
Returns the created enrollment with a terminal status (READY, REJECTED, or FAILED).
| Status | Description |
|---|---|
201 Created |
Enrollment accepted. Response includes Location. |
400 Bad Request |
Invalid multipart payload, invalid segment values, or both file and uri were provided. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or selected sentver model not found. |
409 Conflict |
Speaker is deleted, disabled, archived, or no default sentver model is configured when sentence verification is requested. |
413 Payload Too Large |
Submitted enrollment audio exceeds the 5 MB per-upload limit, or monthly/storage quota would be exceeded. |
422 Unprocessable Entity |
Media is rejected before an enrollment resource can be accepted. |
429 Too Many Requests |
Rate limit exceeded. |
Get Enrollment
GET /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}
Requires Authentication - Scopes: speaker:enrollments:read
Retrieve a single enrollment record including processing errors.
| Status | Description |
|---|---|
200 OK |
Enrollment retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or enrollment not found. |
Download Enrollment Recording
GET /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/recording
Requires Authentication - Scopes: speaker:enrollments:read
Download the original enrollment recording for debugging when the enrollment is not deleted or purged and the recording is still retained.
| 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 |
Speaker or enrollment not found, or the enrollment is deleted. |
410 Gone |
Enrollment exists, but the recording has been discarded or purged by retention policy. |
List Enrollment Embeddings
GET /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings
Requires Authentication - Scopes: speaker:enrollments:read
List retained embedding evidence extracted from this enrollment during automatic voice-print generation. Preview does not persist embeddings; the same enrollment may have distinct evidence segments for different snapshots.
SpeakerServiceEnrollmentEmbeddingsListResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
enrollmentId |
string (UUID) |
No | Parent enrollment identifier. |
embeddings |
SpeakerServiceEnrollmentEmbeddingResponse[] |
No | Array of embedding records. |
size |
integer |
No | Number of items returned. |
total |
long |
No | Total number of matching items. |
| Status | Description |
|---|---|
200 OK |
Enrollment embeddings retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or enrollment not found. |
Get Enrollment Embedding
GET /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/embeddings/{embeddingId}
Requires Authentication - Scopes: speaker:enrollments:read
Retrieve a single retained enrollment embedding evidence record.
SpeakerServiceEnrollmentEmbeddingResponse
| Status | Description |
|---|---|
200 OK |
Enrollment embedding retrieved successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker, enrollment, or embedding not found. |
Delete Enrollment
DELETE /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}
Requires Authentication - Scopes: speaker:enrollments:delete
Soft-delete an enrollment. Only terminal-state enrollments can be deleted. The same speaker:enrollments:delete scope is used whether or not purge=true is supplied.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
purge |
boolean |
No | false |
Immediately purge enrollment media, biometric artifacts, processing errors, and sensitive debug data. |
| Status | Description |
|---|---|
204 No Content |
Enrollment deleted successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or enrollment not found. |
409 Conflict |
Enrollment is not in a terminal state. |
Purge Enrollment
POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/{enrollmentId}/purge
Requires Authentication - Scopes: speaker:enrollments:delete
Permanently purge a deleted enrollment and its biometric artifacts. Purge removes enrollment media, derived biometric artifacts, processing errors, and sensitive debug data while preserving minimal administrative metadata.
| Status | Description |
|---|---|
204 No Content |
Enrollment purged successfully. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker or enrollment not found. |
409 Conflict |
Enrollment is not deleted or is already purged. |
Reset Speaker Enrollments
POST /api/v1/speaker-services/speaker-verification/speakers/{speakerId}/enrollments/reset
Requires Authentication - Scopes: speaker:enrollments:delete
Restart the enrollment process for a speaker. Reset is a delete operation: existing enrollments, voice prints, and retained verification records for the speaker are soft-deleted and historical records remain subject to retention unless purge=true is supplied.
SpeakerServiceEnrollmentResetRequest
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
purge |
boolean |
No | false |
Immediately purge enrollment recordings, media, and biometric artifacts after soft-delete. |
reason |
string |
No | - | Optional audit/debug reason for the reset. |
SpeakerServiceEnrollmentResetResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
speakerId |
string (UUID) |
No | Speaker whose enrollments were reset. |
failedCount |
integer |
No | Number of non-terminal enrollments marked as failed. |
deletedCount |
integer |
No | Number of enrollments soft-deleted. |
purgedCount |
integer |
No | Number of enrollments immediately purged. |
voicePrintDeletedCount |
integer |
No | Number of voice prints soft-deleted. |
voicePrintPurgedCount |
integer |
No | Number of voice prints immediately purged. |
verificationDeletedCount |
integer |
No | Number of retained verification records deleted. |
verificationPurgedCount |
integer |
No | Number of retained verification records immediately purged. |
resetAt |
string (ISO 8601) |
No | Timestamp when reset completed. |
speaker |
SpeakerServiceSpeakerResponse |
No | Updated speaker. |
| Status | Description |
|---|---|
200 OK |
Enrollments reset successfully. |
400 Bad Request |
Invalid request body. |
401 Unauthorized |
Missing or invalid authentication. |
403 Forbidden |
Insufficient scope or not authorized. |
404 Not Found |
Speaker not found. |
409 Conflict |
Speaker is deleted, purged, or cannot be reset. |
Enrollment Webhooks
Enrollment webhooks notify clients when an enrollment reaches a terminal state: READY, REJECTED, or FAILED.
SpeakerServiceEnrollmentWebhookEvent
| Field | Type | Nullable | Description |
|---|---|---|---|
eventType |
string |
No | Event name. Value: speaker.enrollment.completed. |
speakerId |
string (UUID) |
No | Parent speaker identifier. |
enrollmentId |
string (UUID) |
No | Enrollment identifier. |
status |
string |
No | Terminal enrollment status. |
qualityScore |
float |
Yes | Audio quality score (0.0–1.0) when available. |
errorCode |
string |
Yes | Top-level processing error code when enrollment processing failed unexpectedly. |
rejectionCode |
string |
Yes | Policy or quality rejection reason when the enrollment was rejected by expected validation. |
errors |
SpeakerServiceProcessingError[] |
Yes | Processing errors for failed enrollments. |
completedAt |
string (ISO 8601) |
No | Timestamp when the terminal state was reached. |
When secret is provided, webhook requests include an HMAC-SHA256 verification header. Transient delivery failures are retried with backoff and do not block enrollment completion.
Data Types
SpeakerServiceEnrollmentResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Unique identifier of the enrollment. |
speakerId |
string (UUID) |
No | Parent speaker identifier. |
status |
string |
No | Enrollment status. See SpeakerEnrollmentStatus. |
label |
string |
Yes | Client-defined enrollment label. |
source |
SpeakerServiceMediaSource |
No | Submitted media source details. |
segment |
SpeakerServiceAudioSegmentSelection |
Yes | Audio segment used for enrollment. |
qualityScore |
float |
Yes | Audio quality score (0.0–1.0). |
sentenceVerification |
SpeakerServiceSentenceVerificationResult |
Yes | Sentence verification request/result and sentver model lineage when sentence validation was requested. |
errorCode |
string |
Yes | Top-level processing error code when enrollment processing failed unexpectedly. See SpeakerEnrollmentProcessingErrorCode. |
rejectionCode |
string |
Yes | Policy or quality rejection reason when the enrollment was rejected by expected validation. See SpeakerEnrollmentRejectionCode. |
errors |
SpeakerServiceProcessingError[] |
Yes | Processing errors encountered during enrollment. |
webhook |
CommonWebhook |
Yes | Webhook configuration for completion notifications. |
isDeleted |
boolean |
No | Whether the enrollment has been deleted. |
isPurged |
boolean |
No | Whether biometric artifacts have been permanently removed. |
creationDate |
string (ISO 8601) |
No | Timestamp when the enrollment was created. |
completionDate |
string (ISO 8601) |
Yes | Timestamp when processing completed. |
deletedAt |
string (ISO 8601) |
Yes | Timestamp when the enrollment was deleted. |
purgedAt |
string (ISO 8601) |
Yes | Timestamp when the enrollment was purged. |
purgeAt |
string (ISO 8601) |
Yes | Scheduled purge timestamp based on retention policy. |
SpeakerServiceMediaSource
| Field | Type | Nullable | Description |
|---|---|---|---|
type |
string |
No | Source type: UPLOAD or URI_IMPORT. |
filename |
string |
Yes | Original uploaded filename. |
uri |
string |
Yes | Imported URI when type is URI_IMPORT. |
sha256 |
string |
Yes | SHA-256 checksum of the uploaded audio. |
size |
long |
Yes | File size in bytes. |
contentType |
string |
Yes | Media content type, always audio/wav for speaker-service audio. |
durationSeconds |
double |
Yes | Detected audio duration in seconds. Populated upon processing. |
contentRetained |
boolean |
No | Whether raw recording content is currently retained. |
SpeakerServiceEnrollmentEmbeddingResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Embedding identifier. |
enrollmentId |
string (UUID) |
No | Parent enrollment identifier. |
speakerId |
string (UUID) |
No | Parent speaker identifier. |
modelAlias |
string |
Yes | Effective embedding model when this evidence was generated. |
resolvedModel |
string |
No | Resolved embedding model that produced this embedding. |
modelHash |
string |
No | Model space hash for vector compatibility validation. |
dimension |
integer |
No | Embedding vector dimension. |
createdAt |
string (ISO 8601) |
No | Timestamp when the embedding record was created. |
SpeakerServiceAudioSegmentSelection
| Field | Type | Nullable | Description |
|---|---|---|---|
start |
double |
Yes | Start time in seconds. |
end |
double |
Yes | End time in seconds. |
channel |
integer |
Yes | Zero-based audio channel index. |
speaker |
string |
Yes | Optional upstream speaker label from a prior diarization step. |
SpeakerServiceSentenceVerificationRequest
| Field | Type | Required | Description |
|---|---|---|---|
expectedText |
string |
Yes | Sentence the speaker is expected to say. |
model |
string |
No | Sentver model. If omitted, the default sentver model is used. See Sentence Verification Models. |
locale |
string |
No | BCP-47 locale. If omitted, the speaker locale is used; if neither is set, the request is rejected. |
policy |
SpeakerServiceSentenceVerificationPolicy |
No | Gating/scoring policy. |
SpeakerServiceSentenceVerificationPolicy
Optional threshold policy for sentence verification. The default mode is BALANCED. When mode=CUSTOM, you must supply explicit threshold values.
| Field | Type | Required | Description |
|---|---|---|---|
mode |
SentverThresholdMode |
No | Threshold preset. Default: BALANCED. |
acceptThreshold |
double |
Conditional | Required when mode=CUSTOM. Score ≥ this value → ACCEPT. |
reviewThreshold |
double |
No | Used only when mode=CUSTOM. Score in [reviewThreshold, acceptThreshold) → REVIEW. |
SpeakerServiceSentenceVerificationResult
| Field | Type | Nullable | Description |
|---|---|---|---|
expectedText |
string |
Yes | Expected sentence when retained by policy. |
expectedTextSha256 |
string |
No | SHA-256 hash of the expected sentence. |
locale |
string |
Yes | Locale used by the sentver model. |
modelAlias |
string |
Yes | Requested sentver model, or default model when omitted. |
resolvedModel |
string |
Yes | Sentence verification model version that processed the request. If model fallback was used, this is the fallback model. |
fallbackUsed |
boolean |
No | Whether a fallback model was used instead of the primary model. |
decision |
string |
Yes | Sentence decision: ACCEPT, REJECT, or REVIEW. |
score |
float |
Yes | Smart-matching score between the expected text and detected speech. |
thresholdMode |
SentverThresholdMode |
Yes | Threshold mode that was applied. |
acceptThreshold |
double |
Yes | Accept threshold that was applied. |
reviewThreshold |
double |
Yes | Review threshold that was applied. |
reason |
string |
Yes | Human-readable result summary. |
latencyMs |
integer |
Yes | Sentver processing latency. |
confidenceScore |
float |
Yes | Confidence level of the verification result. |
speechRms |
float |
Yes | Root mean square level of the detected speech audio. |
audioSnr |
float |
Yes | Speech/noise SNR of the submitted audio. |
speechSegments |
SentverSpeechSegment[] |
Yes | Speech regions detected in the submitted audio. |
qualityIndicators |
SentverQualityIndicator[] |
Yes | Audio quality issues detected during verification. Empty when no issues are found. |
SentverSpeechSegment
| Field | Type | Nullable | Description |
|---|---|---|---|
startSeconds |
float |
No | Start of the detected speech segment in seconds from the beginning of the audio. |
endSeconds |
float |
No | End of the detected speech segment in seconds. |
SentverQualityIndicator
| Value | Description |
|---|---|
QUALITY_INDICATOR_UNSPECIFIED |
No specific issue or unrecognized indicator. |
SPEECH_TOO_LOW |
Speech volume is too low. |
SPEECH_NOT_DETECTED |
No speech was detected in the submitted audio. |
SPEECH_TOO_FAST |
Speech tempo is too fast for accurate verification. |
SPEECH_TOO_SLOW |
Speech tempo is too slow for accurate verification. |
SPEECH_TOO_LONG |
Speech duration exceeds the expected range. |
SPEECH_TOO_SHORT |
Speech duration is shorter than required for verification. |
SpeakerServiceProcessingError
| Field | Type | Nullable | Description |
|---|---|---|---|
code |
string |
No | Machine-readable processing error code. See SpeakerEnrollmentProcessingErrorCode. |
message |
string |
No | Human-readable description. |
timestamp |
string (ISO 8601) |
No | Timestamp when the error was recorded. |
CommonWebhook
| Field | Type | Required | Description |
|---|---|---|---|
url |
string |
Yes | HTTPS URL receiving enrollment completion notifications. |
secret |
string |
No | Shared secret used to sign payloads with HMAC-SHA256. Responses return only a masked value when a secret is configured. |
headers |
object |
No | Custom HTTP headers. |
Enumerations
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. |
SpeakerEnrollmentStatus
| Value | Description |
|---|---|
READY |
Enrollment completed successfully and can be used as source material for automatic verification. |
REJECTED |
Enrollment was rejected by a policy gate (e.g. sentence verification). The audio was valid but did not pass validation. The user should retry with correct speech. |
FAILED |
Enrollment failed due to a system error. |
SpeakerEnrollmentRejectionCode
| Value | Description |
|---|---|
SENTENCE_MISMATCH |
The enrollment audio did not match the expected sentence. |
SpeakerEnrollmentProcessingErrorCode
| Value | Description |
|---|---|
SENTVER_MODEL_NOT_AVAILABLE |
The selected sentver model and its configured fallback model cannot process this enrollment. |
SENTVER_LOCALE_UNSUPPORTED |
The selected sentver model cannot process the requested or resolved locale. |
UNSUPPORTED_FORMAT |
The media format or codec is not supported. |
MODEL_NOT_AVAILABLE |
The selected embedding model cannot process enrollment, voice-print, or verification work. |
EMBEDDING_MODEL_HASH_MISMATCH |
Source enrollment embeddings have inconsistent model hashes across different vector spaces. |
VOICE_PRINT_BUILD_FAILED |
Voice print embedding build failed. |
SENTVER_MODEL_NOT_CONFIGURED |
Sentver model is not configured or the default is missing. |
SPEAKER_NOT_VERIFICATION_READY |
Speaker is not verification-ready. |
VERIFICATION_INFERENCE_FAILED |
Verification inference call failed. |
INTERNAL_ERROR |
An unexpected internal error occurred. |
Enrollment Lifecycle
Enrollment creation is synchronous: the response always contains a terminal status (READY, REJECTED, or FAILED). Lifecycle: ready/rejected/failed -> deleted -> purged.
REJECTED indicates a policy gate rejection (e.g. sentence verification failed) - the user should record a new enrollment with correct speech. FAILED indicates an unexpected system error - the client may retry automatically.