Deviceprint management and processing

This section contains voiceprint management and processing proto files.

Notes:

To download Gatekeeper proto files, click download Gatekeeper proto files.
Default values are determined by the gRPC specification. For more information, go to protocol buffers language guide .

deviceprint/deviceprints_management_service.proto

DeviceprintsManager

This service allows managing deviceprint 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
CreateDeviceprintProfile	CreateDeviceprintProfile Request	CreateDeviceprintProfile Response	Creates a new deviceprint 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 deviceprint profile.
GetGkDeviceprintProfileId	GetGkDeviceprintProfileId Request	GetGkDeviceprintProfileId Response	Returns a deviceprint profile ID that belongs to the specified owner, identified by a tag. The deviceprint profile ID can be used for all other deviceprint operations.
GetDeviceprintProfileDetails	GetDeviceprintProfileDetails Request	GetDeviceprintProfileDetails Response	Returns details for a specific deviceprint profile that can be specified either using a deviceprint 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.
UpdateDeviceprintProfileDetails	UpdateDeviceprintProfileDetails Request	UpdateDeviceprintProfileDetails Response	Update any of the deviceprint profile’s writable attributes. The input is a deviceprint profile (that can be specified either using a deviceprint profile ID or an owner and a tag) and the list of writable attributes that are set.
LockDeviceprintProfile	LockDeviceprintProfile Request	LockDeviceprintProfile Response	Locks a deviceprint 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 deviceprint profile ID. Optionally, you can provide more context information about the locking reason.
UnlockDeviceprintProfile	UnlockDeviceprintProfile Request	UnlockDeviceprintProfile Response	Unlocks a locked deviceprint profile, allowing access to the biometrics system so that it can be used again for authentication. The input is a deviceprint profile ID.
DeleteDeviceprintTemplate	DeleteDeviceprintTemplate Request	DeleteDeviceprintTemplate Response	Deletes the deviceprint profile template created by Train. It can be used to delete the template if it is created using a wrong calibration model.
DeleteDeviceprintProfile	DeleteDeviceprintProfile Request	DeleteDeviceprintProfile Response	Deletes all data associated with the deviceprint 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 deviceprint profile ID.
RemoveEnrollmentSegment	RemoveEnrollmentSegment Request	RemoveEnrollmentSegment Response	Removes one or more enrollment segments from the enrollment segments collection of the specified deviceprint profile. Accepts a deviceprint profile ID and the list of segments to remove.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

CreateDeviceprintProfile

POST /v1/deviceprints/profiles

GetGkDeviceprintProfileId

GET /v1/deviceprints/profiles/gkid

GetDeviceprintProfileDetails

GET /v1/deviceprints/profiles

UpdateDeviceprintProfileDetails

PATCH /v1/deviceprints/profiles

LockDeviceprintProfile

PUT /v1/deviceprints/profiles/{gk_deviceprint_profile_id.value}/attributes/lock

UnlockDeviceprintProfile

DELETE /v1/deviceprints/profiles/{gk_deviceprint_profile_id.value}/attributes/lock

DeleteDeviceprintTemplate

DELETE /v1/deviceprints/templates/{gk_deviceprint_profile_id.value}

DeleteDeviceprintProfile

DELETE /v1/deviceprints/profiles/{gk_deviceprint_profile_id.value}

ListEnrollmentSegments

GET /v1/deviceprints/profiles/{gk_deviceprint_profile_id.value}/enrollment-segments

RemoveEnrollmentSegment

DELETE /v1/deviceprints/profiles/{gk_deviceprint_profile_id.value}/enrollment-segments/{gk_processed_audio_id.value}

deviceprint/deviceprints_processing_service.proto

DeviceprintsProcessor

This service allows performing basic deviceprints operations. Service methods are typically used in self-service applications such as active authentication via the IVR.

Enrollment workflow

Here is a typical Enrollment workflow:

Note:

Do not forget to upload audio using the Media Manager API anytime in the workflow before calling ProcessAudio (step 5).

StartEngagement
StartSession
GetGkDeviceprintProfileId to get the internal ID.
If the deviceprint profile exists, continue to b. If not, create one in step a.
1. CreateDeviceprintProfile
2. GetEnrollStatus - Checks if the deviceprint profile is trained.
ProcessAudio
Enroll - Repeat steps five and six, typically three times, until the deviceprint is ready to be trained.
Train
StopSession
StopEngagement

Verification workflow

Here is a typical verification workflow:

Note:

Do not forget to upload audio using the Media Manager API anytime in the workflow before calling Verify (step 5).

StartEngagement
StartSession
GetGkDeviceprintProfileId to get the internal ID.
GetEnrollStatus - Checks if the deviceprint profile is trained.
Verify
GetSessionDecision
StopSession
StopEngagement

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
ProcessAudio	ProcessAudio Request	ProcessAudio Response	Processes the audio and checks its quality. Creates an audio model identified by gk_processed_audio_id that the system uses in consequent operations such as Enroll or Verify.
Enroll	Enroll Request	Enroll Response	Adds processed audio to the deviceprint’s enrollment segments collection. The system uses the processed audio in this collection when it creates the deviceprint’s template (Train). Accepts a deviceprint profile ID and a processed audio ID returned by the ProcessAudio method. Returns information about the status of the deviceprint, indicating whether it is ready to be trained or not.
GetEnrollStatus	GetEnrollStatus Request	GetEnrollStatus Response	Returns information about the status of the deviceprint, indicating whether it is trained, ready to be trained, or not ready.
Train	Train Request	Train Response	Creates a new voice template for a deviceprint profile using audio (typically audio models) from the enrollment segments collection.
Verify	Verify Request	Verify Response	Checks if a given audio matches the specified deviceprint profile.
Identify	Identify Request	Identify Response	Checks if a given audio matches any of the deviceprint profiles specified. Typically used with a small or medium size group (1-100).
DetectKnownFraudsters	DetectKnownFraudsters Request	DetectKnownFraudsters Response	Checks if a given audio matches any of the deviceprint profiles specified in a watchlist.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

