Voiceprint management

This section contains voiceprint management proto files.

voiceprints_management_service.proto

VoiceprintsManager

This service allows managing voiceprint profiles. Methods are typically used in self-service applications such as active authentication via the IVR.

gRPC method definitions

gRPC method definitions
Method Name Request Type Response Type Description
CreateVoiceprintProfile CreateVoiceprintProfile
Request		 CreateVoiceprintProfile
Response		 Creates a new voiceprint profile. Accepts a message with the print owner and a tag used to distinguish between multiple prints that belong to the same owner. Returns a unique ID for the newly created voiceprint profile.
GetGkVoiceprintProfileId GetGkVoiceprintProfileId
Request		 GetGkVoiceprintProfileId
Response		 Returns a voiceprint profile ID that belongs to the specified owner, identified by a tag. The voiceprint profile ID can be used for all other voiceprint operations.
GetVoiceprintProfileDetails GetVoiceprintProfileDetails
Request		 GetVoiceprintProfileDetails
Response		 Returns details for a specific voiceprint profile that can be specified either using a voiceprint profile ID or using an owner and a tag. The results include both read-only and writable attributes. Use fieldmask to select only a subset of the results.
UpdateVoiceprintProfileDetails UpdateVoiceprintProfileDetails
Request		 UpdateVoiceprintProfileDetails
Response		 Update any of the voiceprint profile’s writable attributes. The input is a voiceprint profile (that can be specified either using a voiceprint profile ID or an owner and a tag) and the list of writable attributes that are set.
ExecuteVoiceprintProfilesStatusJob ExecuteVoiceprintProfilesStatusJob
Request		 ExecuteVoiceprintProfilesStatusJob
Response		 Executes a voiceprint profiles status job and returns a unique job ID that can later be used to monitor the progress and status of the job. The job output data provided in a ZIP file includes one or more CSV files, each containing up to 1 million records. Indicatively the time to generate a ZIP file for 1 million prints takes approximately 2-5 minutes.
GetVoiceprintProfilesStatusJobDetails GetVoiceprintProfilesStatusJobDetails
Request		 GetVoiceprintProfilesStatusJobDetails
Response		 Returns details for a specific voiceprint profiles status job.
LockVoiceprintProfile LockVoiceprintProfile
Request		 LockVoiceprintProfile
Response		 Locks a voiceprint profile, preventing it from being used for authentication. It can be used on an account that is under attack in order to prevent it from being used, or to limit the usage of a low-quality print. The main input is a voiceprint profile ID. Optionally, you can provide more context information about the locking reason. It can be called for a locked print to update the locking reason.
UnlockVoiceprintProfile UnlockVoiceprintProfile
Request		 UnlockVoiceprintProfile
Response		 Unlocks a locked voiceprint profile, allowing access to the biometrics system so that it can be used again for authentication. The input is a voiceprint profile ID.
DeleteVoiceprintTemplate DeleteVoiceprintTemplate
Request		 DeleteVoiceprintTemplate
Response		 Deletes the voiceprint profile template created by Train. It can be used to delete the template if it is created using a wrong calibration model.
DeleteVoiceprintProfile DeleteVoiceprintProfile
Request		 DeleteVoiceprintProfile
Response		 Deletes all data associated with the voiceprint profile.
ListEnrollmentSegments ListEnrollmentSegments
Request		 ListEnrollmentSegments
Response		 Enumerates all audio segments in the audio segments collection. List includes both segments, one that are used for a previous train and other segments that are added later (signaled by a flag) and, if available, a biometric consistency indication. Input is a voiceprint profile ID.
RemoveEnrollmentSegment RemoveEnrollmentSegment
Request		 RemoveEnrollmentSegment
Response		 Removes one or more enrollment segments from the enrollment segments collection of the specified voiceprint profile. Accepts a voiceprint profile ID and the list of segments to remove.

Methods with HTTP bindings

CreateVoiceprintProfile

  POST /v1/voiceprints/profiles  

GetGkVoiceprintProfileId

  GET /v1/voiceprints/profiles/gkid  

GetVoiceprintProfileDetails

  GET /v1/voiceprints/profiles  

UpdateVoiceprintProfileDetails

  PATCH /v1/voiceprints/profiles  

ExecuteVoiceprintProfilesStatusJob

  POST /v1/voiceprints/profiles/status  

