voicevault fusion api user guide · fusion api user guide company confidential page 6 of 60...

Fusion API User Guide


Company Confidential of 60

Title: Fusion API User Guide

Part number: VV/GUIDE/ALL/101/1.1

Copyright © 2018 VoiceVault Inc. All rights reserved.

This document may not be copied, reproduced, transmitted or distributed in part or in

whole by any means without the prior written approved VoiceVault Inc.

The content of this document is provided “as-is” and for informational use only. The

information contained in this document is subject to change without notice and should not

be interpreted as a commitment by VoiceVault Inc. and VoiceVault Inc. assumes no

responsibility or liability for any errors or inaccuracies that may appear in this document.

Except as permitted by such license, no part of this publication may be reproduced, stored

in a retrieval system or transmitted, in any form or by any means, electronic, mechanical,

recording or otherwise, without the prior written permission of VoiceVault Inc.

All trademarks and trade names mentioned herein are hereby acknowledged and

recognized as property of their respective owners.

VoiceVault Inc.

400 Continental Blvd

6th Floor

El Segundo

CA 90245

USA

(310) 426 2792

[email protected]

mailto:[email protected]



Contents Contents ......................................................................................................................... 3

Introduction .................................................................................................................... 5

VoiceVault Fusion Overview ....................................................................................................................... 5

ViGo ............................................................................................................................................................................ 5

Claimants ................................................................................................................................................................ 5

Configurations ...................................................................................................................................................... 6

Dialogue .................................................................................................................................................................. 7

Interacting with the API................................................................................................... 8

Enrolment ........................................................................................................................................................... 9

Verification ...................................................................................................................................................... 11

API Logic ....................................................................................................................... 13

Conditional Logic Flow ............................................................................................................................... 14

Conditional Logic Pseudo code ............................................................................................................... 15

Using the Fusion API ...................................................................................................... 19

Biometric Operations .................................................................................................... 21

RegisterClaimant .......................................................................................................................................... 22

StartDialogue .................................................................................................................................................. 24

StartDialogueOneToFew ........................................................................................................................... 27

SubmitPhrase ................................................................................................................................................. 30

SubmitPhraseBase64 .................................................................................................................................. 35

GetDialogueSummary ................................................................................................................................. 40

AbortDialogue ................................................................................................................................................ 43

AdaptClaimant ............................................................................................................................................... 45

DeleteClaimant .............................................................................................................................................. 47

RequestStatus Enumeration .......................................................................................... 49

DialogueStatus Enumeration ......................................................................................... 51

FailureReason Enumeration ........................................................................................... 52



StatusCode Enumeration ............................................................................................... 53

SQMDecision Enumeration ............................................................................................ 54

VerificationDecision Enumeration ................................................................................. 56

Language Enumeration .................................................................................................. 57



Introduction The VoiceVault Fusion API is implemented as a simple web service

exposing the most common VoiceVault Fusion operations that are used

to drive the user enrolment and verification processes.

The more functional VoiceVault Biometric and Management APIs upon

which this API is based are SOAP-based web services and are

documented separately.

The following sections provide a guide to the usage of these methods,

including interpretation of results, and success / failure scenarios.

First however, is an overview of the fundamental concepts behind the

VoiceVault Fusion platform. Understanding these concepts is key to

the successful implementation of any application based on this API.

VoiceVault Fusion Overview

ViGo

ViGo is a suite of SDKs and libraries that simplify the process of

integrating VoiceVault Fusion into mobile applications.

The VoiceVault ViGo libraries for iOS and Android take care of

communication with the Fusion API on your behalf, meaning that you

do not need to interface with it directly at all.

Please refer to the ViGo developer documentation, available on our

website, for more information on these libraries.

Claimants

A claimant is the representation of a real world individual within the

VoiceVault system.

The claimant is identified within the VoiceVault system by a unique

blind identifier that stays with the voice model for that claimant for the

life of the voice model. As a consequence of the blind identifier, no

personal information about the claimant is known to or stored by the

VoiceVault Fusion biometric system. The identifier is mapped to the

real user in the customer application, outside the VoiceVault system.

A claimant can enroll in one or more languages or “modes” (e.g. digit

or passphrase mode); these enrolments can then be used with any



configuration relating to those languages or modes (configurations are

described in more detail below).

Access control to the voice biometric engine (i.e. which of the possible

users are allowed to voice verify under a specific configuration) must

be handled by the external application.

Claimant identifiers can be disabled and this can be used to revoke that

identifier (they cannot be deleted). Disabling an identifier preserves

the audit trail / history associated with the identifier. Identifiers must

not be re-used or recycled for a different real-world user.

In order to obtain a valid claimant identifier, an external application

must register that claimant before it can be used. This registration

operation creates the necessary information within the VoiceVault

system to support the claimant identifier and then returns the

identifier to the external application so that it can be mapped to

information relating to an actual person.

Remember that when VoiceVault generates a claimant identifier for

use by the external application, VoiceVault Fusion has no knowledge of

whom the identifier will be assigned to, and nor will it ever need to.

Note: The Fusion API will reject an attempt to use a claimant identifier

that has not previously been registered with the VoiceVault system.

Configurations

A VoiceVault Fusion configuration is a related group of settings that

defines a single use case for the VoiceVault system. Each configuration

is uniquely identified and this identifier is used by customer

applications to call the VoiceVault biometric functions to obtain voice

verification functionality.

Configurations have been set up and an configuration IDs provided by

