Voice Biometrics Concepts and Integration Flows
A voice biometrics integration is a conversation, not a single call. Your application prompts the caller, captures what they say, and submits it. The platform answers either with a decision or with a request for more, and your application keeps going until it gets one. Most integration mistakes come from treating it like a one-shot lookup: not looping while the status is still in progress, ignoring the hints that say why audio was rejected, or skipping the call that closes a session. This article explains the concepts behind the platform and the enrollment and verification flows, so you can build the loop correctly the first time.
Scope. This article covers the REST API for active voice biometrics, where the speaker repeats a passphrase. For what the product does and how it defends against fraud, see Active Voice Biometrics Product Overview and Active Voice Biometrics Product Information. Thresholds, quality gates, and the other configuration settings are in the Voice Biometrics Configuration Reference. The headers every request needs are in API Access, Authentication and Required Headers.
How it works
The platform works in a challenge-response manner. Your application starts a session and tells the platform which configuration to use. That configuration decides what to ask the caller for, such as a specific passphrase. Each response from the platform tells your application what to do next: collect more audio, or finish because the process succeeded or failed.
Core concepts
| Concept | What it is |
|---|---|
| Identity | An entity that is enrolled in the platform and whose identity the system can ascertain. The platform stores no personally identifiable data about the person, such as name or address, so voice biometric data cannot be linked to a real person from inside the platform. Several enrollments can belong to one identity, for example one for an IVR and one for a smartphone application, and one person can have several identities. |
| Identity tag | An alias you attach to an identity. Use a de-identified reference, such as a GUID, or keep the mapping from the identity to the real user in your own system. |
| Biometric engine | The most basic component of an authentication process. The platform provides built-in engines for different modalities: active (fixed passphrase, text-dependent), prompted (random passphrase), passive (text-independent), and hybrid (for example, enrolling passively and verifying actively). |
| Enrollment configuration | The full instructions for enrolling an identity with a specific engine: how many repetitions are required, which keywords are used, how long the process may take, and how audio quality is validated. |
| Verification configuration | The rules for verifying an identity, including how many phrases may be asked, the score thresholds for acceptance and rejection, and the audio quality thresholds. Different verification configurations can represent different strengths of authentication, so your application can use a heightened one for sensitive transactions. |
| Configuration symbol | The GUID that identifies an enrollment, verification, or engine configuration. Your application supplies the enrollment symbol when it enrolls, and the verification symbol when it verifies. |
| Enrollment tag | A label that distinguishes several enrollments of the same identity in the same enrollment configuration. |
| Session ID | Returned when you start an enrollment or verification. You pass it on every later call in that process. |
The REST API at a glance
The Voice Biometrics API is a REST API. Its paths begin with /biometric/, and every request carries the identifiers described in API Access, Authentication and Required Headers. Communication with external systems is protected with TLS 1.2.
| Group | Calls | Purpose |
|---|---|---|
| Identity management | CreateIdentity, DisableIdentity, EnableIdentity, RemoveIdentity, GetIdentityStatus, UpdateIdentityTag, UpdateEnrollmentTag | Create and manage identities and tags |
| Enrollment | InitEnrollment, ProcessEnrollment, FinalizeEnrollment | Enroll an identity |
| Verification | InitVerification, ProcessVerification, FinalizeVerification | Verify an identity |
| Enrollment status | IsEnrolled, IsEnrolledInConfiguration, IsEnrolledWithTag, GetEnrollments | Check whether and how an identity is enrolled |
| Information | GetBiometricConfiguration | List the available engines and their configuration GUIDs |
The enrollment and verification calls are under /biometric/Active/ and the identity and status calls under /biometric/Identity/. Configurations are managed through the Management API or the Deployment Portal, not through this API.
Preparing the audio
Your application must be able to record audio in one of three formats, and encode it as a Base64 string. The audio is sent as headerless audio in the body of the request.
| Format | audioFormat value |
|---|---|
| Linear signed PCM, 16-bit, 8 kHz (may be headerless) | Pcm8Khz |
| A-law compressed, 8-bit, 8 kHz (may be headerless) | Alaw8Khz |
| u-law compressed, 8-bit, 8 kHz (may be headerless) | Ulaw8Khz |
Enrollment flow
Enrollment creates a voiceprint for an identity. The identity must exist first, so create it with CreateIdentity.
| Step | Call | What you send | What happens |
|---|---|---|---|
| 1 | CreateIdentity | An identityTag | Creates the identity and returns its symbol. Do this once per person. |
| 2 | InitEnrollment | enrollmentSymbol, identitySymbol, audioFormat, enrollmentTag | The platform checks your permissions and that the identity exists. In a normal case it returns InProgress, a sessionId, and the prompt the caller should speak. |
| 3 | Prompt the caller | Your application plays the prompt and records the caller’s response. | |
| 4 | ProcessEnrollment | The sessionId, and the Base64 audio in the body | The engine decides whether the audio is enough. It returns InProgress with the next prompt, a quality statusHint if the audio was poor, or Successful. |
| 5 | Repeat step 4 | Keep calling ProcessEnrollment with new audio until the status is no longer InProgress. | |
| 6 | FinalizeEnrollment | The sessionId | Completes the enrollment session and returns the voiceprint symbol. Call it in every case. |
- If poor audio keeps arriving, enrollment ends with
QualityRejected, because the caller could not produce enough good-quality data. - After a
Successfulstatus, you can add more audio to the enrollment session, for example when you already collected extra samples. - You can enroll the same identity more than once. For repeat enrollments in the same enrollment configuration, give each a different
enrollmentTag. The most recent enrollment is used by default. - An identity needs at least one successful enrollment before it can be verified.
Verification flow
Verification checks a caller against an enrolled identity.
| Step | Call | What you send | What happens |
|---|---|---|---|
| 1 | Identify the claim | Your application gets the caller’s claimed identity (a username or telephone number, for example) and retrieves the matching identity symbol. | |
| 2 | InitVerification | verificationSymbol, identitySymbol, audioFormat, enrollmentTag | The platform checks your permissions, that the identity exists, and that it is enrolled. In a normal case it returns InProgress, a sessionId, and the prompt. |
| 3 | ProcessVerification | The sessionId, a randomPhrase, and the Base64 audio in the body | The platform evaluates the audio against the thresholds. It returns InProgress with more to say, a quality statusHint, or a final result. |
| 4 | Repeat step 3 | Keep calling until the status is Successful or Rejected. | |
| 5 | FinalizeVerification | The sessionId | Completes the verification session. Call it in every case. |
The prompt content comes from the verification configuration and from the enrollment configuration the identity was enrolled with. The API reference marks the randomPhrase query parameter on ProcessVerification as required.
How the thresholds decide the result
Once the collected data meets the verification configuration’s requirements, the platform compares the consolidated score with its thresholds.
| Consolidated score | Result |
|---|---|
| Equal to or above the success threshold (ST) | Successful |
| Equal to or below the failure threshold (FT) | Rejected |
| Between the two | InProgress. The platform keeps prompting for more audio until the maximum number of phrases is reached, then compares the result with the completion threshold (CT) to decide between Successful and Rejected. |
The values of these thresholds, and how to choose them, are in the Voice Biometrics Configuration Reference.
Status values
Each response carries a ProcessingStatus, interpreted in the context of the process you are running, and a StatusText with diagnostic information in the platform’s system language.
| Status | Enrollment | Verification |
|---|---|---|
InProgress | More data is required. | More data is required. |
Successful | The enrollment succeeded. | The caller’s identity was verified. |
Rejected | Not applicable. | The verification attempt was rejected. |
Failed | Processing failed because of a system condition, such as an exhausted subscription or another operation in progress. Take action to fix it. | The same. |
QualityRejected | The caller could not produce enough good-quality data. | The same. |
ReplayRejection | The system detected that an existing audio file is being replayed. | The same. |
Timeout | The session reached a predefined timeout. | The same. |
Aborted | The application is not accepting additional requests. | The same. |
Canceled | The caller started a second session for the same identity, so the first one is cancelled. | Not applicable. |
Status hints
A statusHint explains why audio was not accepted, so your application can change what it asks the caller to do, for example to speak a little louder. Active enrollments can return speech quality hints. Your application should ignore any hint it does not recognize and treat it as unknown.
| Status hint | Meaning |
|---|---|
DataProcessed | The submitted audio was processed successfully. |
NoSpeech | No speech was detected. Check that the audio was captured and submitted in the correct format. |
WrongContent | The requested prompt was not recognized. The caller should repeat the phrase exactly. |
SpeechQualityInsufficient | The voice quality measurements were unsuccessful. Try a cleaner recording, with less echo or a better channel. |
PlaybackDetected | The audio was detected to have been submitted previously. |
VolumeTooLow | The volume is too low. Increase the amplification or speak louder. |
TooMuchNoise | The signal-to-noise ratio is low, so a lot of background noise was detected. Record in a quieter environment. |
VolumeTooHigh | The volume is very high, close to clipping. Decrease the amplification or speak softer. |
TooManySamplesClipped | The recording clipped, so the volume is much too high. |
InconsistentRepetition | A successive enrollment phrase did not match the previous phrases. Do not change the prompt or the speaker during enrollment. |
LengthTooShort | The recording was shorter than expected. |
SampleTooLong | The recording is too long. Shorten the utterance. |
The audio quality thresholds that produce these hints are described in the Voice Biometrics Configuration Reference. The status text can be configured to include all the measurements for a sample, such as biometric scores and quality measurements.
Errors and retries
- Exceptions are returned for problems with the parameters you submit or with permissions, such as an identity that does not exist or a request that is not allowed.
Failedstatus: problems inside the system produce aFailedstatus. Restart the whole process, beginning withInitEnrollmentorInitVerification.- Finalize errors: if
FinalizeEnrollmentorFinalizeVerificationreturns an error (the result is false), repeat the call. An error from the finalize call does not change the outcome of an enrollment that was already completed. - One operation per identity: if another operation for the same identity is in progress, or the subscription has been exhausted, the call fails with
Failedand astatusHint.
Scale and availability
The platform can run several service instances for high availability and throughput. Session state is persisted in a local or network cache, or in the database cluster, so any load balancer can distribute your requests.
Examples
Create an identity. The identifiers go in headers, and the scope for the Voice Biometrics API is VB:
| curl --request POST \ 'https://biometric-api.example.com/biometric/Identity/CreateIdentity?identityTag=<identity-reference>' \ --header 'x-correlation-id: <unique-guid>' \ --header 'x-deployment-id: <your-deployment-id>' \ --header 'x-operator-id: <your-operator-id>' \ --header 'x-scopes: VB' |
Start an enrollment:
| curl --request POST \ 'https://biometric-api.example.com/biometric/Active/InitEnrollment?enrollmentSymbol=<enrollment-config-guid>&identitySymbol=<identity-guid>&audioFormat=Pcm8Khz&enrollmentTag=<tag>' \ --header 'x-correlation-id: <unique-guid>' \ --header 'x-deployment-id: <your-deployment-id>' \ --header 'x-operator-id: <your-operator-id>' \ --header 'x-scopes: VB' |
The response carries the SessionId, the ProcessingStatus (normally InProgress), and the CurrentPrompt to play. Pass the SessionId to ProcessEnrollment with your audio.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
InitEnrollment or InitVerification fails immediately | Another operation for the same identity is in progress, the subscription is exhausted, or the identity does not exist. Check the statusHint and the identity. |
| Verification fails because the identity is not enrolled | An identity needs at least one successful enrollment first. Check IsEnrolled or GetEnrollments. |
Enrollment ends in QualityRejected | Too many samples failed the quality checks. Use the status hints to guide the caller, and check the audio path for noise, clipping, or low volume. |
NoSpeech on every submission | The audio is not being captured or not in the declared format. Check audioFormat and that the audio is headerless and Base64-encoded. |
WrongContent repeatedly | The caller is not repeating the prompted phrase exactly. |
PlaybackDetected or ReplayRejection | The audio was already submitted, or a recording was replayed. This also happens when you retest with the same file. |
The first enrollment session ends as Canceled | A second session was started for the same identity. Run one enrollment per identity at a time. |
| A response is not final | Keep calling ProcessEnrollment or ProcessVerification while the status is InProgress, and finalize only when it is not. |