GetVoiceprintProfilesStatusJobDetails

  GET /v1/voiceprints/profiles/status/{gk_job_id.value}  

LockVoiceprintProfile

  PUT /v1/voiceprints/profiles/{gk_voiceprint_profile_id.value}/attributes/lock  

UnlockVoiceprintProfile

  DELETE /v1/voiceprints/profiles/{gk_voiceprint_profile_id.value}/attributes/lock  

DeleteVoiceprintTemplate

  DELETE /v1/voiceprints/templates/{gk_voiceprint_profile_id.value}  

DeleteVoiceprintProfile

  DELETE /v1/voiceprints/profiles/{gk_voiceprint_profile_id.value}  

ListEnrollmentSegments

  GET /v1/voiceprints/profiles/{gk_voiceprint_profile_id.value}/enrollment-segments  

RemoveEnrollmentSegment

  DELETE /v1/voiceprints/profiles/{gk_voiceprint_profile_id.value}/enrollment-segments/{gk_processed_audio_id.value}  

voiceprints_management_messages.proto

CreateVoiceprintProfileRequest

Input message that defines parameters for CreateVoiceprintProfile.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
CreateVoiceprintProfileRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
owner OwnerAndTag Mandatory. Owner of the print and a mandatory print tag that is used to distinguish between different voiceprint profiles that belong to the same owner. Print owner can be a person or a fraudster.
details VoiceprintProfileDetailsForCreate Optional. Properties that are set when creating a voiceprint profile.
field_mask google.protobuf.FieldMask Optional. A field mask used to specify the CreateVoiceprintProfileRequest fields that the method sets.

CreateVoiceprintProfileResponse

Output message that defines parameters returned by CreateVoiceprintProfile.

CreateVoiceprintProfileResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Optional. Unique ID of the newly created voiceprint profile.

DeleteVoiceprintProfileRequest

Input message that defines parameters for DeleteVoiceprintProfile.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
DeleteVoiceprintProfileRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile.
reason string Optional. Specifies the deletion reason.

DeleteVoiceprintProfileResponse

Output message that defines parameters returned by DeleteVoiceprintProfile.

DeleteVoiceprintProfileResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

DeleteVoiceprintTemplateRequest

Input message that defines parameters for DeleteVoiceprintTemplate.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
DeleteVoiceprintTemplateRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile.

DeleteVoiceprintTemplateResponse

Output message that defines parameters returned by DeleteVoiceprintTemplate.

DeleteVoiceprintTemplateResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

ExecuteVoiceprintProfilesStatusJobRequest

Input message that defines parameters for ExecuteVoiceprintProfilesStatusJob.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
ExecuteVoiceprintProfilesStatusJobRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
owner_type nuance.biosec.v1.OwnerType Mandatory. Voiceprints’ owner type. Can be a person or a fraudster.
filter VoiceprintProfilesStatusFilter Optional. Voiceprint-profiles filter.

ExecuteVoiceprintProfilesStatusJobResponse

Output message that defines parameters returned by ExecuteVoiceprintProfilesStatusJob.

ExecuteVoiceprintProfilesStatusJobResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
gk_job_id nuance.biosec.v1.UniqueId Optional. Unique ID of the job.

GetGkVoiceprintProfileIdRequest

Input message that defines parameters for GetGkVoiceprintProfileId.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetGkVoiceprintProfileIdRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
owner OwnerAndTag Mandatory. Owner of the print and a print tag that is used to distinguish between different voiceprint profiles that belong to the same owner. Print owner can be a person or a fraudster. If a tag is specified, the request returns only one ID. If the tag is null or empty, the request returns all IDs.

GetGkVoiceprintProfileIdResponse

Output message that defines parameters returned by GetGkVoiceprintProfileId.

GetGkVoiceprintProfileIdResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Unique ID of the voiceprint profile.

GetVoiceprintProfileDetailsRequest

Input message that defines parameters for GetVoiceprintProfileDetails.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetVoiceprintProfileDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
One of input:  
Mandatory. The voiceprint profile that the request refers to, specified in two alternative ways.
   gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Unique ID of the existing voiceprint profile.
   owner_and_tag OwnerAndTag Owner of the print and a mandatory print tag that is used to distinguish between different voiceprints profiles that belong to the same owner. Print owner can be a person or a fraudster.