ProcessAudio

POST /v1/audios/process:deviceprints

Processes the audio and checks its quality. Creates an audio model identified by gk_processed_audio_id that the system uses in consequent operations such as [Enroll](#Enroll) or [Verify](#Verify).

For more information, see ProcessAudio.

Endpoint

/v1/audios/process:deviceprints

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_media_segment_id": {
        "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
    },
    "channel_selector": {
        "channel": {
            "value": 1
        }
    }
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "gkMediaSegmentId": {
            "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
        },
        "gkProcessedAudioId": {
            "value": "743c43af-f321-4441-8f26-889111702eff"
        },
        "validity": "REASON_AUDIO_OK",
        "audioDetails": {
            "gkMediaSegmentId": {
                "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
            },
            "gkProcessedAudioId": {
                "value": "743c43af-f321-4441-8f26-889111702eff"
            },
            "channelScores": [
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                    "channelScore": 0.948395967
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                    "channelScore": 0.0514041297
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                    "channelScore": 0.000199887014
                }
            ],
            "grossAudio": "5.640s",
            "netAudio": "3.870s",
            "notSpeech": "1.770s",
            "snrDb": 21.8760834,
            "speechLevel": 4.95740795,
            "saturationLevel": 0,
            "perceptualSpeechQuality": 3.60441,
            "packetLossRate": 12.6025896,
            "mediaNumberOfChannels": 1,
            "mediaSamplingRateHz": 8000,
            "processedAudioNumberOfChannels": 1,
            "processedAudioSamplingRateHz": 8000
        },
        "gkCalibrationModelRevisionId": {
            "value": "cbdffbc5-c7a9-4a70-9685-3e6ad7ed4402"
        }
    }
}

Enroll

POST /v1/deviceprints/{gk_deviceprint_profile_id.value}/enrollment

Adds processed audio to the deviceprint's enrollment segments collection. The system uses the processed audio in this collection when it creates the deviceprint's template ([Train](#Train)). Accepts a deviceprint profile ID and a processed audio ID returned by the [ProcessAudio](#ProcessAudio) method. Returns information about the status of the deviceprint, indicating whether it is ready to be trained or not.

For more information, see Enroll.

Endpoint

v1/deviceprints/{gk_deviceprint_profile_id}/enrollment

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_deviceprint_profile_id": {
        "value": "751b67d1-05e6-4c43-b835-ed496451415f"
    },
    "gk_processed_audio_id": {
        "value": "743c43af-f321-4441-8f26-889111702eff"
    }
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "enrollStatus": "ENROLL_STATUS_TRAIN_POSSIBLE",
        "deviceprintDetails": {
            "gkDeviceprintProfileId": {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            },
            "gkOwnerId": {
                "value": "f33b121f-9b76-4367-83f3-d37ed8c2d454"
            },
            "ownerType": "OWNER_TYPE_PERSON",
            "profileTag": "cp_pm"
        },
        "reason": "ENROLL_REASON_ENROLL_OK",
        "audioDetails": {
            "gkMediaSegmentId": {
                "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
            },
            "gkProcessedAudioId": {
                "value": "743c43af-f321-4441-8f26-889111702eff"
            },
            "channelScores": [
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                    "channelScore": 0.948395967
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                    "channelScore": 0.0514041297
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                    "channelScore": 0.000199887014
                }
            ],
            "selectedChannel": {
                "channel": 1
            },
            "grossAudio": "5.640s",
            "netAudio": "3.870s",
            "notSpeech": "1.770s",
            "snrDb": 21.8760834,
            "speechLevel": 4.95740795,
            "saturationLevel": 0,
            "perceptualSpeechQuality": 3.60441,
            "packetLossRate": 12.6025896,
            "mediaNumberOfChannels": 1,
            "mediaSamplingRateHz": 8000,
            "processedAudioNumberOfChannels": 1,
            "processedAudioSamplingRateHz": 8000
        },
        "enrolled": true
    }
}

GetEnrollStatus

GET /v1/deviceprints/{gk_deviceprint_profile_id.value}/enrollment-status

Train

POST /v1/deviceprints/{gk_deviceprint_profile_id.value}/training

Creates a new voice template for a deviceprint profile using audio (typically audio models) from the enrollment segments collection.

For more information, see Train.

Endpoint

v1/deviceprints/{gk_deviceprint_profile_id}/training

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_deviceprint_profile_id": {
        "value": "751b67d1-05e6-4c43-b835-ed496451415f"
    },
    "return_final_transcription": true
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "trainStatus": "TRAIN_STATUS_TRAINED",
        "reason": "TRAIN_REASON_TRAIN_OK",
        "status": "DEVICEPRINT_PROFILE_STATUS_BASIC_TRAINED",
        "deviceprintDetails": {
            "gkDeviceprintProfileId": {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            },
            "gkOwnerId": {
                "value": "f33b121f-9b76-4367-83f3-d37ed8c2d454"
            },
            "ownerType": "OWNER_TYPE_PERSON",
            "profileTag": "cp_pm",
            "printVersion": 1
        },
        "gkCalibrationModelRevisionId": {
            "value": "cbdffbc5-c7a9-4a70-9685-3e6ad7ed4402"
        },
        "enrollmentSegmentsDetails": [
            {
                "gkMediaSegmentId": {
                    "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
                },
                "gkProcessedAudioId": {
                    "value": "743c43af-f321-4441-8f26-889111702eff"
                },
                "consistencyDecision": "CONSISTENCY_DECISION_UNSPECIFIED",
                "audioDetails": {
                    "gkMediaSegmentId": {
                        "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
                    },
                    "gkProcessedAudioId": {
                        "value": "743c43af-f321-4441-8f26-889111702eff"
                    },
                    "channelScores": [
                        {
                            "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                            "channelScore": 0.948395967
                        },
                        {
                            "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                            "channelScore": 0.0514041297
                        },
                        {
                            "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                            "channelScore": 0.000199887014
                        }
                    ],
                    "grossAudio": "5.640s",
                    "netAudio": "3.870s",
                    "notSpeech": "1.770s",
                    "snrDb": 21.8760834,
                    "speechLevel": 4.95740795,
                    "saturationLevel": 0,
                    "perceptualSpeechQuality": 3.60441,
                    "packetLossRate": 12.6025896,
                    "mediaNumberOfChannels": 1,
                    "mediaSamplingRateHz": 8000,
                    "processedAudioNumberOfChannels": 1,
                    "processedAudioSamplingRateHz": 8000
                },
                "usedForTrain": true
            }
        ],
        "totalSegments": 1,
        "totalValidSegments": 1,
        "minSegmentsRequired": 1,
        "totalNetAudio": "3.870s",
        "minNetAudioRequired": "1s",
        "totalNotSpeech": "1.770s",
        "minNotSpeechRequired": "1s"
    }
}

