Voice Biometrics Users

This describes the web services that support verification of a user's identity by analysing their voice.

A user must first register in the system, at the same time supplying initial audio data of their voice. This constructs a voice model for the user, which should be updated to refine the model. Then, at regular intervals, the model can be updated to cater for natural aging, changes in environment etc.

For example:

Response

$ curl --user 1-2-0/bob@example.com:ak-378b7602-5a91-47f8-9f6f-ef4bf3e234e9 https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/register?user_id=Bob&filename=bobsaudio1.wav

Audio data format

The audio data supplied to register, update and verify can be up to 60 seconds long and must be in mono WAV format with a
minimum sample rate of 8 kHz. Supported formats are 16 bit PCM, a-law and mu-law.

Streaming data on a websocket

When training, updating or verifying a user, calling GET returns a url to a websocket which accepts streamed audio data and returns different responses to POST and PUT. In this initial release the audio data needs to be of known length (e.g. a file). Subsequent releases will provide additional stream types including a means of streaming in real time.

When the websocket API encounters an error it returns a reject event and one of the errors listed here:

Parameter	Value	Description
`50`	Bad request
`51`	One of the following: Audio file contains no data Audio is in an unknown format Audio is not mono (must be single-channel) Audio sample rate is too low (below 8 kHz) Audio bit depth is too low (less than 16 and not A-Law or mu-Law) Audio duration is too long (more than 60 seconds)
`52`	Audio does not contain sufficient speech
`60`	A Voice Biometric server exception has occurred
`61`	Service temporarily disabled for this key or account

Text dependent mode

By default, verification runs in text dependent mode. In this mode the same phrase must be used to register, update and verify and the voice biometric engine makes use of this to improve the reliability of the user's model. If different phrases are likely to be supplied to update and verify then text dependent mode should be disabled when calling verify.

Date formats

All dates are of the format YYYY-MM-DD_hh:mm:ss and are in Coordinated Universal Time (UTC).

Response content

All web services in this API return response content of type "application/json".

Charging information

The cost of each call to register or verify can be obtained using the application_status web service, passing it the application_instance_id returned. Cost information will not be available immediately. The costs_valid field will indicate when it is available.

Note

This is a low level API. For information on higher level APIs see the Web Services Language Wrappers

Authorisation

This API employs basic authentication, using your cloud account username, but unlike other web service APIs, requires a suitable Voice Biometric User Group Key rather than your account's API Access Key.


Username	: cloudID/username (e.g. 1-2-0/bob@example.com)
Password	: Voice Biometric User Group Key

Register

You need to supply your account username and a user group key in the basic authorisation string.

This registers a user as part of a user group and creates an initial voice model for that user from the supplied audio data.

The quality of the voice model is dependent on the supplied audio. It must be a good representation of the user's normal voice. It is recommended that at least ten seconds of audio is provided and that once registered, a user's voice model is successfully verified and updated at least twice.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/register
Methods	: PUT, POST, GET

Request using PUT

Parameter	Value	Description
user_id	required	a user-defined Id that uniquely identifies the user. Characters a-z, A-Z, 0-9, "." and "-" can all be used.

When calling register using PUT, you supply a single wav file in the request body.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	always

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/register?user_id=Bob

Sucess Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949"
}

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' is already present", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#register",
        "datetime": "2021-01-15_08:56:24"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/register",
        "datetime": "2021-01-15_08:56:23"
    }
}

Note

The code returned may be an HTTP error code (prefixed by "HTTP") or an underlying Voice Biometrics engine error that has no prefix. For these non-HTTP errors, see the text for a description of the error.

Request using POST

Parameter	Value	Description
user_id	required	a user-defined Id that uniquely identifies the user. Characters a-z, A-Z, 0-9, "." and "-" can all be used.
wav_file_url	optional	a url for a wav file to download. It can be repeated in the query string to add additional file urls. Omit if supplying wav file(s) in the request body.

When calling register using POST, you supply one or more wav files in the request body as multipart/form-data or one or more urls that each point to a wav file to download. Multiple files can be different formats.

When supplying wav files as multipart form-data, the part Name must be Source1, Source2, ... and each part Filename should be the name of the file without path.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	always
sources	array of objects	always

Each source object contains:

Parameter	Value	Description
source	string	always
accepted	bool	always

Example 1

Request (audio file(s) in the request body)

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/register?user_id=Bob