field_mask google.protobuf.FieldMask Optional. A field mask used to specify the VoiceprintProfileDetailsForRead fields that the method reads.

GetVoiceprintProfileDetailsResponse

Output message that defines parameters returned by GetVoiceprintProfileDetails.

GetVoiceprintProfileDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
details VoiceprintProfileDetailsForRead Optional. Voiceprint profile details. Includes both read-only and writable fields.

GetVoiceprintProfilesStatusJobDetailsRequest

Input message that defines parameters for GetVoiceprintProfilesStatusJobDetails.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetVoiceprintProfilesStatusJobDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_job_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the job.

GetVoiceprintProfilesStatusJobDetailsResponse

Output message that defines parameters returned by GetVoiceprintProfilesStatusJobDetails.

GetVoiceprintProfilesStatusJobDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
job_state VoiceprintProfilesStatusJobState Optional. Specifies the current state of the job.
expiration_timestamp google.protobuf.Timestamp Optional. The expiration date and time for the job and its associated results.
download_url string Optional. A URL from which the zip file can be downloaded.

ListEnrollmentSegmentsRequest

Input message that defines parameters for ListEnrollmentSegments.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
ListEnrollmentSegmentsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile.

ListEnrollmentSegmentsResponse

Output message that defines parameters for ListEnrollmentSegments.

ListEnrollmentSegmentsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
enrollment_segments_details repeated EnrollmentSegmentDetails Optional. Additional information about the enrollment segments in the collection.

LockVoiceprintProfileRequest

Input message that defines parameters for LockVoiceprintProfile.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
LockVoiceprintProfileRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile that is locked.
reason string Optional. Specifies the locking reason.

LockVoiceprintProfileResponse

Output message that defines parameters returned by LockVoiceprintProfile.

LockVoiceprintProfileResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

OwnerAndTag

Identifies a voiceprint profile by owner and tag.

OwnerAndTag
Field Type Description
One of owner:  
Mandatory. Print owner, can be a person or a fraudster.
   gk_person_id nuance.biosec.v1.UniqueId Unique person’s ID.
   gk_fraudster_id nuance.biosec.v1.UniqueId Unique fraudster’s ID.
   person_id string The person’s ID. Must be unique at the scope level and used together with a scope ID. Normally specified in the context field.
   fraudster_id string The fraudster’s ID. Must be unique at the scope level and used together with a scope ID. Normally specified in the context field.
tag string Mandatory. Tag used to distinguish between different voiceprint profiles that belong to the same owner.

RemoveEnrollmentSegmentRequest

Input message that defines parameters for RemoveEnrollmentSegment.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
RemoveEnrollmentSegmentRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile.
gk_processed_audio_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the processed audio segment that the method removes from the enrollment segments collection.

RemoveEnrollmentSegmentResponse

Output message that defines parameters returned by RemoveEnrollmentSegment.

RemoveEnrollmentSegmentResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

UnlockVoiceprintProfileRequest

Input message that defines parameters for UnlockVoiceprintProfile.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
UnlockVoiceprintProfileRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the voiceprint profile that is unlocked.

UnlockVoiceprintProfileResponse

Output message that defines parameters returned by UnlockVoiceprintProfile.

UnlockVoiceprintProfileResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

UpdateVoiceprintProfileDetailsRequest

Input message that defines parameters for UpdateVoiceprintProfileDetails.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
UpdateVoiceprintProfileDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
One of input:  
Mandatory. The Voiceprint profile that the request refers to, specified in two alternative ways.
   gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Unique ID of the voiceprint profile.
   owner_and_tag OwnerAndTag Owner of the print and a mandatory print tag that is used to distinguish between different voiceprints profiles that belong to the same owner. Print owner can be a person or a fraudster.
details VoiceprintProfileDetailsForUpdate Mandatory. Voiceprint Profile details that are set. Includes only writable fields.
field_mask google.protobuf.FieldMask Mandatory. A field mask used to specify the VoiceprintProfileDetailsForUpdate fields that the method sets.

UpdateVoiceprintProfileDetailsResponse

Output message that defines parameters returned by UpdateVoiceprintProfileDetails.

UpdateVoiceprintProfileDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

VoiceprintProfileDetailsForCreate