Verify

POST /v1/deviceprints/{gk_deviceprint_profile_id.value}/verification

Checks if a given audio matches the specified deviceprint profile.

For more information, see Verify.

Endpoint

v1/deviceprints/{gk_deviceprint_profile_id}/verification

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_processed_audio_id": {
        "value": "743c43af-f321-4441-8f26-889111702eff"
    },
    "gk_deviceprint_profile_id": {
        "value": "751b67d1-05e6-4c43-b835-ed496451415f"
    }
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "statusMessage": {
            "locale": "",
            "message": "",
            "messageResourceId": ""
        },
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "deviceprintDetails": {
            "gkDeviceprintProfileId": {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            },
            "gkOwnerId": {
                "value": "f33b121f-9b76-4367-83f3-d37ed8c2d454"
            },
            "ownerType": "OWNER_TYPE_PERSON",
            "profileTag": "cp_pm",
            "printVersion": 1
        },
        "gkMediaSegmentId": {
            "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
        },
        "gkProcessedAudioId": {
            "value": "743c43af-f321-4441-8f26-889111702eff"
        },
        "decision": "DECISION_AUTHENTIC",
        "reason": "DECISION_REASON_DEVICEPRINT_MATCH",
        "authenticationScore": {
            "score": 3.58197331
        },
        "riskEngineResult": {
            "risk": 0,
            "reliability": 99
        },
        "gkCalibrationModelRevisionId": {
            "value": "cbdffbc5-c7a9-4a70-9685-3e6ad7ed4402"
        },
        "audioDetails": {
            "gkMediaSegmentId": {
                "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
            },
            "gkProcessedAudioId": {
                "value": "743c43af-f321-4441-8f26-889111702eff"
            },
            "channelScores": [
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                    "channelScore": 0.948395967
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                    "channelScore": 0.0514041297
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                    "channelScore": 0.000199887014
                }
            ],
            "grossAudio": "5.640s",
            "netAudio": "3.870s",
            "notSpeech": "1.770s",
            "snrDb": 21.8760834,
            "speechLevel": 4.95740795,
            "saturationLevel": 0,
            "perceptualSpeechQuality": 3.60440969,
            "packetLossRate": 12.6025896,
            "mediaNumberOfChannels": 1,
            "mediaSamplingRateHz": 8000,
            "processedAudioNumberOfChannels": 1,
            "processedAudioSamplingRateHz": 8000
        }
    }
}

Identify

POST /v1/deviceprints/identification

Checks if a given audio matches any of the deviceprint profiles specified. Typically used with a small or medium size group (1-100).

For more information, see Identify.

Endpoint

v1/deviceprints/identification

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_deviceprint_profile_ids": {
        "unique_ids": [
            {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            }
        ]
    },
    "gk_processed_audio_id": {
        "value": "743c43af-f321-4441-8f26-889111702eff"
    }
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "statusMessage": {
            "locale": "",
            "message": "",
            "messageResourceId": ""
        },
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "deviceprintDetails": {
            "gkDeviceprintProfileId": {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            },
            "gkOwnerId": {
                "value": "f33b121f-9b76-4367-83f3-d37ed8c2d454"
            },
            "ownerType": "OWNER_TYPE_PERSON",
            "profileTag": "cp_pm",
            "printVersion": 1
        },
        "gkMediaSegmentId": {
            "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
        },
        "gkProcessedAudioId": {
            "value": "743c43af-f321-4441-8f26-889111702eff"
        },
        "decision": "DECISION_AUTHENTIC",
        "reason": "DECISION_REASON_DEVICEPRINT_MATCH",
        "authenticationScore": {
            "score": 3.58197331
        },
        "riskEngineResult": {
            "risk": 0,
            "reliability": 99
        },
        "gkCalibrationModelRevisionId": {
            "value": "cbdffbc5-c7a9-4a70-9685-3e6ad7ed4402"
        },
        "audioDetails": {
            "gkMediaSegmentId": {
                "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
            },
            "gkProcessedAudioId": {
                "value": "743c43af-f321-4441-8f26-889111702eff"
            },
            "channelScores": [
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                    "channelScore": 0.948395967
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                    "channelScore": 0.0514041297
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                    "channelScore": 0.000199887014
                }
            ],
            "grossAudio": "5.640s",
            "netAudio": "3.870s",
            "notSpeech": "1.770s",
            "snrDb": 21.8760834,
            "speechLevel": 4.95740795,
            "saturationLevel": 0,
            "perceptualSpeechQuality": 3.60440969,
            "packetLossRate": 12.6025896,
            "mediaNumberOfChannels": 1,
            "mediaSamplingRateHz": 8000,
            "processedAudioNumberOfChannels": 1,
            "processedAudioSamplingRateHz": 8000
        },
        "deviceprintResults": [
            {
                "gkDeviceprintProfileId": {
                    "value": "751b67d1-05e6-4c43-b835-ed496451415f"
                },
                "authenticationScore": {
                    "score": 3.58197331
                }
            }
        ]
    }
}