VoiceVault as part of your access credentials.

A configuration represents one possible use of a single language pack

with a particular set of accept and reject thresholds and it is an

important part of an organisation’s security policy, as it defines the

biometric configuration for a particular customer application. The

threshold settings within a configuration directly affect the False

Accept versus False Reject rates that a system will operate at and can

be tuned for better caller experience (i.e. less False Rejects) or higher

security (i.e. less False Accepts).



Many configurations can be deployed to represent different uses of the

system.

Different customer applications with different requirements can use

different configurations, or different customer applications with the

same requirements can use the same configuration. It is also possible

for a single customer application to use multiple configurations to

support different security levels.

Please contact VoiceVault if you have specific application requirements

that lead you to require different configuration settings.

Dialogue

A dialogue is the term used to refer to an on-going voice verification

session through the VoiceVault Fusion API.

When a customer application needs to enroll or verify a claimant it

must first instruct the API to start a dialogue.

The dialogue directs the customer application to gather speech from

the claimant, and the speech is submitted into the dialogue. On an

ongoing basis the dialogue provides a summary of the current status,

which indicates whether (and what) further speech is required and

whether the claimant is accepted or rejected.



Interacting with the API The VoiceVault Fusion programming model is very simple - the same

interaction model is used both for enrolment and verification. This

greatly simplifies application development with the VoiceVault

Fusion API.

Simply by changing the configuration of VoiceVault Fusion you can

deploy, using this simple interaction model, a wide range of different

call flows. What this means in practice is that changes to these

system settings (see examples below) do not require any application

code changes. The SubmitPhrase method uses the configuration

settings to drive the dialogue interaction with the user.

Some of the many changes that can be made include

• The number of enrolment utterances to prompt the user for

• The minimum number of verification utterances

• The maximum number of SQM (signal quality measurement)

errors that will be permitted

The default settings for your configuration will have been provided to

you as part of your registration.



Enrolment

The process flow for enrolling a user with the VoiceVault Fusion system

is shown in Figure 1.

The application must start by obtaining a claimant identifier for the

user using RegisterClaimant. It is likely that each application

installation (or device) will require a separate claimant identifier, but it

is also possible for an application to allow a user to register and

manage multiple identities.

Once an identifier has been obtained the application makes a call to

start the dialogue (using StartDialogue) with the VoiceVault Fusion

system, which responds by requesting that the user speak a 4-digit

phrase.

The application must record the user speaking the required phrase and

send the recording back to VoiceVault Fusion via the SubmitPhrase

method, which in turn provides status on the progress of the dialogue

and the next phrase (if any) to prompt the user for. The configuration

settings determine the behaviour of the SubmitPhrase method.



Figure 1 - Process flow for enrolling a user with VoiceVault Fusion

Once the application has provided VoiceVault Fusion with sufficient

phrases (as defined by the configuration) the application enters a

polling state, waiting for all of the user inputs to complete processing.

At this point the system indicates back to the application either that

additional phrases are required or that the process is complete.



Verification

The process flow for verifying a user with VoiceVault Fusion is shown in

Figure 2.

In this case the application already knows the claimant identifier (as it

was created and used at enrolment time).

Exactly as with enrolment, the application makes a call to start the

dialogue.

The application then records the user speaking the required phrase and

sends the recording back to VoiceVault Fusion via the SubmitPhrase

method, which in turn provides status on the progress of the dialogue

and the next phrase (if any) to speak.

Once the application has provided VoiceVault Fusion with sufficient

phrases, the application enters a polling state, waiting for all of the

inputs to complete processing. At this point the system indicates

either that additional phrases are required or that the process is

complete and that the user has been successfully verified or has been

rejected. The application will decide how to proceed once it has been

informed of the verification / rejection decision.

Note that the accept / reject threshold settings within the

configuration determine if a user will be accepted or rejected. These

threshold values are not modifiable by application developers.



Figure 2 - Process flow for verifying a user with VoiceVault Fusion



API Logic The way that your application interacts with the VoiceVault Fusion biometric engine

is encompassed by the logical use of the key API methods:

• StartDialogue

• SubmitPhrase

• GetDialogueSummary

• AbortDialogue

Specifically, the values for DialogueStatus and RequestStatus define the conditional

logic for what methods to call and when. This logic is defined visually as a flow

chart and as pseudo code in the sections below.



Conditional Logic Flow



Conditional Logic Pseudo code

This pseudo code provides an example of the conditional logic for processing a

DialogueSummary object returned from a call to the Biometric API SubmitPhrase()

or GetDialogueSummary() methods.

Note the following:

• AbortDialogue should only be called when the RequestStatus shows that

there is an irrecoverable error. This might be for example if the

Configuration ID that has been passed doesn’t exist – in this scenario, there

is no way that the dialogue can proceed.

• An irrecoverable error is different to the Error state of the DialogueStatus

as it is essentially business logic error that indicates an incorrect

configuration of the application, as opposed to an unexpected exception.

As such, the irrecoverable error state will be of most use at development

time as a correctly configured and operational system should not, in theory,

encounter an irrecoverable error.

• The decision to call SubmitPhrase (to prompt the user for a spoken phrase)

should be based exactly on the logic described. If PromptHint option is

enabled, and if the logic dictates that SubmitPhrase should be called, the

appropriate PromptHint will always be present.

• The VoiceVault Fusion API is asynchronous. What this means in practice is

that when you call SubmitPhrase you provide us with some audio that we