Contains fields that the system uses to create a voiceprint profile. Included in CreateVoiceprintProfileRequest. Fields that are set can be defined by a fieldmask.

VoiceprintProfileDetailsForCreate
Field Type Description
custom_data repeated VoiceprintProfileDetailsForCreate.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

VoiceprintProfileDetailsForCreate.CustomDataEntry

VoiceprintProfileDetailsForCreate.CustomDataEntry
Field Type Description
key string  
value string  

VoiceprintProfileDetailsForRead

Contains the readable fields of the voiceprint profile. Included in GetVoiceprintProfileDetailsResponse. Fields that are read can be defined by a fieldmask.

VoiceprintProfileDetailsForRead
Field Type Description
gk_voiceprint_profile_id nuance.biosec.v1.UniqueId Optional. Unique ID of the voiceprint profile.
gk_owner_id nuance.biosec.v1.UniqueId Optional. Unique ID of the voiceprint profile owner.
owner_type nuance.biosec.v1.OwnerType Optional. Owner type. Can be a person or a fraudster.
tag string Optional. Tag used to distinguish between different voiceprint profiles that belong to the same owner.
version google.protobuf.Int32Value Optional. The current version of the voiceprint profile (incremented each time a print is retrained).
status VoiceprintProfileStatus Optional. Indicates whether the voiceprint profile is trained or not.
near_term_adaptation google.protobuf.BoolValue Optional. Indicates whether adaption is performed or not.
lock_info VoiceprintProfileLockInfo Optional. Lock status.
template_info VoiceprintProfileTemplateInfo Optional. Voiceprint template information.
creation_timestamp google.protobuf.Timestamp Optional. Time and date of the voiceprint profile creation.
modification_timestamp google.protobuf.Timestamp Optional. Time and date of the last update.
custom_data repeated VoiceprintProfileDetailsForRead.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

VoiceprintProfileDetailsForRead.CustomDataEntry

VoiceprintProfileDetailsForRead.CustomDataEntry
Field Type Description
key string  
value string  

VoiceprintProfileDetailsForUpdate

Contains the writable fields of the voiceprint profile. Included in UpdateVoiceprintProfileDetailsRequest. Fields that are updated can be defined by a fieldmask.

VoiceprintProfileDetailsForUpdate
Field Type Description
custom_data repeated VoiceprintProfileDetailsForUpdate.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

VoiceprintProfileDetailsForUpdate.CustomDataEntry

VoiceprintProfileDetailsForUpdate.CustomDataEntry
Field Type Description
key string  
value string  

VoiceprintProfileLockInfo

Contains information about the locking state of a voiceprint profile.

VoiceprintProfileLockInfo
Field Type Description
status nuance.biosec.v1.LockStatus Optional. Specifies whether the print is locked or not.
locked_by string Optional. The user ID of the analyst/agent that locked the print. Relevant only in case of manual lock.
lock_reason nuance.biosec.v1.LockReason Optional. Specifies the locking reason if it is a standard one.
reason string Optional. A text message that specifies the reason if it is not a standard one.
mismatch_counter google.protobuf.Int32Value Optional. The number of consecutive mismatches, used when a voiceprint profile is locked due to too many mismatches.
lock_timestamp google.protobuf.Timestamp Optional. Specifies the voiceprint profile locking time.
auto_unlock_timestamp google.protobuf.Timestamp Optional. The time when the voiceprint profile (if locked) is automatically unlocked.

VoiceprintProfileTemplateInfo

Contains information about the voiceprint profile template. Both fields are not set if the print is not trained.

VoiceprintProfileTemplateInfo
Field Type Description
gk_calibration_model_revision_id nuance.biosec.v1.UniqueId Optional. Unique ID of the calibration model that is used to train the voiceprint profile template.
voice_class_score google.protobuf.FloatValue Optional. A score between 0 and 100 that can be used to categorize voices into classes according to various factors such as timbre, pitch, and so on.
latest_train_timestamp google.protobuf.Timestamp Optional. The most recent training time of the voiceprint profile.

VoiceprintProfilesStatusFilter

Voiceprint-profiles filter.

VoiceprintProfilesStatusFilter
Field Type Description
creation_timestamp_interval google.type.Interval Optional. An absolute time range defined using UTC timestamps start time and end time.