DetectKnownFraudsters

POST /v1/deviceprints/known-fraudsters-detection

Checks if a given audio matches any of the deviceprint profiles specified in a watchlist.

For more information, see DetectKnownFraudsters.

Endpoint

v1/deviceprints/known-fraudsters-detection

Request

{
    "context": {
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_engagement_id": {
            "value": "7ad5befc-4c5d-4165-9a06-eef5c82b5727"
        },
        "gk_session_id": {
            "value": "e218dcf8-1065-4947-b2bc-8b47c088c51b"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_deviceprint_profile_ids": {
        "unique_ids": [
            {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            }
        ]
    },
    "gk_processed_audio_id": {
        "value": "743c43af-f321-4441-8f26-889111702eff"
    }
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "statusMessage": {
            "locale": "",
            "message": "",
            "messageResourceId": ""
        },
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "deviceprintDetails": {
            "gkDeviceprintProfileId": {
                "value": "751b67d1-05e6-4c43-b835-ed496451415f"
            },
            "ownerType": "OWNER_TYPE_UNSPECIFIED",
            "profileTag": ""
        },
        "gkMediaSegmentId": {
            "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
        },
        "gkProcessedAudioId": {
            "value": "743c43af-f321-4441-8f26-889111702eff"
        },
        "decision": "DECISION_UNCERTAIN",
        "reason": "DECISION_REASON_NO_SCORES",
        "gkCalibrationModelRevisionId": {
            "value": "cbdffbc5-c7a9-4a70-9685-3e6ad7ed4402"
        },
        "audioDetails": {
            "gkMediaSegmentId": {
                "value": "urn:mm:v2:a7272be1-a8f9-4167-8283-dd787a593d47:0554543f-1737-413f-813a-c600d7ebbaef:1eeffdc9-197f-3080-919c-8558ea813cf2"
            },
            "gkProcessedAudioId": {
                "value": "743c43af-f321-4441-8f26-889111702eff"
            },
            "channelScores": [
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_LANDLINE",
                    "channelScore": 0.948395967
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_MOBILE",
                    "channelScore": 0.0514041297
                },
                {
                    "channelType": "TELEPHONY_CHANNEL_TYPE_VOIP",
                    "channelScore": 0.000199887014
                }
            ],
            "grossAudio": "5.640s",
            "netAudio": "3.870s",
            "notSpeech": "1.770s",
            "snrDb": 21.8760834,
            "speechLevel": 4.95740795,
            "saturationLevel": 0,
            "perceptualSpeechQuality": 3.60440969,
            "packetLossRate": 12.6025896,
            "mediaNumberOfChannels": 1,
            "mediaSamplingRateHz": 8000,
            "processedAudioNumberOfChannels": 1,
            "processedAudioSamplingRateHz": 8000
        },
        "deviceprintResults": [
            {
                "gkDeviceprintProfileId": {
                    "value": "751b67d1-05e6-4c43-b835-ed496451415f"
                }
            }
        ],
        "numberOfPrints": 1
    }
}

deviceprint/deviceprints_management_messages.proto

CreateDeviceprintProfileRequest

Input message that defines parameters for CreateDeviceprintProfile.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

CreateDeviceprintProfileRequest
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 deviceprint profiles that belong to the same owner. Print owner can be a person or a fraudster.
details	DeviceprintProfileDetailsForCreate	Optional. Properties that are set when creating a deviceprint profile.
field_mask	google.protobuf.FieldMask	Optional. A field mask used to specify the CreateDeviceprintProfileRequest fields that the method sets.

CreateDeviceprintProfileResponse

Output message that defines parameters returned by CreateDeviceprintProfile.

CreateDeviceprintProfileResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Optional. Unique ID of the newly created deviceprint profile.

DeleteDeviceprintProfileRequest

Input message that defines parameters for DeleteDeviceprintProfile.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

DeleteDeviceprintProfileRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile.
reason	string	Optional. Specifies the deletion reason.

DeleteDeviceprintProfileResponse

Output message that defines parameters returned by DeleteDeviceprintProfile.

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

DeleteDeviceprintTemplateRequest

Input message that defines parameters for DeleteDeviceprintTemplate.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

DeleteDeviceprintTemplateRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile.

DeleteDeviceprintTemplateResponse

Output message that defines parameters returned by DeleteDeviceprintTemplate.

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

DeviceprintProfileDetailsForCreate

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

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

DeviceprintProfileDetailsForCreate.CustomDataEntry

DeviceprintProfileDetailsForCreate.CustomDataEntry
Field	Type	Description
key	string
value	string

DeviceprintProfileDetailsForRead

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

DeviceprintProfileDetailsForRead
Field	Type	Description
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Optional. Unique ID of the deviceprint profile.
gk_owner_id	nuance.biosec.v1.UniqueId	Optional. Unique ID of the deviceprint 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 deviceprint profiles that belong to the same owner.
version	google.protobuf.Int32Value	Optional. The current version of the deviceprint profile (incremented each time a print is retrained).
status	DeviceprintProfileStatus	Optional. Indicates whether the deviceprint profile is trained or not.
lock_info	DeviceprintProfileLockInfo	Optional. Lock status.
template_info	DeviceprintProfileTemplateInfo	Optional. Deviceprint template information.
creation_timestamp	google.protobuf.Timestamp	Optional. Time and date of the deviceprint profile creation.
modification_timestamp	google.protobuf.Timestamp	Optional. Time and date of the last update.
custom_data	repeated DeviceprintProfileDetailsForRead.CustomDataEntry	Optional. Custom application data in a list of key-value pairs.

DeviceprintProfileDetailsForRead.CustomDataEntry

DeviceprintProfileDetailsForRead.CustomDataEntry
Field	Type	Description
key	string
value	string