put on a work queue and return control to you immediately, returning the

current state of the dialogue at the precise instant in time. The information

we return may or may not include the result of the audio you just

submitted, indeed it only will include that result if we manage to process

the audio instantaneously following submission. This means that your

application can continue to gather additional speech from the user (if so

required and indicated by the information returned to you) while we are

processing your previous submission.

• In practice this means that you can execute a hard loop getting the user to

speak the prompt hint and calling SubmitPhrase until we return

TooManyUnprocessedPhrases (or a termination state). When

TooManyUnprocessedPhrases is returned, you must proceed to a loop

calling GetDialogueSummary until either a termination state is reached or

you need to return to the SubmitPhrase loop.

• There is no need to try to wait for the completion of processing of your

previous submission between SubmitPhrase calls, and no need to call

GetDialogueSummary between SubmitPhrase calls (unless so indicated by

the return status TooManyUnprocessedPhrases).

• It is important to build a timeout into the polling loop on

GetDialogueSummary and an appropriate value would be around five



seconds. Note however that if the timeout is triggered there is no way tot

recover the dialogue and SubmitPhrase should not be called again – in fact

as the dialogue will have been aborted, the appropriate call would be to

AbortDialogue. This is because the application is in a state where it has not

completed processing, which needs to happen before the dialogue can

proceed.

if (Dialogue_Status = 0)

if (Request_Status = 0)

//All OK, continue

SubmitPhrase()

else if (Request_Status = 10)

//Wait, and poll

GetDialogueSummary()

else if (Request_Status = 5 or 6 or 7 or 11)

//Recoverable error

SubmitPhrase()

else

//Irrecoverable, dialogue cannot continue

AbortDialogue()

end if

else if (Dialogue_Status = 1)

if (Process_Type = 1)

Dialogue Complete… Enrolment succeeded

(valid result)

else

Dialogue Complete… Verification succeeded

(valid result)

end if

else if (Dialogue_Status = 2)

if (Failure_Reason = 5)

Dialogue Complete… Verification failed

(valid result)

else



//Dialogue error, dialogue terminated

Dialogue Complete… Dialogue failed

(invalid result)

end if

else

//Dialogue error or otherwise terminated, cannot

continue

Dialogue Complete… Dialogue failed

(invalid result)

end if

The following enumerations are used in this context:

Dialogue_Status

0 = Started

1 = Succeeded

2 = Failed

3 = Error

4 = Aborted

5 = Abandoned

Request_Status

0 = OK

1 = DialogueDoesNotExist

2 = ExchangeDoesNotExist

3 = ClaimantDoesNotExist

4 = ConfigurationDoesNotExist

5 = RequestProcessingError

6 = GeneralSystemError

7 = NoSample

8 = InvalidProcessTypeRequest

9 = DuplicatePhrase

10 = TooManyUnprocessedPhrases

11 = WrongPhraseSubmitted

12 = ClaimantIsNotEnabled

13 = NoSpecifiedClaimantRegistered

14 = NoSpecifiedClaimantEnrolled

15 = NoActiveSettings

16 = DialogueAlreadyInProgress

17 = AutoReEnrolment

18 = ConfigurationIsNotEnabled



ProcessType

0 = Unknown

1 = Enrol

2 = Verify

3 = Migration

4 = Adapt

FailureReason

0 = NotSet

1 = MaxTotalSqmFailuresExceeded

2 = MaxPhraseSqmFailuresExceeded

3 = MaxTotalVerifyFailuresExceeded

4 = MaxTotalSystemErrorsExceeded

5 = VerificationFailed

6 = Abandoned

7 = RecordingDetected

8 = PassphraseInvalid



Using the Fusion API The Fusion API is called using simple HTTP POST operations.

The URL prefix for the Fusion API will be provided to you in a separate

document.

As credentials are passed in plain text to the Fusion API, all

communications must be over an SSL transport.

A typical HTML form to submit a request to the Fusion API will look

similar to this:

<html>

<head>

<title> Fusion API Test </title>

</head>

<body>

<form method="POST"

action="https://server/FusionApi/RegisterClaimant.ashx">

<label for="username">Username:</label>

<input type="text" id="username" name="username" value=""/>

<br/>

<label for="password">Password:</label>

<input type="password" id="password" name="password" value=""/>

<br/>

<label for="organisation_unit">Org Unit Id:</label>

<input type="text" id="organisation_unit" name="organisation_unit"

value=""/>

<br/>

<input type="submit" name="Submit" value="Submit"/>

</form>

</body>

</html>



A typical XML response will look like this:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<response_info xmlns="http://www.voicevault.com">

<status_code>0</status_code>

<message>success</message>

<claimant_id>86e5c4a7-91e2-4854-8096-c400620977b1</claimant_id>

</response_info>

If an error occurs during processing the status code returned will be

non-zero and the accompanying XML tag “message” will contain a

human readable string that may assist with debugging the problem. In

this error case none of the other method dependent tags will contain

data. The third party application must be prepared to parse empty

tags.



Biometric Operations The operations exposed by the Fusion API are as follows:

1. RegisterClaimant – this operation is used to obtain a

blinded identifier that can be used to associate a real world

identity in your application with a biometric identity in the

ViGo system.

2. StartDialogue – this operation is always the first to be

called when initiating a biometric process, for either

enrolment or verification.

3. StartDialogueOneToFew – this operation is a variant of

StartDialogue used in “1:few” mode. Please see the

detailed method definition below for a description of this