1st part: Name: "Source1", Filename: "Bob1.wav"
2nd part: Name: "Source2", Filename: "Bob2.wav"

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949", 
    "sources": [
        {
            "source": "Source1",
            "accepted": true
        },
        {
            "source": "Source2",
            "accepted": true
        },
    ]
}

Example 2

Request (audio file urls in the query string)

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/register?user_id=Bob&wav_file_url=my.wav.files.com%2Fget_wav%3Ffilename%3Dbob123.wav&wav_file_url=my.wav.files.com%2Fget_wav%3Ffilename%3Dbob456.wav

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949", 
    "sources": [
        {
            "source": "my.wav.files.com/get_wav?filename=bob123.wav",
            "accepted": true
        },
        {
            "source": "my.wav.files.com/get_wav?filename=bob456.wav",
            "accepted": true
        },
    ]
}

Example 3

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' is already present", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#register",
        "datetime": "2021-01-15_08:56:24"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/register",
        "datetime": "2021-01-15_08:56:23"
    }}

Note

The code returned may be an HTTP error code (prefixed by "HTTP") or an underlying Voice Biometrics engine error that has no prefix. For these non-HTTP errors, see the text for a description of the error.

Request using GET

Parameter	Value	Description
user_id	required	a user-defined Id that uniquely identifies the user. Characters a-z, A-Z, 0-9, "." and "-" can all be used.
stream_type *	optional	file
format *	optional	16bit_PCM
sample_rate *	optional	8000

* format and sample_rate properties are present for realtime streaming when it becomes available, but are ignored when stream_type is file. In this case the audio format and sample rate are obtained from the header of the supplied wav file data.

Calling register using GET will return a url on which a websocket can be opened and the audio data streamed.

Response

Parameter	Value	Description
application_instance_id	string	always
url	string	always

You open a websocket on the returned url and send your audio data followed by a JSON message containing the following parameters:

Parameter	Value	Description
event	required	Must be "audio_sent"

You will receive a JSON response containing the following:

Parameter	Value	Description
event	string	always
transaction_id	string	only if event is "register"
user_id	string	only if event is "register"
reason	string	only if event is "reject"
message	string	only if event is "reject"
code	integer	only if event is "reject"

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/register?user_id=Bob

Response

{   
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "url": "wss://voisentry-2.aculabcloud.net/wss/register?auth_token=PFCoTsxSHqxqYz_P1XMSXKz1pDJPHBWMWQNJhbmoL..."
}

Open a websocket on this url and send the audio data.

Send message

{
    "event": "audio_sent"
}

Response

{
    "event": "register",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027"
}

Error Response

{
    "event": "reject", 
    "reason": "Bad Request",
    "message": "Bad API request, register: user_id Bob is already present.",
    "code": 50
}

Update

You need to supply your account username and a user group key in the basic authorisation string.

This updates a user's voice model that has been created by calling register. It should only be called with audio data that is guaranteed (confirmed by other means) to be authentic user voice data.

The quality of the voice model is dependent on the supplied audio. It must be a good representation of the user's normal voice. It is recommended that at least ten seconds of audio is provided. A user's voice model can continue to be updated at regular intervals and when there are changes in environment etc.

You can supply a single wav using PUT, or multiple wav files using POST. Alternatively you can stream the user's audio data on a websocket opened on the url returned by GET.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/update
Methods	: PUT, POST, GET

Request using PUT

Parameter	Value	Description
user_id	required	the user Id for the user that has already been registered..

When calling update using PUT, you supply a single wav file in the request body.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	always

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/update?user_id=Bob

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949"
}

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' not found", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#update",
        "datetime": "2021-01-15_09:24:16"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/update",
        "datetime": "2021-01-15_09:24:16"
    }
}

Note

The code returned may be an HTTP error code (prefixed by "HTTP") or an underlying Voice Biometrics engine error that has no prefix. For these non-HTTP errors, see the text for a description of the error.

Request using POST

Parameter	Value	Description
user_id	required	the user Id for the user that has already been registered..
wav_file_url	optional	a url for a wav file to download. It can be repeated in the query string to add additional file urls. Omit if supplying wav file(s) in the request body.

When calling update using POST, you supply one or more wav files in the request body as multipart/form-data or one or more urls that each point to a wav file to download. Multiple files can be different formats.

When supplying wav files as multipart form-data, the part Name must be Source1, Source2, ... and each part Filename should be the name of the file without path.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	always
sources	array of objects	always

Each source object contains:

Parameter	Value	Description
source	string	always
accepted	bool	always