DeviceprintProfileDetailsForUpdate

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

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

DeviceprintProfileDetailsForUpdate.CustomDataEntry

DeviceprintProfileDetailsForUpdate.CustomDataEntry
Field	Type	Description
key	string
value	string

DeviceprintProfileLockInfo

Contains information about the locking state of a deviceprint profile.

DeviceprintProfileLockInfo
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 deviceprint profile is locked due to too many mismatches.
lock_timestamp	google.protobuf.Timestamp	Optional. Specifies the deviceprint profile locking time.
auto_unlock_timestamp	google.protobuf.Timestamp	Optional. The time when the deviceprint profile (if locked) is automatically unlocked.

DeviceprintProfileTemplateInfo

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

DeviceprintProfileTemplateInfo
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 deviceprint profile template.
latest_train_timestamp	google.protobuf.Timestamp	Optional. The most recent training time of the deviceprint profile.
perceptual_speech_quality	google.protobuf.FloatValue	Optional. Pesq: a number in range 0-5. 0 means that the audio contains only noise. 5 means perfect quality of speech.
packet_loss_rate	google.protobuf.FloatValue	Optional. Packet loss rate expressed as percentage.

GetDeviceprintProfileDetailsRequest

Input message that defines parameters for GetDeviceprintProfileDetails.

Uses the context field as follows:

gk_engagement_id: Not used
gk_session_id: Not used
gk_scope_id: Mandatory
configset_id: Not used

GetDeviceprintProfileDetailsRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of input:		Mandatory. The deviceprint profile that the request refers to, specified in two alternative ways.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Unique ID of the existing deviceprint profile.
owner_and_tag	OwnerAndTag	Owner of the print and a mandatory print tag that is used to distinguish between different deviceprints 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 DeviceprintProfileDetailsForRead fields that the method reads.

GetDeviceprintProfileDetailsResponse

Output message that defines parameters returned by GetDeviceprintProfileDetails.

GetDeviceprintProfileDetailsResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
details	DeviceprintProfileDetailsForRead	Optional. Deviceprint profile details. Includes both read-only and writable fields.

GetGkDeviceprintProfileIdRequest

Input message that defines parameters for GetGkDeviceprintProfileId.

Uses the context field as follows:

gk_engagement_id: Not used
gk_session_id: Not used
gk_scope_id: Mandatory
configset_id: Not used

GetGkDeviceprintProfileIdRequest
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 deviceprint 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.

GetGkDeviceprintProfileIdResponse

Output message that defines parameters returned by GetGkDeviceprintProfileId.

GetGkDeviceprintProfileIdResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Unique ID of the deviceprint profile.

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_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint 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.

LockDeviceprintProfileRequest

Input message that defines parameters for LockDeviceprintProfile.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

LockDeviceprintProfileRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile that is locked.
reason	string	Optional. Specifies the locking reason.

LockDeviceprintProfileResponse

Output message that defines parameters returned by LockDeviceprintProfile.

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

OwnerAndTag

Identifies a deviceprint 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 deviceprint 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_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint 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.

UnlockDeviceprintProfileRequest

Input message that defines parameters for UnlockDeviceprintProfile.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

UnlockDeviceprintProfileRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile that is unlocked.

UnlockDeviceprintProfileResponse

Output message that defines parameters returned by UnlockDeviceprintProfile.

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

UpdateDeviceprintProfileDetailsRequest

Input message that defines parameters for UpdateDeviceprintProfileDetails.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Not used

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

UpdateDeviceprintProfileDetailsResponse

Output message that defines parameters returned by UpdateDeviceprintProfileDetails.

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

deviceprint/deviceprints_processing_messages.proto

AudioProcessingResult

Contains audio metrics and information about the audio model. Included in ProcessAudioResponse.

AudioProcessingResult
Field	Type	Description
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of the audio used for enrollment (in case only a subset of audio is used, value may be different from the input audio ID).
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio.
validity	AudioValidity	Audio validity status. Indicates invalidity reason in case of invalid audio.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on).
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model that the system uses to create the audio model.

AuthenticationScore

Authentication score for a person’s print, used in Verify or Identify.

AuthenticationScore
Field	Type	Description
score	google.protobuf.FloatValue	Raw score of the comparison between the print and the audio.

DetectKnownFraudstersRequest

Input message that defines parameters for DetectKnownFraudsters.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

DetectKnownFraudstersRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of audio:		Mandatory. The input audio.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of a new media segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio.
One of target:		Mandatory. The set of prints, specified as an array of print IDs or as a watchlist ID and tag.
gk_deviceprint_profile_ids	nuance.biosec.v1.ListOfUniqueId	An array of deviceprint profile IDs.
watchlist	nuance.biosec.v1.UniqueIdAndTag	A watchlist ID and a tag used as a filter to select the right prints, in case the person has more than one print.
channel_selector	nuance.biosec.v1.AudioChannelSelector	Optional. Specifies the processed channel when processing media with multiple channels. This parameter is ignored if the media has a single channel or if the input is gk_processed_audio_id.
ignore_checkpoints	bool	Optional. If true, disable the checkpoints defined in configset (checkpointsForAuthentication and checkpointsForFraudDetection configuration parameters are ignored) to process the whole audio. If false, processing might stop before the end of audio (for example, if a match is found for any of the checkpoints defined).

DetectKnownFraudstersResponse

Output message that defines parameters returned by DetectKnownFraudsters.

DetectKnownFraudstersResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	DetectKnownFraudstersResult	Result of the DetectKnownFraudsters operation.

DetectKnownFraudstersResult

Contains detailed information about the operation’s outcome. Included in DetectKnownFraudsters.