mode and its implications.

4. SubmitPhrase – once a dialogue has been initiated, this

operation is used to submit utterances for processing.

5. GetDialogueSummary – this method is used when the user

does not wish to submit any further phrases for the current

dialogue, and simply wishes to see the current processing

status.

6. AbortDialogue - this method should be used when the

caller hangs up prematurely. Note that if this method is not

used when a caller hangs up during enrolment, the

claimant identifier associated with that caller cannot

immediately be used to begin a subsequent enrolment

dialogue.

7. AdaptClaimant – this operation can be used to introduce

new verification audio material into a claimants’ enrollment

model.

8. DeleteClaimant – this method can be used to ensure that

all biometric information is removed for a particular

claimant.



RegisterClaimant

This operation is used to register a new claimant within the VoiceVault

Fusion system.

It creates a new claimant record in the database within the specified

organisation unit and returns a new claimant identifier GUID. Newly

registered claimants are enabled by default.

You can find your organisation unit ID, as well as your API username

and password in the welcome email you received when you registered.

The identifier returned should be used to reference a specific user in all

future transactions and must remain associated with that user for the

life of the application. Identifiers must not be re-used, or recycled,

with a different real-world user. A user can, however, have multiple

claimant identifiers associated with them and the application will

manage the mapping of the identifier(s) to real-world data relating to

the user.

Method: POST

Encoding: application/x-www-form-urlencoded

URL: https://<url_prefix>/RegisterClaimant.ashx



Parameters

Parameter Description

username The username of the service account

attempting to access the Fusion API.

Provided as part of your API access

credentials.

Must not be NULL.

password The password of the service account



credentials.

Must not be NULL.

organisation_unit The organization unit within which the

claimant is to be registered.


credentials.

Must not be NULL.

Outputs


status_code The status of the request.

Zero means success, otherwise an error

has occurred and the message field will

be relevant.

See StatusCode section below for more

details.

message If status_code is non-zero then this field

will indicate more precisely the cause of

the error.

claimant_id The claimant identifier that has been

registered in the system and can be used

for future biometric operations.



StartDialogue

This operation creates a new dialogue that is then used as a reference

for all submitted phrases in the current enrolment or verification

attempt.

The operation requires:

• The ID of the configuration to be used for this enrolment or

verification attempt

• The claimant against which to enrol or verify

• A user reference that can be used later for reporting purposes.

• The language of the passphrase (language is a required

parameter even though it is ignored for verification modes

other than passphrase).

The configuration ID for use with this operation will have been

provided in the welcome email you received when you registered.

The claimant ID must have been previously created using the

RegisterClaimant method.

The value for the externalCallRef parameter can be either left empty

(null), or populated with a reference that can later be used to search

for the dialogue using the VoiceVault Management API (not part of the

Fusion API). For example, an IVR call reference number could be used

as a value for externalCallRef, in order to facilitate the correlation of

dialogues with their associated IVR sessions.

The Language parameter is “EnglishUnitedStates“ unless otherwise

communicated to you (other available languages are listed in the

Language Enumeration section).

Method: POST


URL: https://<url_prefix>/StartDialogue.ashx



Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.

configuration_id The configuration identifier against

which the dialogue should be started.


credentials.

Must not be NULL.

claimant_id The claimant identifier, against which

the dialogue should be started,

previously returned by the

RegisterClaimant operation.

Must not be NULL.

external_ref An arbitrary reference you create that

will be used to tag the dialogue to assist

you with future searching.

language An enumerated type that is only used in

passphrase mode (it is a required

parameter but it is ignored in other

modes).

Must not be NULL.

Outputs





Zero means success, otherwise an

error has occurred and the message

field will be relevant.

See StatusCode section below for

more details.

message If status_code is non-zero then this

field will indicate more precisely the

cause of the error.

dialogue_id This GUID must be stored by the

application, since it must be supplied

as a parameter to all future

operations for the current dialogue.

process_type This is an enumeration that informs

the user which type of dialogue has

been created. This is entirely

dependent on the status of the

supplied claimant.

If the claimant is not enrolled, the

ProcessType will be ENROL,

otherwise VERIFY.

prompt_hint This, if set, tells the user which

phrase should be submitted next for

the current dialogue.

Once a dialogue has been successfully created, as indicated by a

StatusCode of “0” and a valid dialogue_id, the subsequent operations

should be used to interact with it.



StartDialogueOneToFew

This operation creates a new verification dialogue that is then used as a

reference for all submitted phrases.

Note: This variant of StartDialogue is intended for use only in “1:few”

mode. In this use-case, several real-world individuals share access to an

account that requires biometric authentication. For example, a joint

bank account.

Please contact VoiceVault Support if you wish to use 1:few mode in

your application, as there are implications for performance and

scalability that are outside the scope of this document. 1:few mode is

not available for free trial customers.


• The ID of the configuration to be used for this verification

attempt

• The list of claimants against which to verify

• A user reference that can be used later for reporting purposes.

• The Language parameter is “EnglishUnitedStates“ unless

otherwise communicated to you (other available languages are

listed in the Language Enumeration section).

The configuration ID for use with this operation will have been

provided in the welcome email you received when you registered.

The claimant IDs must have been previously created using the

RegisterClaimant method and individually enrolled using a common /

shared phrase or set of digits.

The value for the externalCallRef parameter can be either left empty

(null), or populated with a reference that can later be used to search

for the dialogue using the VoiceVault Management API (not part of the

Fusion API). For example, an IVR call reference number could be used