Example 1

Request (audio filename(s) in the request body)

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/update?user_id=Bob

1st part: Name: "Source1", Filename: "Bob1.wav"
2nd part: Name: "Source2", Filename: "Bob2.wav"

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949", 
    "sources": [
        {
            "source": "Source1",
            "accepted": true
        },
        {
            "source": "Source2",
            "accepted": true
        },
    ]
}

Example 2

Request (audio file urls in the query string)

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/update?user_id=Bob&wav_file_url=my.wav.files.com%2Fget_wav%3Ffilename%3Dbob123.wav&wav_file_url=my.wav.files.com%2Fget_wav%3Ffilename%3Dbob456.wav

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "57c3c968570f11eb854a02e848f54949", 
    "sources": [
        {
            "source": "my.wav.files.com/get_wav?filename=bob123.wav",
            "accepted": true
        },
        {
            "source": "my.wav.files.com/get_wav?filename=bob456.wav",
            "accepted": true
        },
    ]
}

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' not found", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#update",
        "datetime": "2021-01-15_09:24:16"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/update",
        "datetime": "2021-01-15_09:24:16"
    }
}

Note

The code returned may be an HTTP error code (prefixed by "HTTP") or an underlying Voice Biometrics engine error that has no prefix. For these non-HTTP errors, see the text for a description of the error.

Request using GET

Parameter	Value	Description
user_id	required	the user Id for the user that has already been registered..
stream_type *	optional	file
format *	optional	16bit_PCM
sample_rate *	optional	8000

format and sample_rate properties are present for realtime streaming when it becomes available, but are ignored when stream_type is file. In this case the audio format and sample rate are obtained from the header of the supplied wav file data.

Calling update using GET will return a url on which a websocket can be opened and the audio data streamed.

Response

Parameter	Value	Description
application_instance_id	string	always
url	string	always

You open a websocket on the returned url and send your audio data followed by a JSON message containing the following parameters:

Parameter	Value	Description
event	required	Must be "audio_sent"

You will receive a JSON response containing the following:

Parameter	Value	Description
event	string	always
transaction_id	string	only if event is "update"
user_id	string	only if event is "update"
reason	string	only if event is "reject"
message	string	only if event is "reject"
code	integer	only if event is "reject"

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/update?user_id=Bob

Response

{   
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "url": "wss://voisentry-2.aculabcloud.net/wss/update?auth_token=PFCoTsxSHqxqYz_P1XMSXKz1pDJPHBWMWQNJhbmoL..."
}

Open a websocket on the returned url and send the audio data.

Send message

{
    "event": "audio_sent"
}

Response

{
    "event": "update",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027"
}

Error Response

{
    "event": "reject", 
    "reason": "Bad Request",
    "message": "Bad API request, update: user_id Bob not found.",
    "code": 50
}

Verify

You need to supply your account username and a user group key in the basic authorisation string.

This verifies that the supplied audio matches the specified registered user.

The audio data is analysed against the specified user's voice model and this produces a confidence value that the user has been matched. A value of greater than 1.0 indicates a match.

You can enable Presentation Attack Detection (PAD, also known as spoof detection) for each verification. This tries to detect synthesized audio or audio that has been clandestinely recorded and replayed. It also detects audio that has been used previously.

You can supply a single wav file using PUT. For POST in text dependent mode you can supply only a single wav file or, if text dependent is false, you can provide multiple files. Alternatively you can stream the user's audio data on a websocket opened on the url returned by GET.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/verify
Methods	: PUT, POST, GET

Request using PUT

Parameter	Value	Description
user_id	required	a user-defined Id of the user to be verified.
sensitivity	optional	0.0
text_dependent	optional	true
enable_pad	optional	false

When calling verify using PUT, you supply a single wav file in the request body.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	if verification occurs without error
verified	bool	if verification occurs without error
confidence	float	if verification occurs without error
pad_detected	a PADDetected object	if verification occurs without error and a Presentation Attack was detected.

Where the PADDetected object contains the following:

Parameter	Value	Description
type	string	always

Note

The algorithm that calculates the confidence adapts as the speaker’s model is updated and the scaling of the returned confidence value may vary. Consequently different confidence values cannot be reliably compared (e.g. today's score of 1.21 for a user is not necessarily better than yesterday's score of 1.20).