DetectKnownFraudstersResult
Field	Type	Description
deviceprint_details	DeviceprintDetails	General information about the deviceprint profile.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Media ID of the audio used.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio. In case, the system needs to reprocess the audio, a new gk_processed_audio_id is created, even if input audio is specified by gk_processed_audio_id.
decision	nuance.biosec.v1.Decision	Indicates if the given audio matches any of the specified fraudsters deviceprint profiles.
reason	DecisionReason	Reason of the decision.
fraud_detection_score	FraudDetectionScore	The fraud detection scores.
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Level of risk and reliability, computed by the risk engine.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model used.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on).
deviceprint_results	repeated DeviceprintResult	Detailed results for a specific deviceprint profile.
number_of_prints	int32	Number of valid print used for known fraudster detection.

DeviceprintDetails

Contains general information about a single deviceprint profile.

DeviceprintDetails
Field	Type	Description
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Unique ID of the deviceprint profile.
gk_owner_id	nuance.biosec.v1.UniqueId	Unique ID of the person or fraudster that the print belongs to.
owner_type	nuance.biosec.v1.OwnerType	The type of owner (person or fraudster).
profile_tag	string	The profile tag used to label one of the owner’s prints.
print_version	google.protobuf.Int32Value	Print version, incremented each time a print is retrained.

DeviceprintResult

Detailed results of a specific print used in Verify, Identify, and DetectKnownFraudsters.

DeviceprintResult
Field	Type	Description
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Unique ID of the deviceprint profile.
One of score:		The print score.
authentication_score	AuthenticationScore	The person’s print score, used in Verify or Identify.
fraud_detection_score	FraudDetectionScore	The fraudster’s print score, used in DetectKnownFraudsters.

EnrollRequest

Input message that defines parameters for Enroll.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

EnrollRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile for enrollment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of audio that was processed and added to the deviceprint’s enrollment segments collection. The ID is returned by ProcessAudio.

EnrollResponse

Output message that defines parameters returned by Enroll.

EnrollResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	EnrollResult	Enrollment result.

EnrollResult

Contains information about the deviceprint profile and the audio that belongs to the enrollment set. Included in EnrollResponse.

EnrollResult
Field	Type	Description
enroll_status	EnrollStatus	Status of the deviceprint profile after adding the new enrollment segment. Indicates if the deviceprint can or should be trained.
deviceprint_details	DeviceprintDetails	General information about the deviceprint profile.
enrolled	google.protobuf.BoolValue	It is true if audio is added to print, false otherwise.
reason	EnrollReason	In case of failed enrollment, reason of the failure.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on) of the input audio of the EnrollRequest.

EnrollmentSegmentDetails

Contains detailed information about a single enrollment segment that the system uses in the training process. Included in TrainResponse and in ListEnrollmentSegments.

EnrollmentSegmentDetails
Field	Type	Description
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of the media segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio.
consistency_decision	ConsistencyDecision	Indicates whether the segment is consistent or not.
consistency_score	google.protobuf.FloatValue	Biometric consistency score compared to other segments.
used_for_train	google.protobuf.BoolValue	Indicates if the segment is used for training for reasons such as inconsistency, missing model, missing samples, and so on.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on).
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model that the system uses to create the audio model.

FraudDetectionScore

Fraud detection score for a fraudster’s print, used in DetectKnownFraudsters.

FraudDetectionScore
Field	Type	Description
score	google.protobuf.FloatValue	Raw score of the comparison between the print and the audio.

GetEnrollStatusRequest

Input message that defines parameters for GetEnrollStatus. Contains information about whether the deviceprint can or should be trained.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

GetEnrollStatusRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile.

GetEnrollStatusResponse

Output message that defines parameters returned by GetEnrollStatus.

GetEnrollStatusResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	EnrollStatus	The status of the deviceprint profile. Indicates if the deviceprint can or should be trained.
is_trained	google.protobuf.BoolValue	Indicates if the deviceprint is trained and can be used for verification.

IdentifyRequest

Input message that defines parameters for Identify.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

IdentifyRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of audio:		Mandatory. The input audio.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of a new media segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio.
One of target:		Mandatory. The set of prints, specified as an array of print IDs or as a group ID and tag.
gk_deviceprint_profile_ids	nuance.biosec.v1.ListOfUniqueId	An array of deviceprint profile IDs.
group	nuance.biosec.v1.UniqueIdAndTag	A group ID and a tag used as a filter to select the right prints, in case the person has more than one print.
channel_selector	nuance.biosec.v1.AudioChannelSelector	Optional. Specifies the processed channel when processing media with multiple channels. This parameter is ignored if the media has a single channel or if the input is gk_processed_audio_id.
ignore_checkpoints	bool	Optional. If true, disable the checkpoints defined in configset (checkpointsForAuthentication and checkpointsForFraudDetection configuration parameters are ignored) to process the whole audio. If false, processing might stop before the end of audio (for example, if a match is found for any of the checkpoints defined).

IdentifyResponse

Output message that defines parameters returned by Identify.

IdentifyResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	IdentifyResult	Result of the identify operation.

IdentifyResult

Contains detailed information about the operation’s outcome. Included in IdentifyResponse.

IdentifyResult
Field	Type	Description
deviceprint_details	DeviceprintDetails	General information about the deviceprint profile.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Media ID of the audio used.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio. In case the system needs to reprocess the audio, a new gk_processed_audio_id is created, even if input audio is specified by gk_processed_audio_id.
decision	nuance.biosec.v1.Decision	The decision if the given audio matches any of the specified deviceprint profiles.
reason	DecisionReason	The reason for the decision.
authentication_score	AuthenticationScore	Authentication scores.
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Level of risk and reliability, computed by the risk engine.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model used for the identification process.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on).
deviceprint_results	repeated DeviceprintResult	Detailed results for a specific deviceprint profile.

ProcessAudioRequest

Input message that defines parameters for ProcessAudio.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

ProcessAudioRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of input:		Mandatory. Specifies the input audio.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of the new media Segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio segment that is re-processed.
channel_selector	nuance.biosec.v1.AudioChannelSelector	Optional. Specifies the processed channel when processing media with multiple channels. This parameter is ignored if the media has a single channel or if the input is gk_processed_audio_id.

