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

ConceptWhat it is
IdentityAn 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 tagAn 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 engineThe 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 configurationThe 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 configurationThe 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 symbolThe 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 tagA label that distinguishes several enrollments of the same identity in the same enrollment configuration.
Session IDReturned 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.

GroupCallsPurpose
Identity managementCreateIdentity, DisableIdentity, EnableIdentity, RemoveIdentity, GetIdentityStatus, UpdateIdentityTag, UpdateEnrollmentTagCreate and manage identities and tags
EnrollmentInitEnrollment, ProcessEnrollment, FinalizeEnrollmentEnroll an identity
VerificationInitVerification, ProcessVerification, FinalizeVerificationVerify an identity
Enrollment statusIsEnrolled, IsEnrolledInConfiguration, IsEnrolledWithTag, GetEnrollmentsCheck whether and how an identity is enrolled
InformationGetBiometricConfigurationList 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.

FormataudioFormat 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.

StepCallWhat you sendWhat happens
1CreateIdentityAn identityTagCreates the identity and returns its symbol. Do this once per person.
2InitEnrollmentenrollmentSymbol, identitySymbol, audioFormat, enrollmentTagThe 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.
3Prompt the caller
Your application plays the prompt and records the caller’s response.
4ProcessEnrollmentThe sessionId, and the Base64 audio in the bodyThe engine decides whether the audio is enough. It returns InProgress with the next prompt, a quality statusHint if the audio was poor, or Successful.
5Repeat step 4
Keep calling ProcessEnrollment with new audio until the status is no longer InProgress.
6FinalizeEnrollmentThe sessionIdCompletes 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 Successful status, 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.

StepCallWhat you sendWhat happens
1Identify the claim
Your application gets the caller’s claimed identity (a username or telephone number, for example) and retrieves the matching identity symbol.
2InitVerificationverificationSymbol, identitySymbol, audioFormat, enrollmentTagThe 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.
3ProcessVerificationThe sessionId, a randomPhrase, and the Base64 audio in the bodyThe platform evaluates the audio against the thresholds. It returns InProgress with more to say, a quality statusHint, or a final result.
4Repeat step 3
Keep calling until the status is Successful or Rejected.
5FinalizeVerificationThe sessionIdCompletes 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 scoreResult
Equal to or above the success threshold (ST)Successful
Equal to or below the failure threshold (FT)Rejected
Between the twoInProgress. 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.

StatusEnrollmentVerification
InProgressMore data is required.More data is required.
SuccessfulThe enrollment succeeded.The caller’s identity was verified.
RejectedNot applicable.The verification attempt was rejected.
FailedProcessing failed because of a system condition, such as an exhausted subscription or another operation in progress. Take action to fix it.The same.
QualityRejectedThe caller could not produce enough good-quality data.The same.
ReplayRejectionThe system detected that an existing audio file is being replayed.The same.
TimeoutThe session reached a predefined timeout.The same.
AbortedThe application is not accepting additional requests.The same.
CanceledThe 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 hintMeaning
DataProcessedThe submitted audio was processed successfully.
NoSpeechNo speech was detected. Check that the audio was captured and submitted in the correct format.
WrongContentThe requested prompt was not recognized. The caller should repeat the phrase exactly.
SpeechQualityInsufficientThe voice quality measurements were unsuccessful. Try a cleaner recording, with less echo or a better channel.
PlaybackDetectedThe audio was detected to have been submitted previously.
VolumeTooLowThe volume is too low. Increase the amplification or speak louder.
TooMuchNoiseThe signal-to-noise ratio is low, so a lot of background noise was detected. Record in a quieter environment.
VolumeTooHighThe volume is very high, close to clipping. Decrease the amplification or speak softer.
TooManySamplesClippedThe recording clipped, so the volume is much too high.
InconsistentRepetitionA successive enrollment phrase did not match the previous phrases. Do not change the prompt or the speaker during enrollment.
LengthTooShortThe recording was shorter than expected.
SampleTooLongThe 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.
  • Failed status: problems inside the system produce a Failed status. Restart the whole process, beginning with InitEnrollment or InitVerification.
  • Finalize errors: if FinalizeEnrollment or FinalizeVerification returns 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 Failed and a statusHint.

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

SymptomLikely cause and fix
InitEnrollment or InitVerification fails immediatelyAnother 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 enrolledAn identity needs at least one successful enrollment first. Check IsEnrolled or GetEnrollments.
Enrollment ends in QualityRejectedToo 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 submissionThe audio is not being captured or not in the declared format. Check audioFormat and that the audio is headerless and Base64-encoded.
WrongContent repeatedlyThe caller is not repeating the prompted phrase exactly.
PlaybackDetected or ReplayRejectionThe 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 CanceledA second session was started for the same identity. Run one enrollment per identity at a time.
A response is not finalKeep calling ProcessEnrollment or ProcessVerification while the status is InProgress, and finalize only when it is not.

Related Articles


Was this article helpful?