as a value for externalCallRef, in order to facilitate the correlation of

dialogues with their associated IVR sessions.

The Language parameter is “EnglishUnitedStates“ unless otherwise

communicated to you (as will the case if you purchase additional

phrases in other languages).

Method: POST


URL: https://<url_prefix>/StartDialogue.ashx



Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.

configuration_id The configuration identifier against

which the dialogue should be

started.


credentials.

Must not be NULL.

claimant_ids The claimant identifiers against

which the dialogue should be

started, supplied as a comma-

delimited list.

external_ref An arbitrary reference you create

that will be used to tag the dialogue

to assist you with future searching.

language An enumerated type that is only

used in passphrase mode (it is a

required parameter but it is ignored

in other modes).

Must not be NULL.



Outputs



Zero means success, otherwise an

error has occurred and the message

field will be relevant.

See StatusCode section below for

more details.

message If status_code is non-zero then this

field will indicate more precisely the

cause of the error.

dialogue_id This GUID must be stored by the

application, since it must be supplied

as a parameter to all future

operations for the current dialogue.

process_type This operation is verification-specific

and so the process_type will be

VERIFY.

prompt_hint This, if set, tells the user which

phrase should be submitted next for

the current dialogue.

Once a dialogue has been successfully created, as indicated by a

StatusCode of “0” and a valid dialogue_id, the subsequent operations

should be used to interact with it.



SubmitPhrase

See also SubmitPhraseBase64.

This operation is used to append a claimant’s utterance to an existing

dialogue.

It must be submitted using content type = “multipart/form-data” to

allow the binary parameters to be correctly uploaded.


• The dialogue ID that was returned by the call to

StartDialogue

• The phrase that the user is believed to have spoken

• The sample format that the audio data is supplied in

• The binary audio data in a supported audio file format (see

below)

The binary audio data array must contain an 8000Hz single-channel

(mono) sound sample whose attributes depend on the

SampleFormat:

Format Details

U-Law • 8-bit

A-Law • 8-bit

Linear PCM • 16-bit

• BigEndian or LittleEndian



The SampleFormat enumeration value that must be supplied has the

following members:

public enum SampleFormats

{

Unknown,

ALaw,

MuLaw,

LittleEndian,

BigEndian

}

Note that if SampleFormats.Unknown is supplied, and the associated

utterance data does not contain a RIFF header that can be

successfully parsed, an error will be returned since the phrase will be

unusable.

Method: POST

Encoding: multipart/form-data

URL: https://<url_prefix>/SubmitPhrase.ashx

Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.



dialogue_id The dialogue ID that was returned by the

call to StartDialogue.

Must not be NULL.

prompt The phrase that the user is believed to

have spoken.

See below for allowed characters.

Must not be NULL.

format The sample format that the audio data is

supplied in, as described above.

Must not be NULL.

utterance The raw binary data of the audio

recording, which should be submitted

using content type = “multipart/form-

data”.

Must not be NULL.

The prompt parameter only accepts the following values:

• 0-9

• a-z (lower-case)

• A-Z (upper-case)

• Space (“ “)