ProcessAudioResponse

Output message that defines parameters returned by ProcessAudio.

ProcessAudioResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	AudioProcessingResult	Audio processing result.

TrainRequest

Input message that defines parameters for Train.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

TrainRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile for training.

TrainResponse

Output message that defines parameters returned by Train.

TrainResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	TrainResult	The result of the train operation.

TrainResult

Contains information about the outcome of the operation and the current status of the deviceprint profile. Included in TrainResponse.

TrainResult
Field	Type	Description
train_status	nuance.biosec.v1.TrainStatus	Specifies the completion status of the train operation.
reason	TrainReason	Specifies the outcome of the train operation and failure reason when applicable.
status	DeviceprintProfileStatus	Indicates whether the deviceprint profile is trained or not.
deviceprint_details	DeviceprintDetails	General information about the deviceprint profile.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model that the system uses to train the template.
total_segments	google.protobuf.Int32Value	Total number of enrollment segments considered in template training.
total_valid_segments	google.protobuf.Int32Value	Number of enrollment segments that are used to create the template.
min_segments_required	google.protobuf.Int32Value	Minimum number of segments required for a successful training.
total_net_audio	google.protobuf.Duration	Total amount of net speech in all valid segments.
min_net_audio_required	google.protobuf.Duration	Minimum amount of net speech required to train a valid template.
enrollment_segments_details	repeated EnrollmentSegmentDetails	Additional information about the enrollment segments that are used for training.
total_not_speech	google.protobuf.Duration	Total amount of net anything but speech, such as noise and silence, in all valid segments.
min_not_speech_required	google.protobuf.Duration	Minimum amount of net anything but speech, such as noise and silence, required to train a valid template.

VerifyRequest

Input message that defines parameters for Verify.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

VerifyRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of audio:		Mandatory. Specifies the audio that is processed.
gk_media_segment_id	nuance.biosec.v1.UniqueId	Unique ID of a new media segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio.
gk_deviceprint_profile_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the deviceprint profile that the method verifies.
channel_selector	nuance.biosec.v1.AudioChannelSelector	Optional. Specifies the processed channel when processing media with multiple channels. This parameter is ignored if the media has a single channel or if the input is gk_processed_audio_id.
ignore_checkpoints	bool	Optional. If true, disable the checkpoints defined in configset (checkpointsForAuthentication and checkpointsForFraudDetection configuration parameters are ignored) to process the whole audio. If false or not defined, processing might stop before the end of audio (for example, if a match is found for any of the checkpoints defined).

VerifyResponse

Output message that defines parameters returned by Verify.

VerifyResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	VerifyResult	Result of the verify operation.

VerifyResult

Contains detailed information about the operation’s result. Included in VerifyResponse.

VerifyResult
Field	Type	Description
deviceprint_details	DeviceprintDetails	General information about the deviceprint profile.
gk_media_segment_id	nuance.biosec.v1.UniqueId	The media ID of the audio segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Unique ID of the processed audio. In case, the system needs to reprocess the audio, a new gk_processed_audio_id is created, even if the input audio is specified by gk_processed_audio_id.
decision	nuance.biosec.v1.Decision	Indicates if the given audio matches the specified deviceprint profile.
reason	DecisionReason	The reason for the decision.
authentication_score	AuthenticationScore	Authentication scores.
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Level of risk and reliability, computed by the risk engine.
gk_calibration_model_revision_id	nuance.biosec.v1.UniqueId	Unique ID of the calibration model that the system used.
audio_details	AudioDetails	General audio metrics (such as gross audio, net audio, SNR, and so on).

deviceprint/deviceprints_common_types.proto

AudioDetails

Information about the audio.

AudioDetails
Field	Type	Description
gk_media_segment_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the Media Segment.
gk_processed_audio_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the audio returned by a processing method.
gross_audio	google.protobuf.Duration	Optional. Amount of gross audio including speech, noise, and silence.
net_audio	google.protobuf.Duration	Optional. Amount of speech.
not_speech	google.protobuf.Duration	Optional. Amount of audio containing anything but speech, such as noise and silence.
snr_db	google.protobuf.FloatValue	Optional. Signal noise ratio, expressed in decibels.
speech_level	google.protobuf.FloatValue	Optional. Audio energy level.
saturation_level	google.protobuf.FloatValue	Optional. Audio saturation level represented as the number of saturated samples in one minute.
perceptual_speech_quality	google.protobuf.FloatValue	Optional. PESQ score: a number in range 0-5. 0 means that the audio contains only noise. 5 means perfect quality of speech.
packet_loss_rate	google.protobuf.FloatValue	Optional. Packet loss rate expressed as percentage.
channel_scores	repeated TelephonyChannelScore	Optional. The telephony channel identification score.
media_number_of_channels	google.protobuf.Int32Value	Optional. Number of audio input channels. Values are 1 for mono and 2 for stereo.
media_sampling_rate_hz	google.protobuf.Int32Value	Optional. Sampling rate of the input audio in Hertz. Can be different from the one used for processing.
selected_channel	nuance.biosec.v1.AudioChannelSelector	Optional. Specifies the processed channel when processing media with multiple channels. This parameter is not set if the media has a single channel.
processed_audio_number_of_channels	google.protobuf.Int32Value	Optional. Number of audio channels in the processed audio. Values are 1 for mono and 2 for stereo.
processed_audio_sampling_rate_hz	google.protobuf.Int32Value	Optional. Sampling rate used for processing the audio. Value is in Hertz and can differ from the value of the input audio.

TelephonyChannelScore

The score of a specific telephony channel.

TelephonyChannelScore
Field	Type	Description
channel_type	TelephonyChannelType	Mandatory. Specifies the channel type to which the score refers to.
channel_score	float	Mandatory. The numeric score that is related to the specific channel type.

AudioValidity