A user may often be verified with a confidence score that is just above 1.0. This is normal and should not be considered a weak result. If it becomes apparent that the error rates are insufficient for the application, the sensitivity value can be altered to make it more or less sensitive. Setting a positive sensitivity, 1.0 for example, will reduce the likelyhood that an impostor may pass. Setting a negative sensitivity, -1.0 for example, will reduce the likelyhood that a real speaker may fail verification.

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/verify?user_id=Bob

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25
}

If the verification is carried out, but a Presentation Attack is detected you will receive the example JSON:

Response

{
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25,
    "pad_detected": {
        "type": "TypeA"
    }
}

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' not found", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#verify",
        "datetime": "2021-01-15_09:29:36"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/verify",
        "datetime": "2021-01-15_09:29:36"
    }

Request using POST

Parameter	Value	Description
user_id	required	a user-defined Id of the user to be verified.
wav_file_url	optional	a url for a wav file to download. When text_dependent is true, only one url is supported. When text_dependent is false, you can provide additional urls in the query string to specify multiple audio sources. Omit if supplying wav file(s) in the request body.
sensitivity	optional	0.0
text_dependent	optional	true
enable_pad	optional	false

When calling verify using POST with text_dependent enabled, you supply a wav file in the request body as multipart/form-data or a url that points to a wav file to download.

When calling verify using POST with text_dependent disabled, you supply one or more wav files in the request body as multipart/form-data or one or more urls that each point to a wav file to download. Multiple files can be different formats.

When supplying wav files as multipart form-data, the part Name must be Source1, Source2, ... and each part Filename should be the name of the file without path.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
application_instance_id	string	always
transaction_id	string	if verification occurs without error
verified	bool	if verification occurs without error
confidence	float	if verification occurs without error
sources	array of objects	only if text_dependent is False
pad_detected	a PADDetected object	if verification occurs without error and a Presentation Attack was detected.

Each source object contains:

Parameter	Value	Description
source	string	always
accepted	bool	always

Where the PADDetected object contains the following:

Parameter	Value	Description
type	string	always

Note

The algorithm that calculates the confidence adapts as the speaker’s model is updated and the scaling of the returned confidence value may vary. Consequently different confidence values cannot be reliably compared (e.g. today's score of 1.21 for a user is not necessarily better than yesterday's score of 1.20).

A user may often be verified with a confidence score that is just above 1.0. This is normal and should not be considered a weak result. If it becomes apparent that the error rates are insufficient for the application, the sensitivity value can be altered to make it more or less sensitive. Setting a positive sensitivity, 1.0 for example, will reduce the likelyhood that an impostor may pass. Setting a negative sensitivity, -1.0 for example, will reduce the likelyhood that a real speaker may fail verification.

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/verify?user_id=Bob&wav_file_url=my.wav.files.com%2Fget_wav%3Ffilename%3Dbob123.wav

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25
}

If the verification is carried out, but a Presentation Attack is detected you will receive the example JSON:

Response

{
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25,
    "pad_detected": {
        "type": "TypeA"
    }
}

Error Response

{
    "error": {
        "code": HTTP 400,
        "text": "Bad Request: user_id 'Bob' not found", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#verify",
        "datetime": "2021-01-15_09:29:36"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/verify",
        "datetime": "2021-01-15_09:29:36"
    }
}

Request using GET

Parameter	Value	Description
user_id	required	a user-defined Id of the user to be verified.
sensitivity	optional	0.0
text_dependent	optional	true
enable_pad	optional	false
stream_type *	optional	file
format *	optional	16bit_PCM
sample_rate *	optional	8000

format and sample_rate properties are present for realtime streaming when it becomes available, but are ignored when stream_type is file. In this case the audio format and sample rate are obtained from the header of the supplied wav file data.

Calling verify using GET will return a url on which a websocket can be opened and the audio data streamed.

Response

Parameter	Value	Description
application_instance_id	string	always
url	string	always

You open a websocket on the returned url and send your audio data followed by a JSON message containing the following parameters:

Parameter	Value	Description
event	required	Must be "audio_sent"

You will receive a JSON response containing the following:

Parameter	Value	Description
event	string	always
transaction_id	string	only if event is "verify"
user_id	string	only if event is "verify"
verified	bool	only if event is "verify"
confidence	float	only if event is "verify"
pad_detected	a PADDetected object	only if event is "verify" and a Presentation Attack was detected.
reason	string	only if event is "reject"
message	string	only if event is "reject"
code	integer	only if event is "reject"

Where the PADDetected object contains the following:

