Speaker Services - Enrollments
Manage speaker enrollments, enrollment reset, and retained enrollment recordings used for debugging. Enrollments are model-agnostic audio samples - embedding extraction happens at voice-print build time. Sentver model aliases 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. |
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 alias not found. |
409 Conflict |
Speaker is deleted, disabled, archived, or no tenant default sentver alias 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 embedding records that have been extracted and cached for an enrollment by voice-print preview or voice-print creation workflows.
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 cached enrollment embedding 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, the speaker default voice print is cleared, 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 | Requested embedding model alias. |
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 alias. If omitted, the tenant default sentver alias 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 alias, or tenant default alias when omitted. |
resolvedModel |
string |
Yes | Concrete sentver model that processed the request. If alias fallback was used, this is the fallback model. |
fallbackUsed |
boolean |
No | Whether a fallback model was used instead of the primary model for the alias. |
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 voice-print creation. |
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 alias 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. |
VOICE_PRINT_NOT_READY_FOR_MODEL |
No usable voice print is available for the requested or default model. |
SENTVER_MODEL_NOT_CONFIGURED |
Sentver model alias is not configured or the tenant 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.