Audio validity and the reason that the segment is not valid (when relevant).

Name	Number	Description
REASON_UNSPECIFIED	0	Use to initialize the fields.
REASON_AUDIO_OK	1	Audio is satisfactory for processing.
REASON_NOT_ENOUGH_SEGMENTS	2	The number of audio segments provided is not enough for processing.
REASON_INVALID_AUDIO	3	Audio format is invalid or not supported.
REASON_AUDIO_TOO_SHORT	4	Audio does not contain the amount of speech required to complete the process.
REASON_AUDIO_TOO_SOFT	5	Audio speech level is lower than the level required to complete the process.
REASON_AUDIO_TOO_LOUD	6	Audio is too loud and causes saturation.
REASON_AUDIO_TOO_NOISY	7	Audio SNR is too low.
REASON_INTERNAL_ERROR	999	An internal error prevented the system from checking if the audio is valid or not.

ConsistencyDecision

Specifies if an enrollment segment used for training is consistent with the other segments in the collection.

Name	Number	Description
CONSISTENCY_DECISION_UNSPECIFIED	0	Audio consistency is not set.
CONSISTENCY_DECISION_CONSISTENT	1	The segment is consistent with other segments in the enrollment segments collection and probably belongs to the same person.
CONSISTENCY_DECISION_INCONSISTENT	2	The segment is inconsistent with other segments in the enrollment segments collection and probably belongs to a different person.

DecisionReason

Deviceprint processing decision reason.

Name	Number	Description
DECISION_REASON_UNSPECIFIED	0	Decision reason is not specified.
DECISION_REASON_AUDIO_OK	1	Audio is valid.
DECISION_REASON_NOT_ENOUGH_SEGMENTS	2	Processing requires more audio segments than provided.
DECISION_REASON_INVALID_AUDIO	3	Audio format is invalid or not supported.
DECISION_REASON_AUDIO_TOO_SHORT	4	Audio does not contain the amount of speech required to complete the process.
DECISION_REASON_AUDIO_TOO_SOFT	5	Audio speech level is lower than the level required to complete the process.
DECISION_REASON_AUDIO_TOO_LOUD	6	Audio is too loud and causes saturation.
DECISION_REASON_AUDIO_TOO_NOISY	7	Audio SNR (Signal to Noise Ratio) is too low.
DECISION_REASON_FRAUDSTER_INDICATION	8	A fraud attempt probably occurred.
DECISION_REASON_DEVICEPRINT_MATCH	9	This is probably the authentic person.
DECISION_REASON_DEVICEPRINT_NO_MATCH	10	This is probably not the authentic person.
DECISION_REASON_LOW_RELIABILITY	11	The system could not reach a reliable decision.
DECISION_REASON_NO_RISK_DETECTED	12	Risk was not detected.
DECISION_REASON_NO_SCORES	13	No available scores.
DECISION_REASON_INTERNAL_ERROR	999	An error occurred while making the decision.

DeviceprintProfileStatus

Deviceprint profile status.

Name	Number	Description
DEVICEPRINT_PROFILE_STATUS_UNSPECIFIED	0	Deviceprint profile status is not set.
DEVICEPRINT_PROFILE_STATUS_NOT_TRAINED	1	Deviceprint is not trained.
DEVICEPRINT_PROFILE_STATUS_BASIC_TRAINED	2	Deviceprint is trained but can be improved using additional enrollment audio.
DEVICEPRINT_PROFILE_STATUS_OPTIMAL_TRAINED	3	Deviceprint is trained with an optimal amount of audio.

EnrollReason

Enroll operation result.

Name	Number	Description
ENROLL_REASON_UNSPECIFIED	0	Value is not set.
ENROLL_REASON_INTERNAL_ERROR	1	An internal error prevented the system from completing the operation.
ENROLL_REASON_ENROLL_OK	2	Enroll completed successfully.
ENROLL_REASON_TOO_SHORT	3	Audio does not contain the amount of speech required to complete the process.
ENROLL_REASON_MISSING_MODEL	4	Audio has not a valid audio model.
ENROLL_REASON_ALREADY_ADDED	5	Audio is already added to the print
ENROLL_REASON_WRONG_PRINT_TYPE	6	Audio was processed for a different type of print

EnrollStatus

Specifies if the enrollment segments collection of a print allows the system to train the print successfully.

Name	Number	Description
ENROLL_STATUS_UNSPECIFIED	0	Enroll status is not set.
ENROLL_STATUS_TRAIN_NOT_POSSIBLE	1	Minimal requirements for training are not met.
ENROLL_STATUS_TRAIN_POSSIBLE	2	Minimum requirements for training are met, but Nuance recommends adding more audio.
ENROLL_STATUS_TRAIN_SUGGESTED	3	Optimal training requirements are met.
ENROLL_STATUS_FULL	4	Too many segments are added and it is not possible to add more.

TelephonyChannelType

The telephony channels that are currently supported.

Name	Number	Description
TELEPHONY_CHANNEL_TYPE_UNSPECIFIED	0	Telephony channel is not specified.
TELEPHONY_CHANNEL_TYPE_LANDLINE	1	Landline call.
TELEPHONY_CHANNEL_TYPE_MOBILE	2	Mobile call.
TELEPHONY_CHANNEL_TYPE_VOIP	3	VOIP call.

TrainReason

Train operation result.

Name	Number	Description
TRAIN_REASON_UNSPECIFIED	0	Train status is not set.
TRAIN_REASON_TRAIN_OK	1	Train completed successfully.
TRAIN_REASON_INCONSISTENCY	2	Train failed due to inconsistent audio segments (Segments seem to belong to different devices).
TRAIN_REASON_NOT_READY_TO_TRAIN	3	Train failed because the number of segments in the enrollment segments collection is too small, or because the segments do not contain enough usable audio.
TRAIN_REASON_INTERNAL_ERROR	999	An internal error prevented the system from completing the operation.