• ASCII characters C0-FF (accented alphabetic characters

taken from the ISO-8859-1 extended ASCII character set.

In practice this means that even if a passphrase (for example)

contains punctuation, that punctuation must not be passed in the

prompt parameter.



Outputs





be relevant.


details.



the error.

dialogue_status A value indicating whether the dialogue

is in progress has been successful or has

failed.

See DialogueStatus Enumeration below

for more details.

failure_reason If the dialogue was not successful then

this field provides more detail.

See FailureReason Enumeration below

for more details.

request_status This value provides the status of this

particular call to SubmitPhrase.

See RequestStatus Enumeration below

for details.

prompt_hint If the dialogue has not completed then

this value tells the user which phrase

should be submitted next.

last_sqm_decision The result of the signal quality

measurement (SQM) decision on the

previously submitted speech sample

(not the current one).

verification_decision The verification decision that has been

made for this dialogue (if applicable).

See appendix for possible values.



Note that you will only receive the WrongPhraseSubmitted value in

the request_status field when the PromptedPhrase attribute passed

in SubmitPhrase does not match the expected PromptHint as

returned to you by the previous SubmitPhrase or

GetDialogueSummary call.

For example, if you pass "6379" as the PromptedPhrase, but the

actual utterance passed is different (say “1234”), then it would be

expected that this utterance would be rejected during the server side

processing as an SQM failure ("MISSPEAK") rather than being rejected

on the client side. In other words, the client has no means of

knowing that the utterance data does not match the

PromptedPhrase – the submission therefore needs to be processed

and rejected by SQM on the server side. Note: If an utterance is so

rejected then the system simply continues requesting additional

utterances to replace it.

The following conditions control the process flow of an application:

• If dialogue_status is “Started” and request_status is “OK”

then more phrases are needed

• If dialogue_status is “Started” and request_status is

“TooManyUnprocessedPhrases” then processing is being

carried out and the application should poll

GetDialogueSummary

• If dialogue_status is “Succeeded” and process_type is

“Enrol” then the enrolment completed successfully


“Verify” then the verification attempt was accepted

• If dialogue_status is “Failed” and process_type is “Verify”

and failure_reason is “VerificationFailed” then the

verification attempt was rejected

• Any other combination of values is considered an error



SubmitPhraseBase64

See also SubmitPhrase.

This operation is exactly the same as SubmitPhrase but allows the

upload of audio to be inline in a standard “application/x-www-form-

urlencoded” body rather than as a “multipart/form-data” body. This

is to support limited environments that do not have multipart MIME

support. The disadvantage of this content type is that a Base64

encoded audio file is significantly larger than the raw audio, thus

consumes more bandwidth, and the encoding consumes more CPU

time on the client.


• The dialogue ID that was returned by the call to

StartDialogue

• The phrase that the user is believed to have spoken

• The sample format that the audio data is supplied in

• The binary audio data in a supported audio file format (see

below), Base64 encoded

The Base64 encoded binary audio data array must contain an 8000Hz

single-channel (mono) sound sample whose attributes depend on the

SampleFormat:

Format Details

U-Law • 8-bit

A-Law • 8-bit

Linear PCM • 16-bit

• BigEndian or LittleEndian



The SampleFormat enumeration value that must be supplied has the

following members:

public enum SampleFormats

{

Unknown,

ALaw,

MuLaw,

LittleEndian,

BigEndian

}

Note that if SampleFormats.Unknown is supplied, and the associated

utterance data does not contain a RIFF header that can be

successfully parsed, an error will be returned since the phrase will be

unusable.

Method: POST


URL: https://<url_prefix>/SubmitPhraseBase64.ashx

Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.

dialogue_id The dialogue ID that was returned by

the call to StartDialogue.

Must not be NULL.



prompt The phrase that the user is believed to

have spoken.

See below for allowed characters.

Must not be NULL.

format The sample format that the audio data

is supplied in, as described above.

Must not be NULL.

utterance The Base64 encoded binary data of the

audio recording.

Must not be NULL.

The prompt parameter only accepts the following values:

• 0-9

• a-z (lower-case)

• A-Z (upper-case)

• Space (“ “)

• ASCII characters C0-FF (accented alphabetic characters

taken from the ISO-8859-1 extended ASCII character set.

In practice this means that even if a passphrase (for example)

contains punctuation, that punctuation must not be passed in the

prompt parameter.



Outputs





be relevant.


details.



the error.

dialogue_status A value indicating whether the dialogue

is in progress has been successful or has

failed.


for more details.



See FailureReason Enumeration below

for more details.




for details.






previously submitted speech sample (not

the current one).



Note that you will only receive the WrongPhraseSubmitted value in

the request_status field when the PromptedPhrase attribute passed

in SubmitPhraseBase64 does not match the expected PromptHint as

returned to you by the previous SubmitPhraseBase64 or

GetDialogueSummary call.

For example, if you pass "At VoiceVault, I am verified as I speak" as

the PromptedPhrase, but the actual utterance passed is different (say

“VoiceVault knows me by the sound of my voice”), then it would be

expected that this utterance would be rejected during the server side

processing as an SQM failure ("MISSPEAK") rather than being rejected

on the client side. In other words, the client has no means of

knowing that the utterance data does not match the

PromptedPhrase – the submission therefore needs to be processed

and rejected by SQM on the server side. Note: If an utterance is so

rejected then the system simply continues requesting additional

utterances to replace it.







GetDialogueSummary











GetDialogueSummary

This operation is used to retrieve the status of the current dialogue

without the need to submit a phrase.

This operation is typically used when the call to SubmitPhrase returns

a request_status value of TooManyUnprocessedPhrases.

In this scenario, it is impossible for the application to submit further

phrases until the server has processed the pipeline, in which case the

application must repeatedly call GetDialogueSummary until a valid

status is received.

Method: GET


URL: https://<url_prefix>/GetDialogueSummary.ashx

Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.

dialogue_id The dialogue ID that was returned by

the call to StartDialogue.

Must not be NULL.



Outputs




has occurred and the message field will be

relevant.


details.



the error.

dialogue_status A value indicating whether the dialogue is

in progress has been successful or has

failed.


for more details.



See FailureReason Enumeration below for

more details.



See RequestStatus Enumeration below for

details.






previously submitted speech sample (not

the current one).



verification_decision The verification decision that has been

made for this dialogue (if applicable).

See Appendix for possible values.







GetDialogueSummary











AbortDialogue

This method should be used when the caller hangs up prematurely,

or a dialogue needs to be terminated early for any reason.

It will abort the dialogue and all associated unprocessed exchanges.

This is especially important for enrolment dialogues, as only one

enrolment dialogue may be active at a time.

Method: POST


URL: https://<url_prefix>/AbortDialogue.ashx

Parameters





credentials.

Must not be NULL.




credentials.

Must not be NULL.

dialogue_id The dialogue ID that was used in the call

to SubmitPhrase.

Must not be NULL.



Outputs





be relevant.


details.



the error.


particular call to AbortDialogue.


for details.



AdaptClaimant

This operation can be used to introduce new verification audio

material into a claimant’s enrollment model.

The material introduced must have been previously determined to be

suitable for adaptation. For example, a verification dialogue that is

either a strong “Accept” or “Reject” will usually not be suitable – the

former because the model would not benefit from the material, and

the latter because there is significant doubt over the identity of the

speaker.

Method: POST


URL: https:// <url_prefix>/AdaptClaiamant.ashx

Parameters


username VIGO_CREDENTIAL_ID

The username of the service account



credentials.

Must not be NULL.

password VIGO_CREDENTIAL_PWD

The password of the service account



credentials.

Must not be NULL.

claimant_id The claimant for whom the adaptation

will take place.

Must not be NULL.



dialogue_id The verification dialogue from which the

adaptation audio material will be taken.

If the dialogue consists of more than one

phrase, the phrase that is most suitable

for adaptation will be selected.

Must not relate to an enrollment

dialogue.

Must not be NULL.

Outputs





be relevant.


details.



the error.



DeleteClaimant

This operation can be used to ensure that all biometric information

stored in VoiceVault databases is removed for a particular claimant.

This includes any enrolled voice models, any replay detection

metadata, and all speech that has been submitted in dialogues

pertaining to the specified claimant identifier.

Note: If the claimant to be deleted has been a participant in any

“1:few” mode dialogues, biometric information for those dialogues

will be removed. Since these dialogues are effectively “shared”, this

means that data will be removed for all other participants in those

dialogues. This method should therefore be used with extreme

caution in that use-case.

Please refer to Biometric Operations above, and specifically the

StartDialogueOneToFew method, for more details on the “1:few”

use-case.

Method: POST


URL: https:// <url_prefix>/DeleteClaiamant.ashx

Parameters


username VIGO_CREDENTIAL_ID

The username of the service account



credentials.

Must not be NULL.

password VIGO_CREDENTIAL_PWD

The password of the service account



credentials.



Must not be NULL.

claimant_id The claimant for whom the biometric

record will be removed.

Must not be NULL.

Outputs





be relevant.


details.



the error.



RequestStatus Enumeration The RequestStatus enumeration is returned for all request_status XML fields and has the

following members:

Member Summary

0 OK The request completed successfully

1 DialogueDoesNotExist Caller supplied an invalid dialogue ID

2 ExchangeDoesNotExist Reserved for internal use

3 ClaimantDoesNotExist Caller supplied an invalid claimant ID

4 ConfigurationDoesNotExist Caller supplied an invalid

configuration ID

5 RequestProcessingError Reserved for internal use

6 GeneralSystemError A system error occurred and has

been logged

7 NoSample Reserved for internal use

8 InvalidProcessTypeRequest Reserved for internal use

9 DuplicatePhrase Reserved for internal use

10 TooManyUnprocessedPhrases The server is busy processing

previous phrases, so the current

request should be retried later

11 WrongPhraseSubmitted

Caller supplied a phrase that did not

match the expected prompt

12 ClaimantIsNotEnabled Claimant is currently disabled

13 NoSpecifiedClaimantRegistered None of the claimants specified are

registered

14 NoSpecifiedClaimantEnrolled None of the specified claimants are

enrolled



15 NoActiveSettings No active settings for the specified

configuration

16 DialogueAlreadyInProgress Dialogue is already in progress for

the specified claimant

17 AutoReEnrolment Reserved for internal use

18 ConfigurationIsNotEnabled The specified configuration is not

enabled

19 SampleFormatMismatch There is a mismatch between the

audio format that was specified to

that which was submitted.

20 SampleFormatUnsupported The audio file was specified but does

not contain enough information to

help determine what the format

actually is.

For example, “Wave” could be

specified and valid PCM audio files

are submitted but without RIFF

headers, so that we are unable to

determine whether the file is big-

endian or little-endian.



DialogueStatus Enumeration The following enumerations are returned from calls to SubmitPhrase and

GetDialogueSummary and are used to determine what operation should be called next in

the process flow. The DialogueStatus enumeration is returned for all dialogue_status XML

fields and has the following members:

Member Summary

0 Started The dialogue is still in progress

1 Succeeded The dialogue has successfully completed and, for verification

dialogues, the claimant has been successfully verified

2 Failed The dialogue has failed. This could be due, for example, to a

rejected verification attempt, or a recording being detected

– see the FailureReason for further details

3 Error An error has caused the dialogue to terminate and has been

logged

4 Aborted The dialogue has been purposely terminated prematurely.

This could be, for example, if a caller has hung up the phone.

5 Abandoned A dialogue is set to this status when it has been “Started”

for a configurable period of time, without any activity, and is

deemed to be no longer in use.



FailureReason Enumeration The FailureReason enumeration is returned for all failure_reason XML fields and has the

following members (the default being NotSet):

Member Summary

NotSet The dialogue was successful or is not

complete

MaxTotalSqmFailuresExceeded The threshold for the total number of

permissible SQM errors within a dialogue

has been exceeded

MaxPhraseSqmFailuresExceeded The threshold for SQM errors on a single

phrase has been exceeded

MaxTotalSystemErrorsExceeded The threshold for the total number of

permissible system errors within a dialogue

has been exceeded

VerificationFailed Indicates that a verification dialogue has

been rejected

RecordingDetected The threshold to determine whether a

submitted utterance within this dialogue is a

recording of a previous one has been

exceeded

PassphraseInvalid The phrase text contains words that are not

in the language lexicon.

In preactice this means that the words must

be added to the language lexicon before the

phrase can be used.



StatusCode Enumeration The StatusCode enumeration is returned for all Fusion API XML fields and has the following

members:

Member Summary

NoError The method call completed successfully and all documented

outputs will be present in the XML response.

UnknownError A non-recoverable server error occurred. Further details will

be included in the message field.

InvalidParameter The method was called with one or more invalid

parameters.

The first parameter that failed validation will be returned in

the message field.

SoapFault An error occurred delegating on to the underlying and richer

VoiceVault Fusion SOAP API.

This error could be server side, or it could be the result of

inputs supplied by the caller. The message field will provide

more detail.

RequestStatusError The RequestStatus enumeration resulted in a terminal (for

the current dialogue) error.

The message field will indicate which RequestStatus value

was returned.

See RequestStatus Enumeration for more details.

For all status codes other than zero the XML response will include a “message” field that

gives additional human readable information about the error.



SQMDecision Enumeration The following enumerations are returned from calls to SubmitPhrase and

GetDialogueSummary and are used to determine the signal quality measurement (SQM) for

the previously submitted phrase (NOT the one that has just been submitted).

Value Member Summary

0 NotSet Speech sample has not undergone SQM

processing (possibly due to an error).

1 OK Speech sample has passed the speech quality

measaurement test/

2 Quiet Speech is too quiet or no speech is heard.

Could result from there being not enough

signal to detect the prompted for words.

3 Misspeak The spoken phrase does not contain the words

that were prompted for.

4 Noisy The signal to noise ratio is too low. The

spoken words are indistinguishable over other,

background, noise.

5 BeginCutoff Data is missing from the start of the submitted

speech sample. Could result from the speaker

beginning to say the required phrase before

the application recording process has started.

6 EndCutoff Data is missing from the end of the submitted

speech sample. Could be because the speaker

is not ebign given enough time to respond to

the prompt.

7 Short The words in the speech sample are too close

together – likely because the speaker spoke

too fast.



8 Isolated The words in the speech sample are too far

apart together – likely because the speaker

spoke too slowly and the words were not

spoken so as to be a sinlge phrase.

9 Recording The speech sample has been detected as being

identical to a previously submitted sample.

10 Alignment Failure There is a high chance that the speech sample

is a recording of a previously submitted

sample, but the associated dialogue will be

allowed to continue.

11 Passphrase Too Short The passphrase contains less than the

minimum required number of phonemes.

This message comes form the speech recognizer and is returned whenever there is an issue with the phrase (wrong words spoken; phrase cutoff; user not speaking clearly; not enough phonemes could be extracted; etc.).

If appropriate, the user could be prompted to

repeat the phrase.



VerificationDecision Enumeration

Member Summary

NotApplicable This is not a verification dialogue

NotSet This is a verification dialogue that

is still in progress, and no audio

material has yet been processed

by the verification engine

Uncertain The dialogue is in progress, at

least one phrase has been

processed by the verification

engine, but more audio material is

required in order to make a final

verification decision

Accept The dialogue is complete and

verification was successful with a

high confidence level

Reject The dialogue is complete and

verification was unsuccessful with

a high confidence level

StrongAccept The dialogue is complete and

verification was successful with an

extremely high confidence level

StrongReject The dialogue is complete and

verification was unsuccessful with

an extremely high confidence level



Language Enumeration The Language enumeration is required for calls to StartDialogue and has the following

members:

Member

Afrikaans

Albanian

ArabicAlgeria

ArabicBahrain

ArabicEgypt

ArabicIraq

ArabicJordan

ArabicKuwait

ArabicLebanon

ArabicLibya

ArabicMorocco

ArabicOman

ArabicQatar

ArabicSaudiArabia

ArabicSyria

ArabicTunisia

ArabicUnitedArabEmirates

ArabicYemen

Armenian

AzeriCyrillic

AzeriLatin

Basque

Belarusian

Bulgarian

Catalan

Chinese

ChineseHongKong

ChineseMacau

ChineseSingapore

ChineseTaiwan

ChineseSimplified

ChineseTraditional



Croatian

Czech

Danish

Dhivehi

DutchBelgium

DutchTheNetherlands

EnglishAustralia

EnglishBelize

EnglishCanada

EnglishCaribbean

EnglishIreland

EnglishJamaica

EnglishNewZealand

EnglishPhilippines

EnglishSouthAfrica

EnglishTrinidadandTobago

EnglishUnitedKingdom

EnglishUnitedStates

EnglishZimbabwe

Estonian

Faroese

FarsiIran

Finnish

FrenchBelgium

FrenchCanada

FrenchFrance

FrenchLuxembourg

FrenchMonaco

FrenchSwitzerland

Galician

Georgian

GermanAustria

GermanGermany

GermanLiechtenstein

GermanLuxembourg

GermanSwitzerland

Greek

Gujarati

Hebrew



Hindi

Hungarian

Icelandic

Indonesian

ItalianItaly

ItalianSwitzerland

Japanese

Kannada

Kazakh

Konkani

Korean

Kyrgyz

Latvian

Lithuanian

Macedonian

MalayBrunei

MalayMalaysia

Marathi

Mongolian

NorwegianBokmal

NorwegianNynorsk

Polish

PortugueseBrazil

PortuguesePortugal

Punjabi

Romanian

Russian

Sanskrit

SerbianCyrillic

SerbianLatin

Slovak

Slovenian

SpanishArgentina

SpanishBolivia

SpanishChile

SpanishColombia

SpanishCostaRica

SpanishDominicanRepublic

SpanishEcuador



SpanishElSalvador

SpanishGuatemala

SpanishHonduras

SpanishMexico

SpanishNicaragua

SpanishPanama

SpanishParaguay

SpanishPeru

SpanishPuertoRico

SpanishSpain

SpanishUruguay

SpanishVenezuela

Swahili

SwedishFinland

SwedishSweden

Syriac

Tamil

Tatar

Telugu

Thai

Turkish

Ukrainian

Urdu

UzbekCyrillic

UzbekLatin

Vietnamese

voicevault fusion api user guide · fusion api user guide company confidential page 6 of 60...

Documents