Parameter	Value	Description
type	string	always

Note

The algorithm that calculates the confidence adapts as the speaker’s model is updated and the scaling of the returned confidence value may vary. Consequently different confidence values cannot be reliably compared (e.g. today's score of 1.21 for a user is not necessarily better than yesterday's score of 1.20).

A user may often be verified with a confidence score that is just above 1.0. This is normal and should not be considered a weak result. If it becomes apparent that the error rates are insufficient for the application, the sensitivity value can be altered to make it more or less sensitive. Setting a positive sensitivity, 1.0 for example, will reduce the likelyhood that an impostor may pass. Setting a negative sensitivity, -1.0 for example, will reduce the likelyhood that a real speaker may fail verification.

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/verify?user_id=Bob

Response

{   
    "application_instance_id": "vb-2236d625010060f83617.000001",
    "url": "wss://voisentry-2.aculabcloud.net/wss/verify?auth_token=PFCoTsxSHqxqYz_P1XMSXKz1pDJPHBWMWQNJhbmoL..."
}

Open a websocket on the returned url and send the audio data.

Then send the message:

{
    "event": "audio_sent"
}

If the verification is carried out successfully you will receive the example JSON:

Response

{
    "event": "verify",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25
}

If the verification is carried out, but a Presentation Attack is detected you will receive the example JSON response:

Response

{
    "event": "verify",
    "transaction_id": "e1352c5a44fe11eb91ba021ae2cff027",
    "verified": true,
    "confidence": 1.25,
    "pad_detected": {
        "type": "TypeA"
    }
}

Erorr Response

{
    "event": "reject", 
    "reason": "Bad Request",
    "message": "Bad API request, update: user_id Bob not found.",
    "code": 50
}

Stats

This obtains statistics relating to a specified registered user.

You need to supply your account username and a user group key in the basic authorisation string.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/stats
Methods	: GET, POST

Parameter	Value	Description
user_id	required	the Id of the user.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
user_group_name	string	always
transaction_id	string	always
registration_date	string	always
update_date	string	always
verification_date	string	always
verification_attempts	integer	always
verifications_passed	integer	always
verifications_failed	integer	always

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/stats?user_id=Bob

Response

{
    "user_group_name": "BobsCompany", 
    "transaction_id": "c2ae5d2455ac11ebbdef02e848f54949", 
    "registration_date": "2021-01-13_14:30:33", 
    "update_date": "2021-01-13_14:31:28", 
    "verification_date": "2021-01-13_14:34:24", 
    "verification_attempts": 1, 
    "verifications_passed": 1, 
    "verifications_failed": 0
}

Error Response

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user Id Bill is not a registered user.", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#stats",
        "datetime": "2021-01-15_08:56:24"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/stats",
        "datetime": "2021-01-15_08:56:23"
    }
}

Exists

This determines whether a specified user is currently registered.

You need to supply your account username and a user group key in the basic authorisation string.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/exists
Methods	: GET, POST

Parameter	Value	Description
user_id	required	the Id of the user.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
user_id	string	always
transaction_id	string	always
exists	bool	always

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/exists?user_id=Bob

Response

{
    "user_id": "Bob", 
    "transaction_id": "c2ae5d2455ac11ebbdef02e848f54949", 
    "exists": true 
}

Error Response

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user Id Bill is not a registered user.", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#exists",
        "datetime": "2021-01-15_08:57:18"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/exists",
        "datetime": "2021-01-15_08:57:17"
    }
}

Delete

This deletes a specified registered user and removes any trained audio voice model data.

You need to supply your account username and a user group key in the basic authorisation string.

Request


URL	: https://ws-[cloudID].aculabcloud.net/voice_biometrics/v1/user/delete
Methods	: GET, POST

Parameter	Value	Description
user_id	required	the Id of the user.

Response

A JSON object containing the following parameters:

Parameter	Value	Description
user_id	string	always
transaction_id	string	always
deleted	string	always

Example

Request

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user/delete?user_id=Bob

Response

{
    "user_id": "Bob, 
    "transaction_id": "c2ae5d2455ac11ebbdef02e848f54949", 
    "deleted": "2021-01-13_14:30:33"
}

Error Response

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user Id Bill is not a registered user.", 
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_voice_biometrics_users/#delete",
        "datetime": "2021-01-15_08:57:46"
    },
    "request": {
        "url": "/voice_biometrics/v1/user/delete",
        "datetime": "2021-01-15_08:57:45"
    }
}